Model Context Protocol

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard from Anthropic that lets AI apps connect to external data and tools. It splits the world into clients — AI apps like Claude Desktop, Claude Code, and Cursor — and servers, which expose tools and data to those clients. Hyperspell ships an MCP server so any MCP-capable agent can query and write to your company brain. You don’t build any MCP plumbing — you point your client at Hyperspell and the brain shows up as a handful of tools.

Two ways to connect

	Hosted (remote)	Local (sync daemon)
Transport	Streamable HTTP at `https://api.hyperspell.com/mcp`	stdio, on your machine
Install	None — point your client at the URL	Runs via the Hyperspell sync daemon (below)
Best for	Claude Desktop connectors, Cursor, Claude Code, web agents, CI	A machine that already syncs a local copy of the brain
Extra	—	Reads the brain summary off disk, offline, with no API call

Both render the same tools — an agent’s expectations transfer between them. The only difference is where the standing brain summary is read from: the hosted server serves it straight from Hyperspell (no daemon, no sync), while the local server runs via the sync daemon and reads the daemon-synced copy off disk.

Tools

Every Hyperspell MCP server exposes the core brain tools:

Tool	What it does
`ask`	Ask a question and get a synthesized, cited answer drawn from everything connected.
`search`	Retrieve ranked source documents for a query — no synthesis. The composable primitive.
`remember`	Write a note or document into the brain so future queries surface it.
`list_context`	List the standing brain-summary files (company, workstreams, personal).
`read_context`	Read one summary file by its relative path.
`grep_context`	Keyword-search across the summary.
`list_memories`	List indexed documents (one page); filter by source or status.
`list_connections`	List the integrations connected for this user.
`brain_status`	Report identity, summary freshness, and how to use the brain.

Plus management tools for inspecting and administering the brain:

Tool	What it does
`list_apps`	See which apps (workspaces) your login can target, and which is active.
`use_app`	Switch which of your apps subsequent calls target. Sticky across sessions; only apps you already have access to.
`get_memory`	Fetch one indexed document by source and resource id.
`list_integrations`	List the integrations configured for the app.
`generate_brain`	Rebuild the synthesized company-brain context tree (async, non-destructive).
`delete_memory`	Permanently delete a memory. Guarded — returns a preview unless called with `confirm=true`.
`revoke_connection`	Revoke an integration connection and purge that user’s data for it. Guarded.
`get_brain_config` / `set_brain_config` / `reset_brain_config`	Read or change how the brain generates — structure, prompts, source weights. Mutations are guarded.

Guarded tools never act on the first call: without confirm=true they return a preview of what would change, so an agent can show it to you and only proceed once you approve. They also carry MCP destructiveHint annotations, so clients like Claude ask for permission before running them at all. It also provides one prompt, ask_brain, that scaffolds a brain query for the client.

Tuning how hard the brain works

ask and search both take an effort dial that decides how much compute retrieval spends on a single query. It’s the same tier set the REST API’s effort field uses, and it ships in the tool schema as an enum, so an agent can pick a tier without being told.

Effort	What runs	Reach for it when
`minimal`	Verbatim single-shot retrieval, no LLM hop	Direct lookups; fastest and cheapest
`low`	An LLM rewrites the query and extracts date filters first	The literal wording won’t match how the answer is phrased
`medium`	Rewrite + agentic refinement loop (up to 3 extra rounds)	Normal questions — the `ask` default
`high`	Rewrite + extended refinement (up to 6 rounds)	Hard, multi-hop questions worth the latency
`very_high`	Multi-tool agent that can also search live sources	Research-grade questions; can take minutes

ask defaults to medium and search to minimal. Higher tiers mean better recall at more latency and cost.

Results are compact by default — ask returns {answer, citations, errors, query_id} and search returns citation-sized documents, so a multi-MB Slack or Granola thread doesn’t blow up your agent’s context. Pass full=true on ask/search for the raw payload.

The *_context tools read the standing brain summary — the pre-synthesized document tree — so an agent can read the summary first and only reach for ask/search for what it doesn’t cover. On the hosted server they serve the summary straight from Hyperspell (no daemon, no sync); on the local server they read the daemon-synced copy off disk, offline, with no API call, and additionally expose it as hyperbrain://context resources.

Hosted server

The hosted server is mounted on the Hyperspell API at:

