MCP Setup: Connect Your Agent to Substrate over stdio

Substrate exposes 32 tools over a stdio MCP server. Your agent runtime spawns substrate mcp as a child process — there is no port to open, no daemon to manage, and no network connection involved. The server reads the .substrate/ directory in whatever working directory the runtime uses when it spawns the process, so getting that path right is the single most important configuration step.

Configuration

Choose the tab that matches your setup:

Claude Code
Any MCP Runtime

Place the following block in an .mcp.json file at your project root. Claude Code will ask you to approve the project-scoped MCP server the first time you open the project.v0.7.0 pre-release (installed via global link — use this now):

.mcp.json

{
  "mcpServers": {
    "substrate": {
      "command": "substrate",
      "args": ["mcp"]
    }
  }
}

npm release (once Substrate is published):

.mcp.json

{
  "mcpServers": {
    "substrate": {
      "command": "npx",
      "args": ["@diegoferreyra/substrate", "mcp"]
    }
  }
}

After saving .mcp.json, install the agent skill so Claude carries workflow conventions across sessions without re-prompting:

substrate install-skill

Field	Value
`command`	`substrate` (global link) or `npx` (npm release)
`args`	`["mcp"]` or `["@diegoferreyra/substrate", "mcp"]`
Working directory	The project root that owns `.substrate/`

Tool schemas are advertised through tools/list — your runtime discovers them automatically on startup. No additional registration is required.

The MCP server reads the .substrate/ in its working directory. If your agent runtime is spawned from a git worktree or any directory other than the project root that owns .substrate/, it will get that directory’s database — which may be empty. Always confirm the working directory before debugging a not_found error.

Verify the connection

Ask your agent to call the whoami tool. A healthy response looks like this:

{
  "project_id": "…",
  "project_name": "substrate",
  "schema_version": 2,
  "boards": [{ "id": "dev", "name": "Substrate Dev", "…": "…" }],
  "hints": ["…"]
}

If the call returns a not_found error, check two things:

Working directory — confirm the runtime is spawning substrate mcp from the directory that contains .substrate/.
Initialization — run substrate init in that directory if .substrate/ does not exist yet.

Teach your agent to always call whoami first at the start of a session. It confirms the connection, loads board context, and surfaces any hints Substrate wants the agent to act on.

The agent skill

Running substrate install-skill writes a skill file to ~/.claude/skills/substrate, stamped with the current binary version. The skill encodes conventions your agent needs to work effectively with Substrate:

Call whoami at the start of every session
Use optimistic concurrency when updating tasks
Read and respect the policy envelope returned by write operations

Without the skill, you would need to include these instructions in every system prompt or session preamble. With it, Claude picks them up automatically. Run the following to check whether the installed skill matches your binary version without overwriting anything:

substrate install-skill --check

This exits non-zero and reports drift if the versions do not match.

The skill is version-stamped against the binary. After upgrading Substrate, re-run substrate install-skill to keep the skill in sync.

Next steps

The Agent Loop

Follow the recommended whoami → get_board → list_tasks → write loop and understand how the policy envelope guides agent behavior.

Quickstart

Initialize a board and start the local inspector if you haven’t already.

Get Started

Concepts

Working with Agents

Authoring a Substrate

Operations

MCP Setup: Connect Your Agent to Substrate over stdio

Configuration

Verify the connection

The agent skill

Next steps

The Agent Loop

Quickstart

​Configuration

​Verify the connection

​The agent skill

​Next steps

The Agent Loop

Quickstart

Configuration

Verify the connection

The agent skill

Next steps