<div align="center">

mcprec

record & replay any MCP server

Capture stdio. Replay deterministically. Test agent tools without the network.

</div>

A transparent middleware for the Model Context Protocol. Wraps any stdio MCP server, captures every JSON-RPC frame to a transcript, and replays that transcript later as a fake server. The result: deterministic, network-free, billing-free fixtures for agent tests that would otherwise be flaky against a live API.

Why

Tests against real MCP tools are flaky for the same three reasons every external-service integration test is flaky: network blips fail CI runs that have nothing to do with the code under test, parallel runs exhaust API rate limits, and remote contracts drift overnight (a field gets renamed, the test that passed Tuesday breaks Wednesday).

Hand-written mocks fix the first two but quietly worsen the third: a mock returns what the test author believes the server returns, and by the time those beliefs diverge from reality the tests are validating fiction. The HTTP world solved this with record-and-replay tools like VCR. mcprec does the same for MCP: capture the actual wire bytes once against a real server, replay them forever, fail loudly when a method/params combo no longer matches the recording, and re-record with one command when the contract genuinely changed.

✦ Install

npm install -g mcprec
# or one-shot:
npx mcprec record --out fixture.jsonl -- npx @modelcontextprotocol/server-github

✦ Modes

Record

mcprec record --out fixtures/github.jsonl -- \
  npx @modelcontextprotocol/server-github

Your agent talks to the real server-github over stdio; every JSON-RPC frame in both directions lands in github.jsonl. The MCP server runs exactly as it would normally - no proxy URL, no certificate shenanigans, nothing for it to detect.

Replay

mcprec replay fixtures/github.jsonl

The binary that gets exec'd by your agent is now mcprec replay. It serves the recorded transcript as a fake MCP server, matching by (method, params). Mismatch → loud error, full diff.

Inspect

mcprec inspect fixtures/github.jsonl

Pretty-prints a recorded session: timeline view of requests and responses, syntax-highlighted JSON, inferred contract (which methods, which tools, how many calls each).

Diff

mcprec diff fixtures/github.old.jsonl fixtures/github.new.jsonl

Compares two transcripts. Surfaces contract drift: methods that now return new fields, methods that no longer exist, parameter shapes that changed. The fixture-update workflow.

✦ Transcript format

Newline-delimited JSON. One frame per line. Direction + relative timestamp + the original message:

{"t":0.000,"dir":"→","msg":{"jsonrpc":"2.0","id":1,"method":"initialize"}}
{"t":0.012,"dir":"←","msg":{"jsonrpc":"2.0","id":1,"result":{"capabilities":{}}}}
{"t":0.043,"dir":"→","msg":{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_issues","arguments":{"q":"is:open"}}}}
{"t":0.890,"dir":"←","msg":{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"..."}]}}}

Plain text. Diffable in PRs. Hand-editable when you need to redact a token. Friendly to git, friendly to humans, friendly to CI.

✦ vs. mocks and snapshot tests

	Mock	Snapshot tests	mcprec
Source of truth	Author's belief	Real once	Real always
Catches drift	No	Sometimes	Always (replay fails)
Re-record on contract change	Manual rewrite	Manual	One command
Setup cost	High (write the mock)	Medium	Low (just run once)
Wire-level fidelity	None	Output only	Full JSON-RP