> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Get started with TopK Context Engine using MCP server.

The TopK MCP server lets any MCP-compatible AI agent query your datasets using natural language. Once connected, your agent can:

* **List datasets** — discover what data is available
* **Ask questions** — query datasets with natural language and get grounded answers

<Info>
  **Prerequisites**

  * TopK account ([Sign up here](https://console.topk.io/login))
  * TopK API key ([Get API key here](https://console.topk.io/api-key))
</Info>

## Authentication

To authenticate with the MCP server, you need to provide your `TOPK_API_KEY`.

<Tip>
  Get your API key [here](https://console.topk.io/api-key).
</Tip>

## Setup

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="aws-us-east-1-elastica" icon="flower-2">
        ```bash theme={null}
        claude mcp add --transport http topk https://elastica.api.topk.io/mcp \
        --header "Authorization: Bearer <your-topk-api-key>"
        ```
      </Step>

      <Step title="aws-eu-central-1-monstera" icon="clover">
        ```bash theme={null}
        claude mcp add --transport http topk https://monstera.api.topk.io/mcp \
        --header "Authorization: Bearer <your-topk-api-key>"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="aws-us-east-1-elastica" icon="flower-2">
        ```bash theme={null}
        codex mcp add topk --url https://elastica.api.topk.io/mcp --bearer-token-env-var TOPK_API_KEY
        ```
      </Step>

      <Step title="aws-eu-central-1-monstera" icon="clover">
        ```bash theme={null}
        codex mcp add topk --url https://monstera.api.topk.io/mcp --bearer-token-env-var TOPK_API_KEY
        ```
      </Step>
    </Steps>

    <Warning>
      You need to set the `TOPK_API_KEY` environment variable that **Codex** will use in the
      Authorization header.
    </Warning>
  </Tab>

  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open Developer Settings">
        Go to Settings → Developer -> Edit Config.

        <Info>
          Make sure you have **Developer Mode** enabled in Claude Desktop.
        </Info>

        <Frame>
          <img src="https://mintcdn.com/topk/FdVZp-R1uyhc2rlS/images/claude-desktop-developer-settings.png?fit=max&auto=format&n=FdVZp-R1uyhc2rlS&q=85&s=48d964d0d88fdebf1f68f6cccdd190f6" alt="Claude Desktop Developer Settings" width="2190" height="1396" data-path="images/claude-desktop-developer-settings.png" />
        </Frame>
      </Step>

      <Step title="Open Config File">
        Open your Claude Desktop JSON config file:

        <Frame>
          <img src="https://mintcdn.com/topk/FdVZp-R1uyhc2rlS/images/claude-desktop-config-json.png?fit=max&auto=format&n=FdVZp-R1uyhc2rlS&q=85&s=f48b9b35ddd82fded7963e0cdeb3eb05" alt="Claude Desktop Config File" width="1536" height="1068" data-path="images/claude-desktop-config-json.png" />
        </Frame>
      </Step>

      <Step title="Add TopK MCP">
        Add the following under `mcpServers` and provide your API key:

        <CodeGroup>
          ```json aws-us-east-1-elastica theme={null}
          {
            "mcpServers": {
              "topk": {
                "command": "npx",
                "args": [
                  "-y",
                  "mcp-remote",
                  "https://elastica.api.topk.io/mcp",
                  "--header",
                  "Authorization: Bearer ${TOPK_API_KEY}"
                ],
                "env": {
                  "TOPK_API_KEY": "your-api-key-here"
                }
              }
            }
          }
          ```

          ```json aws-eu-central-1-monstera theme={null}
          {
            "mcpServers": {
              "topk": {
                "command": "npx",
                "args": [
                  "-y",
                  "mcp-remote",
                  "https://monstera.api.topk.io/mcp",
                  "--header",
                  "Authorization: Bearer ${TOPK_API_KEY}"
                ],
                "env": {
                  "TOPK_API_KEY": "your-api-key-here"
                }
              }
            }
          }
          ```
        </CodeGroup>

        <Info>
          Make sure you have **Node.js** installed with version **20** or **higher**.
        </Info>
      </Step>

      <Step title="Restart Claude Desktop">
        Restart Claude Desktop to apply the changes.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    Add the following to `~/.cursor/mcp.json`:

    <CodeGroup>
      ```json aws-us-east-1-elastica theme={null}
      {
        "mcpServers": {
          "topk-elastica": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote",
              "https://elastica.api.topk.io/mcp",
              "--header",
              "Authorization: Bearer ${TOPK_API_KEY}"
            ],
            "env": {
              "TOPK_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```

      ```json aws-eu-central-1-monstera theme={null}
      {
        "mcpServers": {
          "topk-monstera": {
            "command": "npx",
            "args": [
              "-y",
              "mcp-remote",
              "https://monstera.api.topk.io/mcp",
              "--header",
              "Authorization: Bearer ${TOPK_API_KEY}"
            ],
            "env": {
              "TOPK_API_KEY": "your-api-key-here"
            }
          }
        }
      }
      ```
    </CodeGroup>

    Restart Cursor to apply the changes.
  </Tab>
</Tabs>

<Info>
  TopK MCP server is **region-specific**. See available regions [here](/regions).
</Info>

## Available tools

Once connected, your agent will have access to `list_datasets` and `ask` tools.

Agents typically follow this flow:

1. Call `list_datasets` to discover what datasets are available
2. Select one or more relevant datasets
3. Call `ask` with a natural language query and the selected datasets

### `list_datasets`

Lists all available datasets in your TopK project. The agent should call this first to discover what data is available before answering any data-related questions.

### `ask`

Queries one or more datasets using natural language and returns a grounded answer.

These ask modes are supported:

* **auto** *(default)* — chooses the best mode based on the provided query
* **summarize** — gathers information from the datasets and returns a concise answer
* **research** — multi-step search and reasoning, best for analytical or comparative questions