Substrate MCP Server

An MCP (Model Context Protocol) server that gives an agent a Room's own routes as tools. It is the interactive door onto the platform: any MCP-compatible client — Claude Code, Claude Desktop, Cursor, VS Code — can read the Room's context pack, work its Board, run Investigations, and put Pre-registrations, Mints and Assertions through the admission Gate.

It is not the only door. A Room the wizard creates also ships scripts/substrate.py, the headless path its own harness runs inside a scripted run. Both write through the same routes and meet the same Gate; the Room's README.md says which to reach for and when.

Installation

# From the repository root
pnpm install
pnpm -C packages/mcp-server build

The build produces dist/index.js, which is the entry point for the server. The package also registers a substrate-mcp binary via package.json#bin.

Configuration

The server needs two things — where the Room reports, and the Agent Key it acts under — and it can take both from a Room package rather than being told them. Everything is resolved with the precedence CLI flag > environment variable > the Room's .env > default.

Room mode: point the server at a Room package

node dist/index.js --room /path/to/room --role scientist

--room names the directory holding a Room package's .env — the gitignored file the wizard wrote when the Room was opened and showed exactly once. --role picks which of that Room's keys to act under.

A Room and this server name the same three things differently, and that difference is the point of Room mode rather than something to paper over:

| | the Room's .env writes | this server's own variable | |---|---|---| | instance URL | SUBSTRATE_URL | SUBSTRATE_API_URL (or SUBSTRATE_BASE_URL) | | Agent Key | SUBSTRATE_KEY_<ROLE> — one per role | SUBSTRATE_API_TOKEN | | minting key | SUBSTRATE_MINTING_KEY | SUBSTRATE_MINTING_KEY |

Only the minting key agrees. SUBSTRATE_KEY_<ROLE> is built from --role exactly as scripts/substrate.py builds it — wiring-referee becomes SUBSTRATE_KEY_WIRING_REFEREE — with no allowlist of roles, so a Room that gains a seventh role gains its key in the same file and this server finds it without being rebuilt.

A Room's key is its role. A scientist key cannot file a referee verdict. Change --role to open a different door; there is nothing to copy anywhere.

When the Room is not where the server looked, or its .env sets neither value, the refusal names the path it read and the variables it wanted — one bullet per variable actually missing.

The server's own variables

| Setting | Env var | CLI flag | Required | Default | |---------|---------|----------|----------|---------| | Room package directory | SUBSTRATE_ROOM_DIR | --room | No | — | | Role whose key to use | SUBSTRATE_ROLE | --role | No | scientist | | Substrate instance URL | SUBSTRATE_API_URL (or SUBSTRATE_BASE_URL) | --api-url | Yes, unless a Room supplies it | — | | Agent Key | SUBSTRATE_API_TOKEN | --token | Yes, unless a Room supplies it | — | | Room minting key | SUBSTRATE_MINTING_KEY | --minting-key | No | — | | MCP server name | SUBSTRATE_SERVER_NAME | --name | No | substrate-mcp |

The minting key is configuration and never a tool argument: a key the model can pass is a key the model has seen, and every transcript would then carry it. Without one, submit_mint says so rather than sending an unsigned record.

SUBSTRATE_TIMEOUT_S sits in a Room's .env and is deliberately not read here — the client passes no signal to fetch, so honouring it would be configuration that silently does nothing.

Getting an Agent Key

1. Open a Room in the web UI.
2. Go to Settings → Agent Keys.
3. Create a key and copy it. It is shown only once.

A Room package created by the wizard already carries one key per role in its .env, so a Room in hand needs none of this.

Declaring the server to Claude Code

A Room the wizard creates ships its own declaration as .mcp.json at the root of the tree, pointed at itself:

{
  "mcpServers": {
    "substrate": {
      "command": "node",
      "args": [
        "/absolute/path/to/packages/mcp-server/dist/index.js",
        "--room",
        ".",
        "--role",
        "scientist"
      ]
    }
  }
}

--room . is the Room's own repository: an MCP client starts a server with the project as its working directory. No key appears in that file, and none may be put in one — a Room repository is a publication surface, and a .mcp.json's ${VAR} expansion reads the environment, which a .env on disk does not populate. The server reads the Room's .env itself instead.

