Skip to content

mcpdev

mcpdev is a command-line client for MCP servers. It connects over stdio or Streamable HTTP, inspects tools, prompts, resources, and templates, calls them, snapshots a public interface and diffs it against another snapshot, runs declarative scenario files, and watches a rebuild without restarting your AI harness.

It treats MCP 2025-11-25 (stateful initialize) and 2026-07-28 (stateless per-request _meta) as distinct wire eras. Protocol eras and fallback rules are defined in Compatibility.

flowchart LR
  Server["MCP server<br/>stdio or Streamable HTTP<br/>wire era 2025-11-25 or 2026-07-28"]
  CLI["mcpdev"]
  Inspect["Inspect<br/>tools, prompts, resources"]
  Operate["Call, prompt, read"]
  Snap["Snapshot → Diff<br/>exit 40 on change"]
  Test["Test<br/>scenario suites"]
  Watch["Watch<br/>rebuild and reconnect"]

  Server <--> CLI
  CLI --> Inspect
  CLI --> Operate
  CLI --> Snap
  CLI --> Test
  CLI --> Watch

An AI agent skill teaches an assistant the CLI contract, so it reaches for mcpdev instead of writing a throwaway client.

Install

Requires Go 1.27. Linux, macOS, and Windows are supported on amd64 and arm64.

go install github.com/phillarmonic/mcpdev/cmd/mcpdev@latest
mcpdev version

Checksummed archives, build_time_policy, and Windows notes are in Installation.

Quick start

Build the in-repo stdio fixture and inspect it:

mkdir -p ./bin
go build -o ./bin/stdio-lab ./testdata/servers/stdio-lab
mcpdev inspect --command ./bin/stdio-lab

Run the declarative suite against the same server:

mcpdev --command ./bin/stdio-lab test testdata/scenarios/valid/stdio.json

Lock a baseline, then diff a later build against it:

mcpdev snapshot --command ./bin/stdio-lab --out testdata/mcpdev/baseline.json
mcpdev diff testdata/mcpdev/baseline.json --command ./bin/stdio-lab

diff exits 40 when the public interface changed and 60 when a catalog could not be captured completely, so a pipeline can gate on the exit code instead of parsing stderr.

Where to go next

Task Page
Launch a local stdio server Stdio servers
Reach a Streamable HTTP endpoint Streamable HTTP
Inspect a rebuilt binary or endpoint Inspect a server
Call a tool, render a prompt, read a resource Call, prompt, and read
Test a target declaratively Declarative tests
Snapshot and diff interfaces Snapshots and diffs
Record and replay fixtures Replay fixtures
Watch a rebuild and reconnect Watch and rebuild
See the wire exchange on stderr Protocol tracing
Debug framing, auth, or timeouts Troubleshooting
Install the release binary in CI GitHub Actions
Drive the CLI from an AI agent AI agents

Reference

Topic Page
Commands, streams, exit classes CLI
Protocol era matrix Compatibility
mcpdev.toml, profiles, interpolation Configuration
Diagnostic records and redaction Diagnostics and redaction
Pagination and capability gating Server inventory
On-disk interface document Snapshot format
Change classification and severity Interface diff policy
YAML/JSON suite document Scenario format
Releases, archives, identity Installation

Contributing

Development

Automation uses drun and its xdrun interpreter (spec: .drun/spec.drun).

xdrun --list
xdrun ci

xdrun ci is the quality gate: formatting, vet, lint, tests, build, security, vulnerability scanning, and a strict build of this site. GitHub Actions runs it on Ubuntu for every ready pull request, plus the focused process, transport, and watch set on Ubuntu, macOS, and Windows.