MCP clients

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 instead. For ChatGPT, see 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.

The Connect via MCP dialog with Cursor, Claude Code, and Other tabs and a generated API key — The MCP clients setup in the dashboard

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

Cursor
Claude Code
Codex
Other clients

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

{
  "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.

Run the command shown in the dashboard. It has this shape:

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.

If you also install the command line tool, 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.

Add the server to ~/.codex/config.toml and put your key in an environment variable:

[mcp_servers.hyperspell]
url = "https://api.hyperspell.com/mcp"
bearer_token_env_var = "HYPERSPELL_API_KEY"

export HYPERSPELL_API_KEY="YOUR_API_KEY"

Restart Codex to pick up the change.

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.

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.
`list_memories`	Page through indexed documents, optionally by source.
`list_context`, `read_context`, `grep_context`	List, read, and keyword-search the compiled pages about your company, projects, and people. These read from the server, so no local sync is needed.
`list_connections`, `list_integrations`	See which tools are connected for you and which are available.
`describe_source`, `resolve_name`, `query_source`	Query a connected tool live through its own API, for data that changes by the minute.
`brain_status`	Report what the brain contains and how to use it.
`delete_memory`, `revoke_connection`	Remove a memory or disconnect a tool. Both ask for confirmation.

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 for the difference and Configuration 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.

Setup

Connecting Agents

Advanced Usage

Resources

Get your endpoint and key

Set up your client

What the agent gets

Personal keys and organization keys

Troubleshooting

​Get your endpoint and key

​Set up your client

​What the agent gets

​Personal keys and organization keys

​Troubleshooting

Get your endpoint and key

Set up your client

What the agent gets

Personal keys and organization keys

Troubleshooting