The one machine-local value is the path in args[0]: the server is not published to a registry yet, so a Room and the platform it reports to are assumed to be on one machine and the path is resolved by hand once.

Without a Room package — pointing the server at an instance directly:

{
  "mcpServers": {
    "substrate": {
      "command": "node",
      "args": ["/absolute/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "SUBSTRATE_API_URL": "https://your-substrate-instance.example.com",
        "SUBSTRATE_API_TOKEN": "your-agent-key"
      }
    }
  }
}

Other MCP clients

This is a standard stdio MCP server, so any MCP client can run it. What differs between clients is only which file the declaration lives in — the command and args above are the same two lines everywhere:

| client | where the declaration goes | |---|---| | Claude Code | .mcp.json at the project root (or ~/.claude.json for a user-scoped one) | | Cursor | .cursor/mcp.json in the project (or ~/.cursor/mcp.json) | | Claude Desktop | claude_desktop_config.json — on macOS, ~/Library/Application Support/Claude/ | | VS Code | .vscode/mcp.json in the workspace |

A Room ships for Claude Code, and that is the only client any of this was driven against: the other three take the same command and args in their own file, and each was not driven here. If a client cannot start the server, run the command by hand first — it prints its refusal to stderr and stops.

Started directly, without any client:

node dist/index.js --room /path/to/room --role scientist

The server speaks the MCP protocol on stdout and logs diagnostics to stderr.

Tool reference

14 tools, in the order an Investigation uses them. Two notes before the list:

• The wire format still spells the Board list_backlog and a Work Item backlog_item_id. CONTEXT.md retired both words; renaming what an MCP client calls is not this server's to do unilaterally, so the names below are the wire format and the prose around them is the glossary's.
• A refusal is not a tool error. When the Gate says no, the call succeeded and the answer was no: the verdict comes back naming every rule that failed, and it is public either way. Only a broken transport or a missing key is reported as an error.

get_context

Fetch the Room's full agent context pack — the Room's own record, its Room Profile (the predicate registry the Gate checks an Assertion against) and its Conduct, the Board, active and stale work, recent outcomes, repository state and guidance.

• Parameters: none
• Returns: the complete context pack as JSON.

The tool's own description is built from the pack's sections rather than written by hand, so a section added to the pack cannot reach an agent undescribed.

list_backlog

List the Room's Work Items.

• Parameters: none
• Returns: array of items with id, title, description, type, priority, status, claim state and metadata.

create_backlog_item

Propose a new Work Item.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | Yes | Title of the Work Item. | | description | string | No | Longer description of the work to be done. | | type | enum | Yes | One of: hypothesis_test, replication, critique, synthesis, review, meta_analysis, other. | | priority | enum | No | One of: low, medium, high. Defaults to medium. | | skillTag | string | No | Routes the item to a specific agent capability. |

• Returns: the created Work Item.

claim_backlog_item

Take ownership of a Work Item so no other agent dispatches it. A Claim is the claiming key plus an unexpired Lease, and the scientific write path needs one: a Pre-registration, a Mint and an Assertion are all refused unless you hold the item's Claim.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | backlog_item_id | string | Yes | The Work Item to claim. |

• Returns: the updated Work Item with its claim metadata.
• Refusals: already claimed by another agent.

release_backlog_claim

Hand a Work Item back early. Completing or abandoning an Investigation does not release the Claim — it lapses on its own expiry — because a Mint queued offline can only be flushed while you still hold it. Release once your outbox is empty.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | backlog_item_id | string | Yes | The Work Item whose claim to release. |

• Returns: the updated Work Item with the claim removed.

create_investigation

Register an Investigation: a Work Item bound to a branch with an active Lease. The lifecycle is create → heartbeat → complete or abandon. One Investigation, one branch.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | See note | Name for the Investigation. | | branch_name | string | Yes | The branch this runs on. Must be unique among active Investigations. | | hypothesis_statement | string | No | What you expect to find. | | objective | string | No | What success looks like. | | backlog_item_id | string | No | A Work Item you hold the Claim on. |

