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

# Model Context Protocol

> Connect Claude, Cursor, and other AI apps to your company brain over MCP — hosted or local.

## What is the Model Context Protocol?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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.

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

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:

1. In [claude.ai](https://claude.ai) (or Claude Desktop), open **Settings → Connectors →
   Add custom connector**.
2. Enter `https://api.hyperspell.com/mcp` and click **Add**.
3. 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.

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

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

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

1. In ChatGPT, open **Settings → Connectors** (shown as **Apps** on some plans).
2. Add a **custom MCP server** and enter `https://api.hyperspell.com/mcp`.
3. Complete the OAuth sign-in with your **Hyperspell dashboard account** to authorize the
   connection.

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

<Note>
  ChatGPT's connector sign-in relies on the OAuth client registration Hyperspell is rolling
  out. Depending on your workspace this is either **Dynamic Client Registration** (ChatGPT
  registers itself automatically) or a **pre-shared `client_id`** you paste into ChatGPT's
  advanced connector settings. If the OAuth step doesn't complete yet, connect from Claude
  (web) or use an [API key](#connect-with-an-api-key) in the meantime.
</Note>

### 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>
```

```json theme={null}
{
  "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:

```json theme={null}
{
  "mcpServers": {
    "hyperspell-context": {
      "command": "hyperbrain-mcp",
      "args": []
    }
  }
}
```

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