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¶
- Fixture catalog and how to add one: Test fixtures.
- Official requirement sets, pinned per revision: Official MCP conformance.
- End-to-end stdio loop: Stdio developer loop.
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.