An Investigation on a Work Item keeps that item's title, so leave title out when you send a backlog_item_id; a differing title is refused. Send one only when there is no Work Item.

• Returns: the created Investigation record.

heartbeat_investigation

Refresh the Investigation's Lease. Without timely heartbeats the platform derives it as stale, which tells humans and other agents the work may be abandoned. Call every few minutes while working.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | investigation_id | string | Yes | The Investigation to heartbeat. |

• Returns: the Investigation with a refreshed Lease expiry.

complete_investigation

Mark an Investigation finished; the branch is ready for review.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | investigation_id | string | Yes | The Investigation to complete. |

• Returns: the updated Investigation record.

abandon_investigation

Abandon an Investigation and release its branch for reuse.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | investigation_id | string | Yes | The Investigation to abandon. |

• Returns: the updated Investigation record.

register_preregistration

Register a Pre-registration for a claimed Work Item before doing any work. Its position in the append-only log is what an Assertion is later judged against: an Assertion is refused if its Pre-registration arrived after the earliest Mint it cites.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | work_item_id | string | Yes | The Work Item this design is for. You must hold its Claim. | | bins | array | Yes | The outcomes committed to in advance, each { name, description }, in the order you want them read. At least two, one of which describes an honest failure. | | kill_criterion | string | Yes | The condition under which the Investigation stops and reports. | | lane | string | Yes | The compute envelope this will run in (0, A, B or C). | | commit_sha | string | Yes | The commit carrying the pre-registered text. | | commit_date | string | No | ISO 8601 date of that commit. Reported, never trusted — if it predates receipt, receipt is the effective time. | | body | string | No | The full pre-registered text as committed. |

• Returns: the verdict — admitted with its log position and receipt time, or refused with every failed rule named. The Gate never judges whether the design is good, only that the structure making it checkable is present.

submit_mint

Record a Mint: what it would take to get this number again. Submit one per step as the step completes, not in a batch at the end — a Mint that lands early survives a crash and shows the run is alive. Submission is idempotent on local_id, so retrying after a network failure returns the record that already landed.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | localId | string | Yes | This Mint's id within the Room, e.g. m-e1-s3. Retries key on it. | | workItemId | string | Yes | The Work Item this run belongs to. You must hold its Claim. | | codeFiles | object | Yes | Path → sha256 for every code file the run used. Content binds, not the commit. | | outputs | object | Yes | Path → sha256 of what the run produced. | | command | string[] | No | The exact command as an argument list. Use ["bash", "-c", "…"] when you mean a shell. | | commitSha | string | No | The commit this ran at — context for a reader, not the binding. | | env | object | No | Interpreter and machine facts that affect the result. | | envVars | object | No | The environment variables that shaped the run. | | inputs | array | No | Every input, each with its hash or pinned revision. | | params | object | No | The parameters the command ran with. | | seeds | any | No | The seeds used. A seed of 0 is a seed. | | seedsJustification | string | No | Why this run has no seeds, if it has none. | | lane | string | No | The compute envelope this ran in. | | step | string | No | Which step of the Investigation this is. Hashed into the recipe. | | task | string | No | The Room's own name for this work, e.g. S5. Hashed into the recipe. |

The recipe hash is computed here and signed with the server's configured minting key — neither is something the agent supplies. The Gate refuses a Mint that declares no code or no outputs, or whose seeds are absent without a justification.

• Returns: recorded (with its log position), already recorded, or refused with the failing rules named. Rules the Gate could not run are reported as not checked, which is not a pass.

publish_assertion

Publish an Assertion — a claim this Room establishes and answers for.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | This Assertion's id in the Room, e.g. asr:e1-retention. | | workItem | string | Yes | The Work Item this answers. You must hold its Claim. | | statement | string | Yes | The claim in one self-sufficient sentence, carrying its own number. This is what every human surface renders. | | predicate | string | Yes | A kernel predicate (replication_outcome, has_property, differs_between, instrument_behaves, localizes_effect_to, implementation_diverges, revision_changed, artifact_exists) or one this Room's Profile registers — read the registry from get_context. | | roles | object | Yes | Role name → { ref } or { value }. Closed vocabulary: subject, comparator, locus, instrument, metric, population, target, artifact, magnitude, condition. A Room extends predicates, never roles. | | provenance | object | Yes | minted_by, rivals_ruled_out (each with its rival, status and ruled_out_by), a skeptic paragraph, and any null_control. | | referee | object | Yes | { rounds: [...] }, the full history in order. The last round must be an acceptance; the Gate never reads the reasoning. | | selfContained | object | Yes | role_labels and as-implemented definitions — what lets the claim be read alone. | | polarity | string | No | Polarity of the claim. | | publicationInfo | object | No | Publication metadata. |

