---
title: "MCP"
description: "The tools an agent has at /mcp, a call of each, how to connect Claude Code and Codex, and what an agent cannot do."
url: https://spool.alexpatow.com/docs/mcp
docs_index: https://spool.alexpatow.com/llms.txt
---

# MCP

The tools an agent has at /mcp, a call of each, how to connect Claude Code and Codex, and what an agent cannot do.

The server answers the [Model Context Protocol](https://modelcontextprotocol.io) at `/mcp`, in the same process as the HTTP API and the studio. An agent that is pointed at it can load rows and documents, run the project's extractors, match what was loaded, look things up and change identities.

- **A tool is a call of the HTTP API.** It answers what the API answers and is refused what the API refuses.
- **The caller is whoever the server says it is.** With `spool dev` that is the `dev` account. With `spool serve` it is the token the agent presents, and what it changes is recorded as `agent:<name>`. No tool has an argument that names the author of a change.
- **A change made under the caller's name says why.** The tools that change identities or take rows back require a `reason`, which the log keeps beside the change. A load, an extraction and a match take none: the run records who started it.
- **Nothing is kept between requests.** The transport is Streamable HTTP without sessions, and every answer is one JSON response.

The tool calls on this page are what an agent sends. Each block is the `params` of a `tools/call` request, and each was run against the server as shown.

## Connect a client

Against `spool dev`, which asks for no token:

```sh
claude mcp add --transport http spool http://127.0.0.1:7765/mcp
codex mcp add spool --url http://127.0.0.1:7765/mcp
```

Against `spool serve`, make a token for each agent, named after it, so that the log says which one made a change. On the server's machine, `spool token add claude --store spool.duckdb` prints the token once. Then, with the token in `SPOOL_TOKEN`:

```sh
claude mcp add --transport http spool https://spool.example.com/mcp --header "Authorization: Bearer $SPOOL_TOKEN"
codex mcp add spool --url https://spool.example.com/mcp --bearer-token-env-var SPOOL_TOKEN
```

Claude Desktop reaches it through the `mcp-remote` package, a local server that passes each call on with a header. In `claude_desktop_config.json`:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "spool": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://spool.example.com/mcp", "--header", "Authorization:${SPOOL_AUTH}"],
      "env": { "SPOOL_AUTH": "Bearer <token>" }
    }
  }
}
```

The MCP SDKs, the MCP connector of the Claude API and the `mcp` tool of the OpenAI Responses API take the address and the token too.

**ChatGPT on the web and Claude on the web cannot connect to a server that asks for a token.** They add a remote server with no sign-in or through OAuth, and Spool is not an OAuth server. An organisation with Anthropic's request-headers beta can enter the header in Claude. Nothing else is built for it.

## Before you start

The examples use the sample project with both of its files of rows loaded and matched, which is where [Getting started](https://spool.alexpatow.com/docs/getting-started.md) ends. If you have that project and its server is running, use it. If not, this makes it:

```sh
spool init companies
cd companies
```

```sh
spool dev
```

Leave that running. In a second terminal, in the `companies` directory:

```sh
spool load samples/crm-1.csv
spool match
spool load samples/crm-2.csv
spool match
```

One more row gives the agent something to review, a Halden Group with no country:

```csv title="halden.csv"
id,name
c-13,Halden Group
```

```sh
spool load halden.csv --source crm
spool match
```

## Tools that look things up

Each is marked read-only for the client.

| Tool | What it answers | The same as |
| --- | --- | --- |
| `describe_store` | The entity types and their features, the sources the project declares with their columns, the extractors, counts, and the head of the log | `GET /v1/info` |
| `search_identities` | Identities by words in their records, by type or by ID | `GET /v1/identities` |
| `get_identity` | One identity and its records | `GET /v1/identities/{id}` |
| `get_identity_history` | Every change that touched an identity | `GET /v1/identities/{id}/history` |
| `search_records` | Records by words, source, key or identity, with their values | `GET /v1/records` |
| `get_record` | One record | `GET /v1/records/{id}` |
| `explain_pair` | Why two records share an identity, or why they do not. A record is named by its ID, as `source:key`, or, for one an extractor found, as the lists name it | `GET /v1/explain` |
| `list_review_items` | The cases left for someone to decide, the open ones by default | `GET /v1/review` |
| `get_review_case` | One review item with what is needed to decide it | `GET /v1/review/{id}/case` |
| `list_constraints` | The `must_link` and `cannot_link` decisions in force | `GET /v1/constraints` |
| `list_changesets` | The log after a position | `GET /v1/changesets` |
| `get_run` | One run: whether it is running, and what it reported | `GET /v1/runs/{run}` |
| `mint_identity_ids` | New identity IDs for a `create_identity` operation | `POST /v1/ids` |

An agent usually starts by asking what the store holds:

```json title="MCP tool call"
{ "name": "describe_store", "arguments": {} }
```

```text title="Output"
{"api":"v1","store":{"engine_version":"0.1.0","format_version":"11","manifest_hash":"d7d4b712d86302152897a67a5924cd1c2e26594e049685c2f007177e20633946","head":2,"entity_types":[{"name":"company","declaration_version":1,"features":[{"name":"record_id","data_type":"UUID"},{"name":"name","data_type":"VARCHAR"},{"name":"name_key","data_type":"VARCHAR"},{"name":"country","data_type":"VARCHAR"}],"strategies":[],"records":10,"unassigned":1,"retracted":0,"sources":[{"source":"crm","records":10,"unassigned":1,"retracted":0,"last_loaded_at":"2026-11-18T21:55:15.653351Z"}],"identities":5,"open_review_items":1,"open_draft":null}],"sources":[{"name":"crm","key":"id","columns":["id","name","country"],"entity_types":["company"]},{"name":"notes","key":null,"columns":["name"],"entity_types":["company"]}],"extractors":[{"name":"companies","runtime":"python","file":"extractors/companies.py","hash":"eacb9397cacc366a1cd065d8f328039484a5e5d4fbf49b8ca1f2a3cbd34f8c92"}],"documents":0}}
```

Identities are found by words in their records:

```json title="MCP tool call"
{ "name": "search_identities", "arguments": { "q": "kestrel" } }
```

```text title="Output"
{"identities":[{"id":"01a1efc6-42c0-7776-b736-83fde0cb4498","entity_type":"company","label":"Kestrel Analytics","created":2,"members":1,"sources":[{"source":"crm","records":1}]}],"next":null}
```

Records are found by source and key, which is how an agent gets from the key a person names to the record ID the other tools take:

```json title="MCP tool call"
{ "name": "search_records", "arguments": { "source": "crm", "key": "c-5" } }
```

```text title="Output"
{"records":[{"id":"38f040c9-82b9-2f94-813b-697309e52dab","entity_type":"company","source":"crm","key":"c-5","payload":{"country":"GB","id":"c-5","name":"Halden Group"},"label":"Halden Group","evidence":null,"loaded_at":"2026-11-18T21:48:44.236810Z","load_run":1,"identity":"01a1efc6-41cd-775d-8758-e7329447fd9a","supersedes":null,"superseded_by":null,"retracted":null}],"next":null}
```

The calls below use IDs from this project. To run them yourself, these put the IDs in shell variables, and the tool calls show the variable where the ID goes:

```sh
ACORN=$(spool show records crm:c-1 | awk '/^identity/ {print $2}')
TOOL=$(spool show records crm:c-9 | awk '/^record/ {print $2}')
GB=$(spool show records crm:c-5 | awk '/^record/ {print $2}')
US=$(spool show records crm:c-6 | awk '/^record/ {print $2}')
```

```json title="MCP tool call"
{ "name": "get_identity", "arguments": { "identity": "$ACORN" } }
```

```json title="MCP tool call"
{ "name": "get_identity_history", "arguments": { "identity": "$ACORN" } }
```

```json title="MCP tool call"
{ "name": "get_record", "arguments": { "record": "$GB" } }
```

`explain_pair` answers what `spool explain` prints, as JSON:

```json title="MCP tool call"
{ "name": "explain_pair", "arguments": { "a": "$GB", "b": "$US" } }
```

What is waiting for a decision, and one case with what is needed to decide it:

```json title="MCP tool call"
{ "name": "list_review_items", "arguments": {} }
```

```text title="Output"
{"items":[{"id":1,"run":9,"entity_type":"company","kind":"possible_merge","records":["621ab95e-5f9e-6b91-e660-455831fe854a"],"identities":["01a1efc6-41cd-775d-8758-e731c61371cb","01a1efc6-41cd-775d-8758-e7329447fd9a"],"groups":[],"status":"open","resolved_seq":null,"superseded_by":null,"dismissed":null}]}
```

```json title="MCP tool call"
{ "name": "get_review_case", "arguments": { "item": 1 } }
```

The case holds the item, its records with their values, the identities they matched with their members, and the judgements between them. It is one call so that an agent need not gather them one at a time.

```json title="MCP tool call"
{ "name": "list_changesets", "arguments": { "after": 1, "limit": 1 } }
```

```json title="MCP tool call"
{ "name": "mint_identity_ids", "arguments": { "count": 1 } }
```

```text title="Output"
{"identities":["01a1efaa-1ba3-7566-8623-0e9b224b63c9"],"changesets":[]}
```

## Tools that change something

Each is marked as a change, so a client can ask the person first.

| Tool | What it does | The same as |
| --- | --- | --- |
| `commit_changeset` | Merges identities, moves or places records, makes identities, adds and removes constraints | `POST /v1/changesets` |
| `split_identity` | Divides one identity in two and keeps the sides apart | `POST /v1/identities/{id}/split` |
| `undo_changeset` | Takes back one committed changeset, or shows what would | `POST /v1/changesets/{seq}/undo` |
| `dismiss_review_item` | Closes a review item without placing its records | `POST /v1/review/{id}/dismiss` |

Five more load, extract, match and take rows back. They are [further down](#tools-that-load-extract-and-match).

`commit_changeset` takes the operations of [the HTTP API](https://spool.alexpatow.com/docs/api.md#changesets). Here the agent records that the two Halden Groups are different companies, so that no later rule or reviewer merges them:

```json title="MCP tool call"
{ "name": "commit_changeset", "arguments": {
  "reason": "registered in different countries, with different company numbers",
  "ops": [ { "op": "constrain", "kind": "cannot_link", "a": "$GB", "b": "$US" } ] } }
