# 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**.

 ![Voyager MCP Server page on the Settings tab with a Stopped status badge, an Off/On toggle in the Off position, an empty Endpoint field showing the placeholder Start server to generate, and the Server configuration section expanded to show the default Port 9090 and Bind interface localhost (127.0.0.1)](https://aerospike.com/docs/_astro/mcp_server_stopped.CeFC7Ygl_1AwqOM.png)

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.

 ![Voyager MCP Server page on the Settings tab with a green Running on port:9090 badge next to the title, the Off/On toggle in the On position, the Endpoint field populated with http://127.0.0.1:9090/mcp, and the Server configuration section showing Port 9090 and Bind interface localhost (127.0.0.1)](https://aerospike.com/docs/_astro/mcp_server_running.Y6Vz1Eq5_ZQXtKS.png)

## 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:

```json
{

  "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:

```json
{

  "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](https://zed.dev/docs/ai/mcp) 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:**

Terminal window

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

**OpenAI Codex CLI:**

Terminal window

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

**Google Gemini CLI:**

Terminal window

```bash
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](https://aerospike.com/docs/database/tools/voyager/mcp/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’”