> ## Documentation Index
> Fetch the complete documentation index at: https://docs.substrate.42.pe/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup: Connect Your Agent to Substrate over stdio

> Register the Substrate stdio MCP server with your agent runtime, verify the connection with whoami, and install the agent skill for Claude Code.

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:

<Tabs>
  <Tab title="Claude Code">
    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):

    ```json .mcp.json theme={null}
    {
      "mcpServers": {
        "substrate": {
          "command": "substrate",
          "args": ["mcp"]
        }
      }
    }
    ```

    **npm release** (once Substrate is published):

    ```json .mcp.json theme={null}
    {
      "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:

    ```sh theme={null}
    substrate install-skill
    ```
  </Tab>

  <Tab title="Any MCP Runtime">
    Register a new MCP server entry in your runtime's configuration with the following values:

    | 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.
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

## Verify the connection

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

```json theme={null}
{
  "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:

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

<Tip>
  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.
</Tip>

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

```sh theme={null}
substrate install-skill --check
```

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

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

## Next steps

<CardGroup cols={2}>
  <Card title="The Agent Loop" icon="rotate" href="/agents/agent-workflow">
    Follow the recommended whoami → get\_board → list\_tasks → write loop and understand how the policy envelope guides agent behavior.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/getting-started/quickstart">
    Initialize a board and start the local inspector if you haven't already.
  </Card>
</CardGroup>