← mcp-cassette

A test double that speaks the protocol, not your language

The cassette is itself an MCP server, so any client in any language connects to it exactly as it connects to the live one: no library to import, no product code to change, no transport to wrap.

That sentence is one line to write and considerably more than one line to implement. This is what it costs: an incremental parser for a streaming format whose line endings are not obvious, two protocol lifecycles in one file, and a header that cannot be written when the file is opened.

Testing a client means owning a server

A test suite for an MCP client needs a server. There are two usual ways to get one, and both charge you.

Run the real server. Correct by construction, and it costs what real things cost: credentials in CI, rate limits, flaky network failures you did not schedule, state that survives runs, and a counterparty free to change its answers without telling you. Tolerable once; not on every push.

Write a fake and run it in the same process. Fast, hermetic, no credentials, and two properties easy to miss while writing it. It is a library for one language, so a team with clients in two languages writes and maintains two fakes. And it is assembled from your reading of the specification rather than from what a server put on the wire, with nothing keeping the two in step. It passes because it agrees with you.

Before deciding which parts of this project were worth keeping, we measured the population it serves: 158 public MCP servers, read by hand where the automated pass was ambiguous. Of those, 83 test through the protocol under the strict reading and 89 under the looser one, which is 52.5% and 56.3%; the honest bracket after accounting for both measurement errors found is 45 to 60%. Among those 83, 16 (19.2%) reach for an official SDK's in-memory transport to avoid live APIs. The method, including two measurement defects that moved the number and were reported rather than quietly fixed, is in docs/research/01-reality-check.md.

Read that the way it falls: protocol-layer testing is already a mainstream habit, not a frontier, and most of that majority got there without this tool. The open question is what sits at the other end, and whether it is the same artifact for every language you write clients in.

record: bytes, not a summary

The recorder is a transparent stdio proxy. Point your client at it instead of at the server, give it the server command, and it forwards bytes verbatim in both directions while writing every JSON-RPC frame it recognises to an append-only JSONL file (src/record.ts). Neither side can tell it is there, and what lands in the file is what the server said rather than what a wrapper decided it meant. Output that is not JSON-RPC at all, such as a chatty server's stdout logs, is preserved as raw entries, so the transcript stays faithful even to a misbehaving server.

replay: the recording answers

Replay reads that file and serves it as an MCP server on stdio (src/replay.ts). Requests are fingerprinted and matched against recorded pairs: lifecycle calls by method, tools/call by tool name plus stable-stringified arguments, everything else by method plus params with the volatile parts (_meta, pagination cursors) removed. Matching is exact, so order does not matter: a reordered test run still lands, and repeated identical calls consume their recordings in turn. A miss reports the closest recorded fingerprint and exactly which component diverged. --on-miss warn adds one tolerance, for arguments that change every run: it may answer a miss with the next unused recording of the same method, and says so on stderr every time.

The precise version of that tolerance is to say which fields change. --volatile /arguments/requestedAt declares one, repeatable, optionally scoped to a single method as tools/call:/arguments/requestedAt, and the same list may live in the cassette header as volatile so the file carries its own declaration; the flags add to it. A declared pointer is dropped from the request's params on both sides, the recorded one as the index is built and the live one as it arrives, so a request differing only in a timestamp or a generated id lands on its recording while everything else still matches exactly. The miss diagnosis drops them too: the paths it names are the ones that really diverged, never the one the session already said would move.

The claim in the pitch is testable, so here it is tested: the same health check against a live reference server, then against the recording of it.

server: mcp-servers/everything@2.0.0  protocol: 2025-06-18
surface: 13 tools, 7 resources, 4 prompts
[OK] no findings
result: PASS (0 error(s), 0 warning(s), gate: error)

Those four lines are the output twice: once with the real server running, once with nothing but a file. Now the part a fake in your own test suite cannot do, using the official Python SDK, which has never heard of this project:

SERVER = StdioServerParameters(
    command="npx",
    args=["-y", "mcp-cassette@0.10.0", "replay", "everything.cassette.jsonl"],
)

async with stdio_client(SERVER) as (read, write):
    async with ClientSession(read, write) as session:
        init = await session.initialize()
        tools = await session.list_tools()
server: mcp-servers/everything 2.0.0
protocol: 2025-06-18
tools: 13
first three: ['echo', 'get-annotated-message', 'get-env']

One cassette, two clients in two languages, identical answers. The Python side imports nothing from here: it launches a subprocess and speaks stdio, exactly as it would to the real server. The rest of this page is what that costs to make true.

Server-sent events are not "split on a blank line"

Over HTTP, an MCP response may arrive as a stream, and recording it faithfully means parsing it the way the specification says rather than the way it looks. The parser is src/sse.ts, and it implements WHATWG HTML's "interpreting an event stream" and nothing else. The rules that a hand-rolled split would get wrong:

