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. It usually signs in with your account, but can also use an API key. For ChatGPT, see ChatGPT.

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. Each endpoint also exists with a /personal suffix, for example https://api.hyperspell.com/mcp/personal. It serves the same tools but only accepts sign-in, never an API key; it exists so that Claude users can keep a personal connector next to a company-wide one, as described in Claude. Clients that authenticate with an API key use the plain endpoint.

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_workstreams`	List workstream pages you can read.
`get_workstream`	Read a saved workstream briefing, with continuation for longer pages.

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. Use list_workstreams to find saved briefings, then get_workstream with a returned workstream_id. Follow next_cursor for longer pages. Reads use your current page access and do not generate or refresh a briefing. Very High ask and search results include retrieval provenance. Each turn groups its tool calls with a provider reasoning summary when available. Tool queries, statuses, and result counts show the actions and outcomes. New queries leave the legacy step explanation field empty.

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 finds no results. Ask it to check list_apps for the active app and list_connections for your connected accounts, then try search. If a source is missing or still syncing, 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