The Gate judges whether a claim is checkable, never whether it is true.

• Returns: admitted with its log position, already published, or refused with every failed rule named. A refusal is public.

add_publication_graph

Put a Publication Graph on record for a paper the platform knows but holds no records for. Takes the six layers a KG prepared offline with the paper-hypergraph skill emits.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | arxiv_id | string | Yes | Bare arXiv id, no version suffix, e.g. 2406.05946. | | version | integer | Yes | Which Revision this graph describes — the one the KG was prepared against. | | layers | object | Yes | nodes, assertions, gaps, artifacts, grounding, boundary. Unknown keys are refused rather than dropped. |

Every quote is re-located against the platform's own pinned copy before anything is written. Records that fail are refused individually and counted, so a partial graph still lands and says how partial it is. Refused entirely when the paper has no pinned source yet.

• Returns: the verdict, with what was written and what was refused.

suggest_publication_records

Add records to a paper's existing Publication Graph — a gap nobody named, an artifact in a footnote, a claim the sweep declined. This mints a new Extraction Version carrying every earlier record plus yours, attributed to your Agent Key.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | arxiv_id | string | Yes | Bare arXiv id, e.g. 2406.05946. | | layers | object | Yes | The same six layers, carrying only what you are adding. References may point at records the current version already holds. | | note | string | Yes | Why these records belong on this paper. "Relevant" is not a reason. | | version | integer | No | Which Revision. Omit for the newest on record. |

• Returns: the verdict, naming the version it minted.

Resource reference

substrate://agent

The authenticated agent's own record.

• MIME type: application/json
• Returns: id, name, capabilities, status, key type, Room assignment and expiry.

substrate://room

The Room, and only the Room — three sections, not one.

• MIME type: application/json
• Returns: the Room's record (id, slug, title, description), its Room Profile — the predicate registry the Gate checks an Assertion against, together with anything the Profile named that the registry would not serve — and its Conduct, the rules that bind an agent. Derived from the agent context pack; get_context stays wider and returns the work and repository state too.

Prompt reference

Two static prompts, which call nothing:

• substrate_onboarding — what a Room is, what an agent may do in one, and the whole path from reading the context pack to an admitted Assertion.
• substrate_investigation_checklist — the same path as a checklist, one line per step.

Troubleshooting

Missing URL or Agent Key The server prints which values are missing and stops. With --room, the message names the .env it read and the variables that file does not set — including which role's key was wanted. Without one, it says no Room was named.

No Room package at that path The three ways this fails are kept apart: the directory is not there, the directory is there and .env is not, or .env is there and cannot be read. The message says which, and names the absolute path it looked at — --room is resolved against the client's working directory, not yours.

Connection refused / network error Check the instance URL points at a running Substrate instance reachable from the machine running the server.

401 Unauthorized The Agent Key is invalid, expired or revoked. Mint a new one from the Room's Settings → Agent Keys.

403 Forbidden The key does not carry the capability the call needs. A Room's key is its role: check --role.

"No minting key is configured" submit_mint refuses rather than sending an unsigned record. Set SUBSTRATE_MINTING_KEY, or point the server at a Room whose .env carries one.

A Gate refusal Not a fault. The verdict names every rule that failed; fix the record and submit again under the same id. Rules reported as not checked ran on nothing and are not passes.

Server not appearing in the client

• The path to dist/index.js must be absolute.
• Run pnpm -C packages/mcp-server build after any code change.
• Start the command by hand: the server logs its refusal to stderr and stops.

Stale Investigation Heartbeats stopped. Send one to refresh the Lease.