The chunk-boundary rule is the one with teeth: it fails only under timing you do not control and cannot be reproduced by reading the code. So it is tested by exhaustion rather than by example. One stream carrying all three line endings, a comment, a multi-line data field and a trailing bare CR is fed at every read size from 1 byte to the whole string, and every size must produce the same three events (tests/sse-capture.test.ts, "splits the same events no matter where the reads fall").

Two lifecycles, one file

The protocol has two eras alive at once, and a recording has to know which one it captured.

The classic lifecycle (revisions up to 2025-11-25) opens with initialize, then notifications/initialized, then requests, and the server states its protocol version in that result. The 2026-07-28 revision is stateless: there is no handshake, every request carries _meta, and server/discover answers what initialize used to. Sessions are gone in that world, and so is the standalone GET stream.

A cassette records the era it saw in the header line, and replay serves in that era rather than guessing from frames (src/cassette.ts, src/http-replay.ts). The migration rule is one function, and worth stating out loud rather than leaving to a reader of the type declaration:

export function cassetteEra(header: CassetteHeader): Era {
  return header.era ?? "legacy";
}

A cassette with no era field is legacy by definition. That is not a fallback chosen for convenience; it is what keeps every file recorded before the field existed working, with no migration step. The stdio recording made for this page is one of them: its header carries no era, and both clients above were served, correctly, as legacy.

A header that cannot be written yet

Which leaves an ordering problem. The header is line 1 of an append-only file, so it is written before anything else. But the era is decided by the first successful exchange, which has not happened when the file is opened, and cannot be inferred from the first request: a dual-era client may try server/discover, get an error, and fall back to initialize. Guessing from that attempt records a lie.

So the HTTP recorder opens the writer in deferred-header mode: entries are buffered in memory, and setEra() writes the header and flushes everything behind it once an exchange has actually succeeded (src/cassette.ts, src/proxy.ts). Success is the whole test, not whether the method was a lifecycle one. A session where nothing succeeded flushes at close with the era omitted, which the reader treats as legacy by the rule above, and changing the era after the header has reached disk throws rather than pretending. The case easiest to get wrong is tested: a server/discover answered with a JSON-RPC error over a stream leaves the header with no era, and still records the failure.

A notification has a position, not just a payload

A server also speaks when nothing asked it to. The legacy era pushes notifications/tools/list_changed unsolicited; the 2026-07-28 revision replaced that and the HTTP GET endpoint with subscriptions/listen, one long-lived request the server acknowledges with notifications/subscriptions/acknowledged and then feeds, tagging every frame with io.modelcontextprotocol/subscriptionId. Either way the frame answers no request, so replay cannot wait to be asked for it. It has to decide when to send it.

Sending it at connect is wrong: a client that hears "the tool list changed" before it has read the tool list learns nothing, and a test that depends on the order is testing replay rather than the client. Sending it never is what v1 did, and it is why a client whose whole job is reacting to change could not be tested against a cassette at all. So the rule is the recording's own order, stated once and implemented in one place:

A server-initiated frame is anchored to the last client request whose answer preceded it in the recording, and replay emits it immediately after it answers that request. A frame recorded while a request was still outstanding belongs to that request instead, and is emitted immediately before its answer. A frame anchored to a request the client never sends is reported, not emitted.

The middle sentence is the one a reader skips and an implementation cannot. On stdio a request's own notifications/progress sits in the file between the request and its response, so the first sentence alone would send a call's progress before the client had sent the call. Position is read from the recorded timestamps and only then from file order, because an HTTP recording writes a whole stream as one entry when the stream closes while stamping each frame as it arrived: by file order, every frame of a long-lived stream looks like it came after requests it actually preceded.

The anchor is the recorded answer itself, by identity, not its fingerprint: a cassette that recorded the same call three times releases the frames of the third recording when the third call is answered, and not before. A subscriptions/listen is anchored by its acknowledgment, because that is what answers it; the recording almost never holds a JSON-RPC response for one, since the server sends that only when it ends the subscription gracefully. The subscription id in every replayed frame is re-keyed to the id the client's own listen request carried, so a client correlates on the id it chose rather than on one from a session that is over.

The last clause is the one worth defending. A recorded notification whose anchor never arrives could be sent anyway, at the end, or at connect. Each of those puts a frame somewhere the recording never put it, and a client that behaves differently because of it has been taught something false about the server. Replay says how many it held back instead:

mcp-cassette replay: 1 recorded server-initiated frame(s) were not replayed: the client never sent the request each one follows

Over HTTP the same rule runs through a stream rather than through stdout. The legacy standalone GET stream and a modern subscription stream are both held open and fed at the anchors, and a client that opens the stream after the anchor was already answered gets the frame on connect, because that is where the recording put it relative to what this session has done so far.

A task is a sequence, and sequences have two ends

