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

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:

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:

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 ends. If you have that project and its server is running, use it. If not, this makes it:

spool init companies
cd companies
spool dev

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

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:

halden.csv
id,name
c-13,Halden Group
spool load halden.csv --source crm
spool match

Tools that look things up

Each is marked read-only for the client.

ToolWhat it answersThe same as
describe_storeThe entity types and their features, the sources the project declares with their columns, the extractors, counts, and the head of the logGET /v1/info
search_identitiesIdentities by words in their records, by type or by IDGET /v1/identities
get_identityOne identity and its recordsGET /v1/identities/{id}
get_identity_historyEvery change that touched an identityGET /v1/identities/{id}/history
search_recordsRecords by words, source, key or identity, with their valuesGET /v1/records
get_recordOne recordGET /v1/records/{id}
explain_pairWhy 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 itGET /v1/explain
list_review_itemsThe cases left for someone to decide, the open ones by defaultGET /v1/review
get_review_caseOne review item with what is needed to decide itGET /v1/review/{id}/case
list_constraintsThe must_link and cannot_link decisions in forceGET /v1/constraints
list_changesetsThe log after a positionGET /v1/changesets
get_runOne run: whether it is running, and what it reportedGET /v1/runs/{run}
mint_identity_idsNew identity IDs for a create_identity operationPOST /v1/ids

An agent usually starts by asking what the store holds:

MCP tool call
{ "name": "describe_store", "arguments": {} }
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:

MCP tool call
{ "name": "search_identities", "arguments": { "q": "kestrel" } }
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:

MCP tool call
{ "name": "search_records", "arguments": { "source": "crm", "key": "c-5" } }
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:

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}')
MCP tool call
{ "name": "get_identity", "arguments": { "identity": "$ACORN" } }
MCP tool call
{ "name": "get_identity_history", "arguments": { "identity": "$ACORN" } }
MCP tool call
{ "name": "get_record", "arguments": { "record": "$GB" } }

explain_pair answers what spool explain prints, as JSON:

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:

MCP tool call
{ "name": "list_review_items", "arguments": {} }
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}]}
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.

MCP tool call
{ "name": "list_changesets", "arguments": { "after": 1, "limit": 1 } }
MCP tool call
{ "name": "mint_identity_ids", "arguments": { "count": 1 } }
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.

ToolWhat it doesThe same as
commit_changesetMerges identities, moves or places records, makes identities, adds and removes constraintsPOST /v1/changesets
split_identityDivides one identity in two and keeps the sides apartPOST /v1/identities/{id}/split
undo_changesetTakes back one committed changeset, or shows what wouldPOST /v1/changesets/{seq}/undo
dismiss_review_itemCloses a review item without placing its recordsPOST /v1/review/{id}/dismiss

Five more load, extract, match and take rows back. They are further down.

commit_changeset takes the operations of the HTTP API. Here the agent records that the two Halden Groups are different companies, so that no later rule or reviewer merges them:

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" } ] } }
Output
{"seq":3,"changeset":"01a1efaa-1ba5-7158-b323-9365dc19b5e7","content_hash":"9b1ab005c425ddd81c5b1ee95101788266b244020147781da5cd9d0ce4c8f5e4"}
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:

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:

MCP tool call
{ "name": "undo_changeset", "arguments": { "seq": 4, "commit": false, "reason": "checking what an undo would do" } }
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}
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:

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:

spool show log --after 2
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

MCP tool call
{ "name": "load_rows", "arguments": { "source": "crm", "entity_type": "company",
  "rows": [ { "id": "c-20", "name": "Kestrel Analytics Inc", "country": "US" } ] } }
MCP tool call
{ "name": "run_match", "arguments": { "entity_type": "company" } }
MCP tool call
{ "name": "get_run", "arguments": { "run": 11 } }
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." } ] } }
MCP tool call
{ "name": "run_extraction", "arguments": { "extractor": "companies" } }
ToolWhat it doesThe same as
load_rowsLoads rows as objects into a sourcePOST /v1/load
load_documentsStores texts as documents of a sourcePOST /v1/documents
run_extractionRuns an extractor over the documents it has not readPOST /v1/extractions
run_matchPlaces the records no match has examined, and commits the resultPOST /v1/match
retract_rowsTakes rows back by their keys: they leave their identities and stay in the storePOST /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 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.