Docs / MCP

MCP

The same contract exposed as bounded agent tools.

Source: docs/initiatives/memory-api/MCP.md — this page is rendered from it, not copied. The same two calls as MCP tools, over the same Store protocol the HTTP contract serves — so the transports cannot disagree.

Brain exposes four bounded tools at the authenticated Streamable HTTP endpoint /mcp. The MCP adapter calls the same Store, models, scopes, tenancy rules, errors, watermarks, and receipts as the HTTP API. It does not contain retrieval or ingestion logic.

Connect#

Keep the credential in BRAIN_API_KEY. A hosted MCP credential is bound by the operator to one Brain, so no tool accepts a project or Brain override.

Codex#

export BRAIN_API_KEY="..."
codex mcp add brain \
  --url https://your-brain.example/mcp \
  --bearer-token-env-var BRAIN_API_KEY

Claude Code#

export BRAIN_API_KEY="..."
claude mcp add --transport http brain https://your-brain.example/mcp \
  --header 'Authorization: Bearer ${BRAIN_API_KEY}'

Cursor#

Put this in ~/.cursor/mcp.json. Launch Cursor from an environment that provides BRAIN_API_KEY; do not replace the placeholder with the secret.

{
  "mcpServers": {
    "brain": {
      "url": "https://your-brain.example/mcp",
      "headers": {"Authorization": "Bearer ${env:BRAIN_API_KEY}"}
    }
  }
}

Any Streamable HTTP client#

{
  "url": "https://your-brain.example/mcp",
  "headers": {"Authorization": "Bearer ${BRAIN_API_KEY}"}
}

The current design-partner path uses a minted, Brain-bound, scoped, revocable bearer key. Brain does not claim a partial OAuth implementation. Broader self-serve discovery waits for a full authorization server with discovery, PKCE, audience validation, expiry, refresh, and revocation.

The four tools#

The default customer credential should carry only records:read and context:read. Add records:write separately when the product needs remember.

Integration sequence#

1. Call brain_status and verify the expected Brain and scopes.
2. Call context at one real product decision point.
3. Preserve every returned state; do not turn an unknown or conflict into a fluent assertion.
4. Resolve at least one returned record_id with get_record.
5. Run the application tests and brain doctor --json.
6. Only then enable remember, using stable source identity and an idempotency key. Pass the returned watermark to context as min_watermark for read-your-write.

Every successful tool response has a request_id. Tool failures serialize the HTTP taxonomy: type, code, message, request_id, and docs_url.

Install the Integrator#

The CLI is distributed directly from the service while the package remains unpublished:

curl -fsSL https://your-brain.example/guide/downloads/install.sh | sh
export BRAIN_API_KEY="..."
brain connect --url https://your-brain.example/mcp --company "Acme" --client auto
brain doctor --json

The installer verifies the executable checksum. brain connect writes only environment references to client configuration and a non-secret .brain/integration.json receipt to the customer repository.

Local stdio#

Stdio is a development bridge, not the customer path. It requires both BRAIN_MCP_PROJECT and BRAIN_MCP_BRAIN; there is no founder default.

export BRAIN_MCP_PROJECT="test:local"
export BRAIN_MCP_BRAIN="demo"
.venv/bin/python -m memory_api.mcp_server

Proof boundary#

The public sandbox uses InMemoryStore. It proves protocol and contract behavior, not customer durability. Customer proof must run against the authenticated SpineStore service with a dedicated test tenant.

# MCP

Brain exposes four bounded tools at the authenticated Streamable HTTP endpoint `/mcp`. The MCP
adapter calls the same Store, models, scopes, tenancy rules, errors, watermarks, and receipts as
the HTTP API. It does not contain retrieval or ingestion logic.

## Connect

Keep the credential in `BRAIN_API_KEY`. A hosted MCP credential is bound by the operator to one
Brain, so no tool accepts a project or Brain override.

### Codex

```bash
export BRAIN_API_KEY="..."
codex mcp add brain \
  --url https://your-brain.example/mcp \
  --bearer-token-env-var BRAIN_API_KEY
```

### Claude Code

```bash
export BRAIN_API_KEY="..."
claude mcp add --transport http brain https://your-brain.example/mcp \
  --header 'Authorization: Bearer ${BRAIN_API_KEY}'
```

### Cursor

Put this in `~/.cursor/mcp.json`. Launch Cursor from an environment that provides
`BRAIN_API_KEY`; do not replace the placeholder with the secret.

```json
{
  "mcpServers": {
    "brain": {
      "url": "https://your-brain.example/mcp",
      "headers": {"Authorization": "Bearer ${env:BRAIN_API_KEY}"}
    }
  }
}
```

### Any Streamable HTTP client

```json
{
  "url": "https://your-brain.example/mcp",
  "headers": {"Authorization": "Bearer ${BRAIN_API_KEY}"}
}
```

The current design-partner path uses a minted, Brain-bound, scoped, revocable bearer key. Brain
does **not** claim a partial OAuth implementation. Broader self-serve discovery waits for a full
authorization server with discovery, PKCE, audience validation, expiry, refresh, and revocation.

## The four tools

| Tool | Default authority | Use |
|---|---|---|
| `brain_status` | read-only | Verify identity, environment, scopes, and capabilities without returning memory content. |
| `context` | read-only | Retrieve task-bounded Context with citations, unknowns, conflicts, processing, abstention, budget, cost, and watermark. |
| `get_record` | read-only | Resolve a citation to the underlying custody Record. |
| `remember` | additive | Add one Record with an explicit stable idempotency key; never deletes or accepts application authority. |

The default customer credential should carry only `records:read` and `context:read`. Add
`records:write` separately when the product needs `remember`.

## Integration sequence

1. Call `brain_status` and verify the expected Brain and scopes.
2. Call `context` at one real product decision point.
3. Preserve every returned state; do not turn an unknown or conflict into a fluent assertion.
4. Resolve at least one returned `record_id` with `get_record`.
5. Run the application tests and `brain doctor --json`.
6. Only then enable `remember`, using stable source identity and an idempotency key. Pass the
   returned watermark to `context` as `min_watermark` for read-your-write.

Every successful tool response has a `request_id`. Tool failures serialize the HTTP taxonomy:
`type`, `code`, `message`, `request_id`, and `docs_url`.

## Install the Integrator

The CLI is distributed directly from the service while the package remains unpublished:

```bash
curl -fsSL https://your-brain.example/guide/downloads/install.sh | sh
export BRAIN_API_KEY="..."
brain connect --url https://your-brain.example/mcp --company "Acme" --client auto
brain doctor --json
```

The installer verifies the executable checksum. `brain connect` writes only environment
references to client configuration and a non-secret `.brain/integration.json` receipt to the
customer repository.

## Local stdio

Stdio is a development bridge, not the customer path. It requires both `BRAIN_MCP_PROJECT` and
`BRAIN_MCP_BRAIN`; there is no founder default.

```bash
export BRAIN_MCP_PROJECT="test:local"
export BRAIN_MCP_BRAIN="demo"
.venv/bin/python -m memory_api.mcp_server
```

## Proof boundary

The public sandbox uses `InMemoryStore`. It proves protocol and contract behavior, not customer
durability. Customer proof must run against the authenticated `SpineStore` service with a
dedicated test tenant.