MCP server setup

This guide walks through starting Aerospike Voyager’s MCP server and connecting your AI coding agent to it.

Prerequisites

• Voyager installed and running.
• At least one Aerospike cluster connection saved and connected in Voyager.

Start the MCP server

The MCP server does not start automatically when Voyager launches. You must turn it on from the MCP Server page each time you want AI coding agents to connect.

1. Open Voyager.
2. Click MCP Server in the sidebar.
3. On the Settings tab, confirm the bind interface (default: localhost (127.0.0.1)) and port (default: 9090). The default address is localhost:9090.
4. Toggle the MCP Server switch to On.

When the server starts, the title-bar badge changes to Running on port:9090, the toggle moves to the On position, and the Endpoint field populates with the URL your AI coding agent should connect to (for example, http://127.0.0.1:9090/mcp). The Statistics tab shows live request counts and connected client information.

Token authentication

Token authentication is optional but recommended. Tokens are encrypted at rest with AES-256-GCM. Tokens can only be generated, revoked, or viewed when the MCP server is stopped.

1. Toggle the MCP server Off if it is running.
2. On the Settings tab, click Generate Token.
3. Copy the token immediately. It is shown only once and cannot be retrieved later.
4. If you lose the token, revoke it and generate a new one.

The current token status (present, absent, or revoked) is shown alongside the generate and revoke actions.

Configure your AI coding agent

The MCP Server page in Voyager generates ready-to-copy snippets for both file-based and CLI-based clients. Most editors that support MCP accept the same JSON block — paste it into the editor’s MCP config file. CLI agents take a single mcp add command.

JSON configuration

Most MCP-compatible editors (Cursor, VS Code, Claude Desktop, IntelliJ, Zed) accept the following block:

{
  "mcpServers": {
    "aerospike-voyager": {
      "type": "http",
      "url": "http://127.0.0.1:9090/mcp"
    }
  }
}

If you generated a token, add an Authorization header and replace YOUR_TOKEN_HERE with the token you copied:

{
  "mcpServers": {
    "aerospike-voyager": {
      "type": "http",
      "url": "http://127.0.0.1:9090/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Where to paste it

Editor	Location
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
VS Code	.vscode/mcp.json (workspace), or Settings → MCP
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS); see Claude Desktop docs for Windows/Linux paths
IntelliJ AI Assistant	Settings → Tools → AI Assistant → MCP

Zed uses a different schema (context_servers rather than mcpServers) — see the Zed MCP documentation for the exact format. The transport URL http://127.0.0.1:9090/mcp is the same.

CLI tools

For CLI agents, run the matching mcp add command in your terminal.

Claude Code:

claude mcp add --transport http aerospike-voyager http://127.0.0.1:9090/mcp

OpenAI Codex CLI:

codex mcp add aerospike-voyager --url http://127.0.0.1:9090/mcp

Google Gemini CLI:

gemini mcp add --transport http aerospike-voyager http://127.0.0.1:9090/mcp

If token auth is enabled, see each CLI’s documentation for attaching the Bearer token.

Other MCP clients

For any MCP-compatible client, use the Streamable HTTP transport at http://127.0.0.1:9090/mcp. If token auth is enabled, include the token as Authorization: Bearer <token>.

Choose an access profile

Voyager offers two access profiles:

• All tools enabled (default): All tools available. Use during active development when you need read and write capabilities.
• Browse and read only: Browse and read operations only. Excludes write, delete, and info commands. Use for safe exploration and schema discovery.

Switch profiles on the MCP Server page. See Access profiles for details.

Test the connection

After configuring your agent, ask it to run list_namespaces as a smoke test. All data tools require a connectionId, so ask the agent to call list_connections first to discover the connection ID of the cluster you want to explore, then pass that ID to list_namespaces. If it returns your namespace list, the connection is working.

Example prompts to try

Once connected, try these prompts with your AI agent:

• “List all namespaces and sets in my cluster”
• “Show me the schema of the sample_users set”
• “Find all records in sample_orders where the total is greater than 100”
• “Create a new record in the test namespace with key ‘user123’”