mcp-cassette replays recorded MCP sessions as offline test servers

A cassette for Model Context Protocol sessions

A developer publishing as ivermin1123 has introduced mcp-cassette, an Apache-2.0 licensed TypeScript tool that records one real Model Context Protocol (MCP) session into a JSONL file and then serves that file as an MCP server. The result, according to a post on dev.to dated 11 October 2026, is that agent tests can run entirely offline, without credentials, rate limits or network dependencies.

The problem it targets

The post frames a familiar pain point: when an agent calls tools over MCP, its tests depend on infrastructure the suite does not control — a live server, that server's credentials and rate limits, and the network in between. The two common escapes both carry costs. Mocking the MCP client library ties every test to a single SDK, and building a bespoke recorder is work the author says several projects have each duplicated internally. mcp-cassette takes a third route, summed up in the post as "the recording is the server."

Recording a session

Recording runs through npx mcp-cassette record, which positions itself between the client and the real server as a transparent proxy and writes every frame, in both directions, to an open JSONL cassette. Secrets the tool recognises are redacted before they reach the file by default, but the author cautions that pattern matching cannot catch everything, and advises reviewing a cassette before committing it.

Replay behaves like a live server

On replay the cassette is served as a genuine MCP server speaking the protocol over stdio or Streamable HTTP. That means any client in any language connects to it exactly as it would to the live one — no library to import, no product code to change and no transport to wrap. The bundled check command, described as an ordinary MCP client, reportedly cannot distinguish the recording from the real thing.

The replay also preserves session-level behaviour: notifications the server pushed on its own are replayed at their original position in the session, and a single cassette covers both protocol revisions the tool supports — the 2025-11-25 revision and the stateless 2026-07-28 revision. A client that probes on one connection and runs its session on a second can capture both into one file using append mode.

Inside test runners

For test suites, the project ships a vitest integration via useCassette from mcp-cassette/vitest, with a jest counterpart. Tests simply point their MCP client at the cassette's URL instead of a live server. A request the recording does not contain fails the test that issued it, with an explanation — a deliberate guard against stale cassettes silently passing.

Contract gating and poisoning lint

Beyond record and replay, the same binary adds two CI-oriented checks. snapshot writes a server's tool contract to a committed file, and snapshot --check fails the pipeline when that contract changes for the worse, sorting changes into breaking, dangerous, minor and info categories. In the post's example output, a removed tool and a parameter becoming required both count as breaking, while a newly added optional parameter is flagged as dangerous.

check also runs sixteen deterministic rules over the text a server publishes for the model to read — tool descriptions, input schemas, prompts and resources — with each rule citing the OWASP MCP Top 10 risk it addresses. A separate lint command applies the relevant rules to what a recorded server handed back, which the author identifies as the surface where indirect prompt injection appears. Findings can be emitted as text, JSON or SARIF for GitHub code scanning. The author is candid that these are heuristics rather than a model, positioning them as an early-warning tripwire in CI rather than a complete defence.

A bundled GitHub Action, ivermin1123/[email protected], runs both the safety check and the contract gate against the committed snapshot and posts a single comment on the pull request, updated on every push. The tool requires Node 22 or later.

Why it matters

MCP is becoming the connective tissue between agents and external tools, and it inherits the classic problems of integration testing: credentials leaking into CI, flaky networks, rate limits and silent API drift. VCR-style record and replay solved much of this for HTTP testing, and mcp-cassette ports the pattern to MCP in a language-agnostic way — because the cassette is a real server on the wire, the client side never has to change. The snapshot gate targets tool drift, a failure mode that shows up as agents calling tools that no longer exist or require different parameters, while the lint rules address tool poisoning and indirect prompt injection, risks the OWASP MCP Top 10 is only beginning to codify. The caveats are genuine — redaction and linting rest on heuristics — but as a credential-free, offline default for agent test suites, the approach is a practical addition to a young ecosystem.