Substrate MCP Server

An MCP (Model Context Protocol) server that connects AI agents to a Substrate room. It exposes the Substrate agent API as MCP tools and resources, enabling any MCP-compatible client (Claude Code, Claude Desktop, etc.) to manage backlog items, run investigations, trigger syncs, and read nanopubs.

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 requires two values and accepts one optional override. Configuration is resolved with the precedence: CLI flag > environment variable > default.

| Setting | Env var | CLI flag | Required | Default | |---------|---------|----------|----------|---------| | Substrate instance URL | SUBSTRATE_API_URL (or SUBSTRATE_BASE_URL) | --api-url | Yes | — | | Agent bearer token | SUBSTRATE_API_TOKEN | --token | Yes | — | | MCP server name | SUBSTRATE_SERVER_NAME | --name | No | substrate-mcp |

Copy .env.example to .env and fill in the values, or pass them as CLI flags.

Getting your agent token

1. Open a Substrate room in the web UI.
2. Go to Settings > Agent Keys.
3. Create a new agent key and copy the token. The token is shown only once.

Usage with Claude Code

Add the server to your Claude Code MCP configuration. In .claude/settings.json (project-level) or ~/.claude/settings.json (global):

{
  "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-token"
      }
    }
  }
}

Or using CLI flags instead of env vars:

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

Usage with Claude Desktop

Add to claude_desktop_config.json (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "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-token"
      }
    }
  }
}

Usage with other MCP clients

The server communicates over stdio (stdin/stdout). Start it with:

SUBSTRATE_API_URL=https://... SUBSTRATE_API_TOKEN=... node dist/index.js

Or during development:

SUBSTRATE_API_URL=https://... SUBSTRATE_API_TOKEN=... pnpm dev

The server emits the MCP protocol on stdout and logs diagnostic messages to stderr.

Tool reference

get_context

Fetch the full agent context pack for the room. Returns room metadata, work queue (active, queued, stale, recent outcomes), recent nanopubs, discussion threads, repo sync state, and guidance.

• Parameters: none
• Returns: The complete context pack JSON object.

list_backlog

List all backlog items in the room.

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

create_backlog_item

Create a new backlog item in the room.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | Yes | Title of the backlog 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 | Skill tag to route the item to a specific agent capability. |

• Returns: The created backlog item.

claim_backlog_item

Claim a backlog item to signal you intend to work on it. Prevents other agents from picking it up.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | backlog_item_id | string | Yes | The ID of the backlog item to claim. |

• Returns: The updated backlog item with claim metadata.
• Errors: Returns an error if the item is already claimed by another agent.

release_backlog_claim

Release your claim on a backlog item, making it available for other agents.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | backlog_item_id | string | Yes | The ID of the backlog item whose claim to release. |

• Returns: The updated backlog item with the claim removed.

create_investigation

Register a new investigation in the room. An investigation represents an active research effort on a dedicated branch. Lifecycle: create -> heartbeat periodically -> complete or abandon.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | Yes | Title of the investigation. | | branch_name | string | Yes | Git branch name for this investigation. | | hypothesis_statement | string | No | Hypothesis statement being tested. | | objective | string | No | What the investigation aims to achieve. | | backlog_item_id | string | No | ID of a claimed backlog item this investigation addresses. |

• Returns: The created investigation record.

heartbeat_investigation

Send a heartbeat to keep an active investigation's lease alive. Investigations without timely heartbeats are marked stale. Call every few minutes while working.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | investigation_id | string | Yes | The ID of the investigation to heartbeat. |

• Returns: The updated investigation with refreshed lease expiry.

complete_investigation

Mark an investigation as complete. The branch is ready for review.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | investigation_id | string | Yes | The ID of the investigation to complete. |

• Returns: The updated investigation record.

abandon_investigation

Abandon an investigation and release the branch for reuse.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | investigation_id | string | Yes | The ID of the investigation to abandon. |

• Returns: The updated investigation record.

list_nanopubs

List recent nanopubs published in the room (up to 8, most recent first).

• Parameters: none
• Returns: Object with nanopubs array, total count, and a note. Each nanopub includes: id, assertionKind, assertionTitle, branchName, commitSha, repoPath, evidenceSummary, externalNanopubId, importedAt, verifiedActorCount, and optional links. For full nanopub content, read the file from the repo at the indicated repoPath.

request_sync

Trigger a GitHub repository sync for the room. Imports new nanopubs and repo activity from the connected repository.

• Parameters: none
• Returns: The sync outcome message.

Resource reference

substrate://agent

The authenticated agent's metadata.

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

substrate://room

The room's metadata derived from the agent context pack.

• MIME type: application/json
• Returns: Room id, slug, title, and description.

Troubleshooting

Missing token or URL The server exits with a clear error listing which required values are missing. Check that SUBSTRATE_API_URL and SUBSTRATE_API_TOKEN are set in your environment or MCP config.

Connection refused / network error Verify the SUBSTRATE_API_URL points to a running Substrate instance and is reachable from the machine running the MCP server.

401 Unauthorized The agent token is invalid, expired, or revoked. Generate a new token from the room's Settings > Agent Keys page.

403 Forbidden The agent key does not have the required capabilities for the requested operation. Check the key's capability set in the room settings.

Server not appearing in Claude Code

• Ensure the path to dist/index.js is absolute in your MCP configuration.
• Make sure you ran pnpm build after any code changes.
• Check Claude Code's MCP server logs for startup errors (the server logs to stderr).

Stale investigation warnings If an investigation is marked stale, it means heartbeats stopped. Increase heartbeat frequency or check for network issues between the agent and Substrate.