```

```text title="Output"
{"seq":3,"changeset":"01a1efaa-1ba5-7158-b323-9365dc19b5e7","content_hash":"9b1ab005c425ddd81c5b1ee95101788266b244020147781da5cd9d0ce4c8f5e4"}
```

```json title="MCP tool call"
{ "name": "list_constraints", "arguments": { "record": "$GB" } }
```

`split_identity` names the records that leave. They get a new identity, and the one that is split keeps its ID:

```json title="MCP tool call"
{ "name": "split_identity", "arguments": { "identity": "$ACORN", "records": ["$TOOL"],
  "reason": "Acorn Tool is a hardware shop in Leeds, not Acorn Tools" } }
```

`undo_changeset` takes the position in the log. With `"commit": false` it answers the changeset that would undo it and commits nothing:

```json title="MCP tool call"
{ "name": "undo_changeset", "arguments": { "seq": 4, "commit": false, "reason": "checking what an undo would do" } }
```

```text title="Output"
{"changeset":{"id":"01a1f0a2-34c3-73a7-844e-eb8ac6aab102","base":4,"actor":"user:01a1f0a2-3336-72d8-8d23-74f15ece6783","reason":"checking what an undo would do","run":null,"ops":[{"op":"unconstrain","kind":"cannot_link","a":"34c3d52d-e53b-1559-7404-1892fb1fd4e3","b":"31075f20-6900-838b-f5af-f8c6576744a4"},{"op":"assign","record":"34c3d52d-e53b-1559-7404-1892fb1fd4e3","from":"01a1f0a2-34bb-729b-bdb0-e47ff384bcb8","to":"01a1efc6-41cd-775d-8758-e7300637659a"}]},"committed":null}
```

```json title="MCP tool call"
{ "name": "undo_changeset", "arguments": { "seq": 4, "reason": "the shop is a branch of Acorn Tools after all" } }
```

`dismiss_review_item` closes an item the agent cannot decide and says why:

```json title="MCP tool call"
{ "name": "dismiss_review_item", "arguments": { "item": 1, "reason": "the row has no country, so it cannot be told which Halden Group it is" } }
```

Every one of those is in the log under its author and reason:

```sh
spool show log --after 2
```

```text title="Output"
position  actor                                      operations  from  started by  reason
3         user:01a1f0a2-3336-72d8-8d23-74f15ece6783  1           -     -           registered in different countries, with different company numbers
4         user:01a1f0a2-3336-72d8-8d23-74f15ece6783  3           -     -           Acorn Tool is a hardware shop in Leeds, not Acorn Tools
5         user:01a1f0a2-3336-72d8-8d23-74f15ece6783  2           -     -           the shop is a branch of Acorn Tools after all
```

## Tools that load, extract and match

```json title="MCP tool call"
{ "name": "load_rows", "arguments": { "source": "crm", "entity_type": "company",
  "rows": [ { "id": "c-20", "name": "Kestrel Analytics Inc", "country": "US" } ] } }