The io.modelcontextprotocol/tasks extension is the one place where the answer to a request is not a value. A server that will take a while answers a tools/call with a handle (resultType: "task") instead of a result, and the client polls tasks/get until the status is terminal. The obvious worry is timing: the client on replay will not poll at the interval it polled at while recording.

It is not a worry, and the reason is worth stating because it is the same reason the rest of this page keeps giving. Replay is driven by the recording's order, not by a clock. Every poll for one task carries the same params, so they share a fingerprint and come out of one pool in recorded order: the client sees the recorded state sequence, one state per poll, and reaches the recorded end on the poll the recording ended on. Poll twice as fast and nothing changes. Poll fewer times and the session is still clean, because a client that lost interest is a client, not a failure.

What does need deciding is the poll after the last recorded one, and the extension's own terminal states decide it:

Once the recorded sequence for a task id ends in a terminal status (completed, failed or cancelled), that last answer is served again for every further poll, without being consumed, in the shape the recording holds it in: a streamed answer is re-served as that stream, a JSON one as JSON. If the recording ended on a non-terminal status, a further poll is a miss whose reason names the task id and the status the recording stopped on.

Re-serving a terminal answer is not a tolerance, it is what the extension says is true: a finished task does not change. It is also the only thing that can answer a client which persisted its task id and came back after its own restart, which the extension explicitly tells clients to do, for as long as the replay holding the recorded sequence outlives that restart; restart the replay too and the pool is whole again, so the same id reads the sequence from its start. The other half is the half that would be tempting to fudge. A recording that stopped while the task was still working holds no later state, and the convenient move is to keep serving working forever; that turns a client's completion check into an infinite loop against a file that was never going to finish. So it misses, and the message says which task and what to do about it:

mcp-cassette replay: fingerprint miss for "tasks/get": the recording holds 3 poll(s)
for task "task-0001" and ends with status "working", which is not terminal: the task
was still running when recording stopped, so there is no later state to serve.
Re-record until the task reaches completed, failed or cancelled

Which shape the recorded server answered a poll in makes no difference to any of this. Over HTTP an answer arrives as a stream unless the server was configured to send JSON, and that is not the default, so most recorded polls are chunks entries rather than plain frames; the rule reads the task's state out of either, and gives a re-served answer back in the shape it was recorded in. One thing the rule does take away: --on-miss warn borrows the next unused recording of the same method, and for a poll that recording is an answer about a different task, so a poll is one of the requests warn refuses to borrow for. A poll past a non-terminal recording misses under warn exactly as it does under error.

Two neighbouring methods needed no new machinery at all, which is the part worth checking rather than claiming. tasks/update carries the client's inputResponses, which is the same field an MRTR retry carries, so it already falls under the rule that an answer bound to an input is never lent to a different one: answer staging where the recording answered production and it misses, under --on-miss warn too. And notifications/tasks is a server-initiated notification on a subscriptions/listen stream, so the position rule above already carries it, re-keyed to the subscription id the client's own listen request used.

What replay does not do

Three limits, stated as they are in the machine-readable index:

The first two are consequences of the design rather than gaps in it. A recording is a statement about one past session, and treating it as one about the present is the mistake this tool makes easy, which is why verify re-fires recorded requests at a live server and diffs the answers.

The third is a narrower gap than it was. Notifications play back, so a client that reacts to a changing tool list can be tested against a file. A server that asks the client something still cannot: under 2026-07-28 those flows became input_required results, which replay does reproduce, but a legacy cassette holding a sampling/createMessage request has no replay path. Test a client that depends on that traffic against a live server.

Three commands

Node 22 or later, and network access for the first one only.

npx -y mcp-cassette@0.10.0 check --stdio "npx -y mcp-cassette@0.10.0 record -o everything.cassette.jsonl -- npx -y @modelcontextprotocol/server-everything@2026.7.4 stdio"

npx -y mcp-cassette@0.10.0 check --stdio "npx -y mcp-cassette@0.10.0 replay everything.cassette.jsonl"

npx -y mcp-cassette@0.10.0 lint everything.cassette.jsonl

The first drives the recording proxy with the health check, so the check is the client and you need none of your own. The second runs the identical check with no server and no network. The third reads the finished file: its header against its own frames, and what the recorded server returned, because a tool result reaches the model with the same authority a tool description does and the cassette is the only place that text still exists. On a clean recording it says so and stops:

everything.cassette.jsonl: header and frames agree

On one carrying an injection it names the frame by request id and method and the JSON path of the string that matched, so you open the file at the exchange rather than search it. Those findings are warn: reported, never gated. Only a header that contradicts its own frames exits non-zero.

Every version here is pinned, and not only because the specification is moving. An unpinned npx will reuse a copy already in the local cache instead of resolving the registry: on the machine these commands were run, bare npx mcp-cassette ran 0.1.1 while latest was 0.4.0, silently, with different output. Pin, or install once and call the binary.

From there, point whatever client your tests already use at mcp-cassette replay <cassette>, in whatever language, and change nothing else.