Skip to main content
substrate mcp speaks the Model Context Protocol over stdin/stdout, exposing all 32 Substrate tools to the agent runtime that spawns it. You rarely run this yourself — your agent runtime spawns it as a child process pointed at your project root. There is no port, no network, and no configuration required beyond placing it correctly in your runtime’s config block.

​
Usage

​
Working Directory

The server reads the .substrate/ in its working directory. Your runtime spawns it from the project root, which is normally what you want — but a runtime spawned from a git worktree gets that worktree’s empty database. Pointing the process at another checkout’s working directory is the supported workaround. See Worktrees and Clones.

​
Logging

mcp is a long-lived process, so it records warnings and errors to .substrate/logs/substrate.log — including an agent’s handled tool errors. Read them with substrate logs --errors. The process also emits the fresh-empty-database warning at startup when it opens a .substrate/ that has boards but no task database.

​
Tools

substrate mcp exposes 32 tools. See MCP Overview for the full list and descriptions.

​
Configuration

See MCP Setup for the config block to add to your agent runtime.