MCP Server

For MCP-aware harnesses (Claude Code, Cursor, etc.), stepbook ships an MCP server that exposes each CLI command as a tool. It's a thin protocol shim over the same JSON envelopes documented in the Agent Contract — every tool spawns the CLI under the hood, so the contract is identical.

The @stepbook/mcp package provides a stepbook-mcp binary that speaks MCP over stdio.

Setup

1. Add it to your harness's MCP config. No install step — npx -y fetches @stepbook/mcp on first launch and caches it. All the major MCP-aware editors use the same JSON shape; only the file location differs.

Claude Code

// ~/.claude.json (global) or .mcp.json (per-project)
{
  "mcpServers": {
    "stepbook": {
      "command": "npx",
      "args": ["-y", "@stepbook/mcp"]
    }
  }
}

Cursor

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "stepbook": {
      "command": "npx",
      "args": ["-y", "@stepbook/mcp"]
    }
  }
}

Prefer a fixed binary on PATH? Install it globally (npm install -g @stepbook/mcp) and use "command": "stepbook-mcp" with no args instead.

2. Restart the harness. In Claude Code, /mcp lists connected servers — you should see stepbook with its 11 tools. If something's wrong, the harness's MCP logs surface the spawn error (usually a bad command path or the bin not on PATH).

Multi-project setups

The MCP server inherits its cwd from however the harness launched it. Every tool also accepts an optional projectDir argument that overrides cwd per call:

// what the agent sends:
{
  "name": "stepbook_run",
  "arguments": {
    "projectDir": "/Users/you/projects/llm-eval-pipeline",
    "from": "summarize",
  },
}

A single running MCP server can drive any number of stepbook projects on the same machine — no restart on project switch.

Tool catalog

Eleven tools, one per exposed CLI command. Three commands are intentionally not exposed: dashboard (a long-running server that doesn't fit MCP's request/response shape), and cases / save-case (case-fixture management, better driven from the CLI):

• stepbook_init, stepbook_add_step — scaffold a project / add a step.
• stepbook_run, stepbook_check — execute the pipeline; CI-friendly check.
• stepbook_diff, stepbook_snapshot_diff — compare runs / a single unit across runs.
• stepbook_variance — measure run-to-run variance.
• stepbook_q — YAML query against a unit's output (compiles to JSONata; raw JSONata available via the tool's jsonata flag).
• stepbook_list, stepbook_list_steps — browse runs / units.
• stepbook_prune — clean up old run blobs.

Tool results

Each tool returns the CLI's --json envelope as the tool's structuredContent, plus a stringified copy as a text content block (for clients that only consume text). Tools that the CLI exits non-zero on come back as isError: true with the error envelope intact — the same distinction the exit-code contract makes from the command line.

So an agent's flow with MCP looks just like the CLI flow, one envelope at a time — execute, assert, query, re-run from the failing unit, re-check.