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

# MCP clients

> Connect Claude Code, Codex, Cursor, or any other agent that speaks the Model Context Protocol.

Hyperspell runs a server that speaks the Model Context Protocol, or MCP. Any agent that supports MCP can connect to it and gain the same tools Claude and ChatGPT use: ask the brain a question, search it, read its compiled pages, or save a note into it. This page covers agents that authenticate with an API key, which includes coding agents such as Claude Code, Codex, and Cursor, as well as desktop apps and cloud agents.

For Claude on the web or desktop, use the [Claude connector](/agents/claude) instead. For ChatGPT, see [ChatGPT](/agents/chatgpt). Neither of those can send an API key, so they sign in with your account.

## Get your endpoint and key

Open the dashboard, go to Settings, then Connect Agents, and choose MCP clients. Everything you need is on that screen, pre-filled with an API key created for you.

<Frame caption="The MCP clients setup in the dashboard">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/hyperspell/images/agents/mcp-setup.png" alt="The Connect via MCP dialog with Cursor, Claude Code, and Other tabs and a generated API key" />
</Frame>

Two things worth knowing about that key:

* It is personal. It is tied to your account and lets the agent see what you see. Treat it like a password.
* It is created once and reused. Reopening the dialog shows the same key. You can revoke it under Settings, Connect Agents, API Keys at any time, and create a new one.

The endpoint depends on your region:

| Region                  | MCP endpoint                                                   |
| ----------------------- | -------------------------------------------------------------- |
| United States (default) | `https://api.hyperspell.com/mcp`                               |
| European Union          | `https://api.eu.hyperspell.com/mcp`                            |
| Dedicated instance      | The URL shown in your dashboard, specific to your organization |

If your organization runs on a dedicated Hyperspell instance, the shared endpoints above will not know your organization. Always copy the URL from the dashboard.

## Set up your client

<Tabs>
  <Tab title="Cursor">
    Click Add to Cursor in the dashboard. Cursor opens and asks you to confirm the new server, already configured with your key.

    If the button does nothing, or you prefer to edit the file yourself, add this to your `mcp.json` (in `.cursor/mcp.json` for a project or `~/.cursor/mcp.json` globally):

    ```json theme={null}
    {
      "mcpServers": {
        "hyperspell": {
          "url": "https://api.hyperspell.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    The dashboard shows this snippet with your real key filled in, so you can copy it directly.
  </Tab>

  <Tab title="Claude Code">
    Run the command shown in the dashboard. It has this shape:

    ```bash theme={null}
    claude mcp add --transport http hyperspell https://api.hyperspell.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    Claude Code adds the server to your configuration. Run `claude mcp list` to confirm it shows up, then start a session and ask something about your company.

    <Tip>
      If you also install the [command line tool](/agents/cli), it registers Hyperspell with Claude Code for you and adds a short note to your `CLAUDE.md` telling Claude Code when to consult the brain.
    </Tip>
  </Tab>

  <Tab title="Codex">
    Add the server to `~/.codex/config.toml` and put your key in an environment variable:

    ```toml theme={null}
    [mcp_servers.hyperspell]
    url = "https://api.hyperspell.com/mcp"
    bearer_token_env_var = "HYPERSPELL_API_KEY"
    ```

    ```bash theme={null}
    export HYPERSPELL_API_KEY="YOUR_API_KEY"
    ```

    Restart Codex to pick up the change.
  </Tab>

  <Tab title="Other clients">
    Any client that supports remote MCP servers over HTTP can connect. You need two values:

    * Server URL: `https://api.hyperspell.com/mcp` (or the EU endpoint).
    * An `Authorization` header with the value `Bearer YOUR_API_KEY`.

    Where your client asks for a transport, choose HTTP or Streamable HTTP. Hyperspell does not support the older SSE-only transport or stdio.
  </Tab>
</Tabs>

## What the agent gets

Once connected, the agent sees these tools. It chooses among them based on what you ask, so you rarely need to name them.

| Tool         | What it does                                                |
| ------------ | ----------------------------------------------------------- |
| `ask`        | Ask the brain a question. Returns an answer with citations. |
| `search`     | Find documents matching a query, ranked, without an answer. |
| `remember`   | Write a note or document into the brain.                    |
| `get_memory` | Fetch one document by source and ID.                        |

Results are compact by default: an answer plus its citations, or a list of documents plus their summaries. Agents can ask for the full document when they need it.

## Personal keys and organization keys

The key from Connect Agents acts as you. That is what you want for an agent you use yourself.

For an agent that serves the whole team, such as an internal bot, an admin can create an organization-wide key under Settings, API Keys. That key sees content shared with everyone and nobody's personal data. See [Permissions](/core/permissions) for the difference and [Configuration](/advanced/configuration#api-keys) for creating keys.

## Troubleshooting

**The agent lists the server but every call fails with an authentication error.** Check that the header reads `Bearer` followed by a space and the key, and that the key has not been revoked in the dashboard.

**The agent connects but says the brain is empty.** Run `brain_status`, or ask the agent to. If your tools are still syncing, the brain fills in over the next minutes to hours. If a source is missing, check its connection in Settings.

**I am in the EU region and get a not-found error.** Use `https://api.eu.hyperspell.com/mcp`. Keys are region-specific, and the US endpoint will not accept an EU key.