```

```json title="MCP tool call"
{ "name": "run_match", "arguments": { "entity_type": "company" } }
```

```json title="MCP tool call"
{ "name": "get_run", "arguments": { "run": 11 } }
```

```json title="MCP tool call"
{ "name": "load_documents", "arguments": { "source": "notes",
  "documents": [ { "key": "notes-2.txt", "text": "Dana called again. Acorn Tools Ltd are moving their account next quarter." } ] } }
```

```json title="MCP tool call"
{ "name": "run_extraction", "arguments": { "extractor": "companies" } }
```

| Tool | What it does | The same as |
| --- | --- | --- |
| `load_rows` | Loads rows as objects into a source | `POST /v1/load` |
| `load_documents` | Stores texts as documents of a source | `POST /v1/documents` |
| `run_extraction` | Runs an extractor over the documents it has not read | `POST /v1/extractions` |
| `run_match` | Places the records no match has examined, and commits the result | `POST /v1/match` |
| `retract_rows` | Takes rows back by their keys: they leave their identities and stay in the store | `POST /v1/retract` |

Each answers with its run. A run that is still going after 30 seconds is answered as `running`, and `get_run` reads it later: with `wait_ms`, it waits up to 60 seconds for the run to finish.

Where these differ from the HTTP API:

- **`load_rows` does not replace a row unless it is told to.** A row with a key the store holds and other values is refused, and the whole call with it, unless the call has `"replace": true`. `POST /v1/load` replaces the row.
- **`load_rows` reads an empty value as a missing one**, as `spool load` reads an empty field. `POST /v1/load` with rows as JSON stores `""` as text.
- **`load_documents` refuses a source the project does not declare.** `POST /v1/documents` stores the document.
- **`run_extraction` needs no `extractor`** when the project has only one.
- **`run_match` always commits.** It takes `rematch` and `strategy`, which is `rules` or a strategy of the project, and no `commit`.
- **`retract_rows` requires a `reason`.** The other four take none.

## What an agent cannot do

- **Approve or reject a draft.** Drafts exist so that a person decides. That stays in the studio and on `/v1`.
- **Add people or make tokens.**
- **Change a project's files.** Rules, features and sources are files in Git, and the server reads them. An agent that edits them does so as any editor of the repository would.
- **Write as someone else, or change an identity without a reason.** Both are refused.
- **List or read documents.** An agent stores them and runs an extractor over them, and reads what was found as records.
- **Leave a match as a draft.** A match an agent starts commits, as `spool match` does. To hold a match for approval, start it over HTTP with `"commit": false`. [Review](https://spool.alexpatow.com/docs/concepts/review.md#drafts) shows how.

## Limits

- A request is at most 4 MiB.
- A list returns 20 entries unless the call gives a `limit`.
- A tool answers at most 256 KiB. A lookup over that is refused with an error that says to ask for less. A change over that was made all the same, and is answered without its large fields, which the answer names in `left_out`.
- A failure is an answer the model can read: the result has `isError` set, and its text is the error the API gives.
- The endpoint speaks the protocol revisions from `2024-11-05` to `2026-07-28`.
- Nobody has measured how well an agent reviews with these tools. The repository has no evaluation of it yet.
