mcp-server

mcptest mcp-server is a stdio MCP server that exposes the mcptest engine to local agents. It lets you ask Claude Code, Cursor, or any MCP-aware client questions like "which tests just failed?" or "show me the cassette for the create_issue path" without leaving your editor.

The MCP server is a subcommand of the main mcptest binary, so you install one CLI and get both the test runner and the agent surface.

Run this example. examples/mcp-server-config/ registers the mcptest stdio MCP server in Claude Code or Cursor, with a read-only config and a read-write variant.

mcptest mcp-server --workspace .

Install

cargo install mcptest
# or build from the workspace:
cargo build --release -p mcptest

The release binary lands at target/release/mcptest.

Register

Claude Code

Edit .claude/mcp.json in your project root:

{
  "mcpServers": {
    "mcptest": {
      "command": "/absolute/path/to/mcptest",
      "args": ["mcp-server", "--workspace", "."]
    }
  }
}

Add "--enable-writes" to the args array if you want the agent to be able to trigger runs and record cassettes.

Cursor

Settings, MCP servers, add a stdio server with the same command and args.

mcp-inspector

For interactive exploration:

npx @modelcontextprotocol/inspector mcptest mcp-server --workspace .

The inspector UI lets you call every tool manually and inspect the resource catalog without writing agent code.

Tools

Read-only tools are always available. Write tools require --enable-writes.

Tool	Mode	What it does
`list_runs`	read	Lists recent run JSON files in the cache. `limit` argument (default 20).
`get_run`	read	Returns one run by `run_id`.
`list_cassettes`	read	Lists cassette files under `<workspace>/.mcptest/cassettes/`.
`get_cassette`	read	Returns one cassette by `name` (with or without extension).
`get_coverage`	read	Returns the coverage block from the most recent run.
`get_doctor_report`	read	Spawns `mcptest doctor` and returns its output.
`trigger_run`	write	Spawns `mcptest run`; accepts optional `filter` and `profile` strings.
`record_cassette`	write	Spawns `mcptest record --cassette <cassette_name>`.

Resources

URI	Content
`mcptest://runs/recent`	JSON array of recent runs in the workspace
`mcptest://config`	YAML rendering of `mcptest.yml`
`mcptest://cassettes/{name}`	Cassette content by stem

The server advertises resources.subscribe so a future revision can stream filesystem-watch updates. The current binary returns the snapshot on each resources/read; subscription delivery is wired through the notify crate in the main loop.

Agent workflows

A short menu of prompts that exercise the tools:

"Show me the last three runs and tell me what changed."
"The CI just failed on run-2026-05-15-abc. Get the run, summarize the failures, and propose fixes."
"List every cassette and tell me which ones are older than two weeks."
"Re-record the create_issue.cassette against staging and re-run the suite." (requires --enable-writes)
"Read mcptest://config and explain the discovery rules to me."

Workspace layout

By default the server reads:

<workspace>/mcptest.yml for the effective config.
~/.cache/mcptest/runs/*.json for runs.
<workspace>/.mcptest/cassettes/* for cassettes.

You can point a workspace at custom directories programmatically via Workspace::with_paths if you embed the server in another binary.

Security

The read-only tools touch only files the calling user can already read. Write tools spawn mcptest subprocesses, so they inherit your normal permissions; the server adds no escalation of its own. Keep --enable-writes off for production agents you do not fully trust.