https://api.hyperspell.com/mcp

It speaks MCP Streamable HTTP and authenticates as an OAuth 2.1 Resource Server — it validates the token on every request and scopes the call to your app and user. There are two ways to authenticate: log in (OAuth, user-scoped) or an API key (app-scoped).

Connect from Claude (log in — recommended)

Add Hyperspell as a custom connector in Claude — no API key required:

In claude.ai (or Claude Desktop), open Settings → Connectors → Add custom connector.
Enter https://api.hyperspell.com/mcp and click Add.
Claude opens a Hyperspell login — sign in with your Hyperspell dashboard account and approve the connection.

The connection is user-scoped: queries, writes, and connection management all act as you, within your workspace. User-scoped tools like list_connections and revoke_connection work out of the box.

On Claude Team and Enterprise plans the flow is two-phase, and no login happens at the admin’s add step — that’s normal:

Workspace Owner (once): Organization settings → Connectors → Add → Custom → Web → enter the URL above (organizations using pre-shared OAuth credentials add them under Advanced settings).
Each member: Customize → Connectors → find the connector (labeled “Custom”) → click Connect → the Hyperspell login opens here, per member.

Connect from ChatGPT (log in)

ChatGPT connects to the same hosted server as a custom MCP connector, with an OAuth sign-in — no API key required. Custom connectors sit behind ChatGPT’s developer mode, so there are two settings to flip before the connector exists:

Turn on developer mode. On a personal plan it’s in ChatGPT’s settings; on Business/Enterprise a workspace admin enables it first (Workspace settings → Permissions & roles → custom MCP connectors) — until they do, members don’t see the option at all.
In Settings → Connectors, create a connector and enter https://api.hyperspell.com/mcp.
Complete the OAuth sign-in with your Hyperspell dashboard account to authorize the connection.
In each new chat, enable the connector from the + menu → developer mode.

Like the Claude connector, the connection is user-scoped — every call acts as you, within your workspace.

Developer mode requires a paid plan: Plus and Pro get read-only custom connectors, Business, Enterprise and Edu get full read and write. OpenAI moves this setting between releases — if the path above doesn’t match what you see, follow their developer mode guide.A connector that’s installed but not enabled for the current conversation is never called. That’s the usual reason ChatGPT appears to ignore Hyperspell — check step 4 before debugging anything else.

Connect with an API key

For server-side agents, CI, and clients that send bearer headers (e.g. Cursor, Claude Code), authenticate with your Hyperspell API key instead:

Authorization: Bearer <your-api-key>

{
  "mcpServers": {
    "hyperspell": {
      "url": "https://api.hyperspell.com/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

An API key authenticates app-scoped (no specific user). Tools that need a user identity — like list_connections — return a clear user_identity_required error when called with an app-only key. To act as a specific user, log in via OAuth instead.

Local server (via the sync daemon)

If you run the Hyperspell sync daemon, it installs a local MCP server and registers it with Claude Desktop for you — no manual config. The daemon keeps a local copy of your brain summary in ~/.hyperspell, and the local server exposes it through the offline *_context tools alongside the standard tools above. This is the best option when you want Claude Desktop to read a fast local summary first and fall back to the full index only when needed. The daemon writes an entry like this into claude_desktop_config.json automatically:

{
  "mcpServers": {
    "hyperspell-context": {
      "command": "hyperbrain-mcp",
      "args": []
    }
  }
}

The config file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. The local server reads its credential from HYPERSPELL_API_KEY in its environment — the same key the CLI uses — so Desktop users never have to run a separate login.

Get Started

Usage

Advanced Usage

Resources

Model Context Protocol

What is the Model Context Protocol?

Two ways to connect

Tools

Tuning how hard the brain works

Hosted server

Connect from Claude (log in — recommended)

Connect from ChatGPT (log in)

Connect with an API key

Local server (via the sync daemon)

​What is the Model Context Protocol?

​Two ways to connect

​Tools

​Tuning how hard the brain works

​Hosted server

​Connect from Claude (log in — recommended)

​Connect from ChatGPT (log in)

​Connect with an API key

​Local server (via the sync daemon)

What is the Model Context Protocol?

Two ways to connect

Tools

Tuning how hard the brain works

Hosted server

Connect from Claude (log in — recommended)

Connect from ChatGPT (log in)

Connect with an API key

Local server (via the sync daemon)