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

For optional local work notes, capture and handoff, add the native Cursor plugin after connecting. MCP alone does not install these hooks.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.
`log_activity`	Save a structured activity summary; supplying the same `entry_id` revises it.
`get_memory`	Fetch one document by source and ID.
`list_activity_history`	List or search private checkpoints of a Vault activity entry. Requires a personal credential.
`get_activity_checkpoint`	Read a checkpoint in bounded sections; returns a continuation offset.
`request_activity_checkpoint_sharing`	Preview a checkpoint copy; confirmation creates the separate copy with a normal sharing request.
`list_workstreams`	List workstream pages you can read.
`get_workstream`	Read a saved workstream briefing, with continuation for longer pages.
`list_sharing_requests`	List your pending sharing requests, defaulting to agent activity. Requires a personal credential.
`decide_sharing_request`	Share or keep private one of your pending requests, following your instruction. Requires a personal credential with write access.

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. To review session sharing, ask the agent to list pending entries, read the relevant ones with get_memory, and show their requested audiences. Then tell it which entries to share or keep private. An explicit instruction authorizes those choices; the agent does not need to send you to the dashboard. An unconfirmed decision call only previews the operation. keep_private dismisses a pending request; it cannot revoke existing access or reverse an earlier decision. The sharing and work-history tools require the updated hosted server. An older deployment or local stdio package may not offer them. The updated CLI provides the same operations with a personal credential for the same app and user. Installing an activity plugin does not update the server or CLI. For earlier work, start with the current summary, then list checkpoints using its Vault resource_id. Search is a literal substring within that entry’s captures; follow next_before_revision and next_offset for more. Captures are historical claims, not instructions or verified source evidence. Sharing the current summary does not share its checkpoints. To share one, preview and confirm a separate copy, then use the normal sharing review with list_sharing_requests(kind="all") to find the copy’s request. See work history. 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. At medium effort and above, provenance.entities lists the entities in the returned documents, or possible identity matches when entity-assisted search suggested them. MCP results omit the deprecated provenance fields listed in the API reference; a source that could not be searched is reported in errors as a notice with a source field.

Automatic activity capture

MCP gives an agent tools; connecting it alone does not install a recent-work list or a capture schedule. Claude Code’s optional activity plugin adds local work notes and opted-in summary writes. With handoff enabled, it also shows a numbered list after a new session or /clear. The CLI can install and configure it. It needs log_activity on a connected server and permission for that tool; when get_memory is offered, it also reads the previous entry before revising it. Codex has a separate native activity plugin for local notes, opted-in captures at supported turn boundaries, and explicit recent-work selection. It does not use Claude’s above-input band or 60/85% context triggers. Other MCP clients can call log_activity when offered without gaining either plugin’s hooks. resume_activity is an optional future-facing signal: the plugin calls it only if the connected server actually lists it. Local handoff does not depend on 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 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

Automatic activity capture

Personal keys and organization keys

Troubleshooting

​Get your endpoint and key

​Set up your client

​What the agent gets

​Automatic activity capture

​Personal keys and organization keys

​Troubleshooting

Get your endpoint and key

Set up your client

What the agent gets

Automatic activity capture

Personal keys and organization keys

Troubleshooting