Introduction

This is the reader’s guide to mcp-conformance, an independent, trace-based conformance toolkit for the Model Context Protocol (MCP). It judges whether an MCP implementation conforms to a specific spec revision — the one the recorded session declares, 2026-07-28 or 2025-11-25, or both at once in a single pass — and, just as importantly, it is built so that an ecosystem with its own authoritative test suite has reason to trust the verdict.

Status: 0.x on crates.io. Before 1.0 the public API and the verdicts may change between minor releases; the changelog says so explicitly when they do; STABILITY.md lists what each release keeps stable.

Versions of this book. The site’s root documents the newest release. Each release’s own book stays at /vX.Y.Z/, and the unreleased main branch is at /dev/. The selector in the menu bar switches between them; a page that documents anything but the newest release says so at the top.

The one idea

The validator’s input is a trace: an ordered, serialized record of a protocol interaction. Its engine is a pure function — &[TraceEvent] -> Report — with no network, no clock, and no I/O of its own. Capturing the trace is mcp-trace-capture’s job — a stdio wrapper and HTTP proxy that forward bytes unchanged — and judging it is the validator’s only job. That split is what makes a verdict deterministic, replayable, language- and SDK-agnostic, and — because it is reproducible from a committed file — auditable rather than a “trust us.”

The credibility mechanism is the agreement check: on every CI run the reference server is driven by the official conformance suite (pinned, at 2025-11-25; the 2026-07-28 surface is measured weekly against the suite’s pre-release), the same sessions are captured as traces, and this toolkit’s verdicts are diffed against the official runner’s. Agreement is the default; an unexplained divergence fails the build. A validator whose verdicts are checked against the recognized authority on every commit is calibrated, not merely asserted to be correct.

The crates

How this book is organized

Each chapter is a curated entry point. The planning documents — charter, ecosystem register, architecture, conformance strategy, engineering standards, security model, roadmap, and decision records — remain the single source of truth, and every chapter links to the authoritative document behind it.

To use the tools:

• Getting started — install, record a session, judge it, and read the report.
• Capturing from your client — the configuration for Claude Desktop, VS Code and Cursor, and driving a server with no client at all.
• Reading a report — what to do about each outcome, triaging a finding, raising coverage, and disputing a verdict.
• Using it in CI — exit codes, JUnit and SARIF, the GitHub Action, and the container image.
• Upgrading — what a release may change, and how to compare verdicts across versions before you move a gate.
• Troubleshooting — what the common failures mean.

How it works:

• Architecture — why judge traces instead of live sessions, and the design trade-offs that follow.
• The trace format — the JSON Lines schema, with a worked example embedded from the README so it cannot drift.
• Two revisions at once — how one trace is judged against 2025-11-25 and 2026-07-28 together, and what a migration looks like when it is measured instead of estimated.
• The trace corpus — the golden good/violation fixtures and their provenance, embedded from corpus/README.md.
• Conformance results — the published tier-gap measurements of real SDKs against the official suite.

Reference:

• Requirements — every clause of 2026-07-28 and 2025-11-25 under its ID: its level, the party it binds, the verbatim quote with a link to the published text, and the checks that judge it or the reason none can.
• Glossary — the terms the book and the tools’ output use.

Getting started

Three steps: install the two tools, record a session of your server or client, and judge the recording. Nothing here depends on the language or SDK your implementation uses — the tools read and write bytes on the wire.

Install

cargo install mcp-trace-capture mcp-trace-validator

cargo binstall mcp-trace-capture mcp-trace-validator fetches prebuilt binaries instead of compiling (Linux x86_64 and aarch64, macOS, Windows x86_64). To build the unreleased source, which may be ahead of the release: cargo install --locked --git https://github.com/tomtom215/mcp-conformance mcp-trace-capture mcp-trace-validator.

From npm or PyPI (not yet released). From the first release after 0.6.0, the same prebuilt binaries install without Rust:

npx mcp-conformance --version          # one-off, or: npm install -g mcp-conformance
pip install mcp-conformance            # into the active environment

Both put mcp-trace-capture, mcp-trace-validator and mcp-conformance on your PATH, as the release’s own binaries, byte for byte: npm installs the one @mcp-conformance/<os>-<cpu> package that fits your machine as an optional dependency of mcp-conformance (no install script, nothing downloaded beyond the packages), and pip installs the wheel for your platform. Packages exist for the five targets above; elsewhere, install from source. With npm, keep optional dependencies enabled (--omit=optional removes the binaries). If a Python environment’s scripts directory is not on PATH, python -m mcp_conformance runs the workbench. Until that release, neither registry has the packages.

Record a session

mcp-trace-capture sits between a client and a server, forwards every byte unchanged, and writes what crossed the wire to a trace file.

A stdio server. Have your client launch the wrapper, with the server’s own command after --:

mcp-trace-capture -o session.jsonl stdio -- python my_server.py

When a client launches it from its configuration file, give -o an absolute path with {session} in the file name — -o /tmp/traces/{session}.jsonl — so each launch writes the next numbered trace (001.jsonl, 002.jsonl, …). Clients relaunch servers, and the wrapper never overwrites a trace, so without {session} the second launch would refuse to start unless --force let it overwrite the first. The capture tool’s README shows the configuration for desktop clients and for the Python and TypeScript SDKs’ stdio clients.

A Streamable HTTP server. Run the proxy in front of it and point the client at the proxy instead:

mcp-trace-capture -o session.jsonl http --upstream http://localhost:3000
# the client connects to http://127.0.0.1:8080/mcp

Stop the proxy with Ctrl-C when the session is over.

Record one session per trace. A trace is judged as one session, so two clients recorded together look like one client breaking the rules (the validator says so when it sees more than one handshake). For a proxy that serves several clients, put {session} in -o and it writes each client session to its own file. 2026-07-28 sessions carry no session id for it to tell them apart by, so run one proxy per client there.

Judge it

mcp-trace-validator validate session.jsonl

Here is a short session that reuses a request id — its fourth line sends tools/list with the id the initialize already used:

{"seq":0,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-host","version":"1.0.0"}}}}
{"seq":1,"direction":"server-to-client","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"my-server","version":"1.0.0"}}}}
{"seq":2,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","method":"notifications/initialized"}}
{"seq":3,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"method":"tools/list"}}

and the validator answers with the violated clause, addressed to the offending event:

  FAIL  BASE-003 (MUST NOT)
        [client] seq 3: request "tools/list" reuses id 1, already used by the same party at seq 0
        spec: "The request ID MUST NOT have been previously used by the requestor within the same session."
        see:  https://modelcontextprotocol.io/specification/2025-11-25/basic#requests
totals: 17 pass, 1 fail, 0 warn, 246 excluded, 0 unsupported, 6 not applicable, 78 not observed
wire schema: pass (4 messages valid)
verdict: fail

Each finding names the clause (BASE-003) and its strength (MUST NOT), the event in the trace (seq 3 — every event carries a seq, its position in the recording), what was wrong, the sentence of the specification it breaks, and a link to it. The exit status is the verdict: 0 pass (warnings included, unless --strict), 1 a clause failed (or warned, under --strict), 2 the run could not judge or report — a bad invocation (an unknown flag, a trace file that cannot be read), nothing judgeable (a trace with nothing in it, or one declaring only revisions this build does not know), or output not written — and 3 the trace is malformed. STABILITY.md keeps these meanings fixed. Reading a report goes further: triaging a finding, raising coverage, and disputing a verdict.

Reading a report

The report lists what needs attention; --all lists every clause. The totals always count every clause the revision has, in seven outcomes:

So a pass verdict says nothing this session did broke a clause. How much it covers is in the totals: a short session observes few clauses, and a richer session (more features, errors, pagination, both transports) puts more of the specification to the test.

Which revision. The validator judges the revision the session declares — in initialize, in each request’s _meta, or in the MCP-Protocol-Version header — and says how it chose: (declared by the trace). --revision 2025-11-25 overrides it; naming two (--revision 2025-11-25 --revision 2026-07-28) judges the session under both and shows where they differ. This build knows 2025-11-25 and 2026-07-28. A session of an older revision, such as 2025-06-18, is refused with an explanation rather than judged against rules it was not playing by.

Several traces. mcp-trace-validator validate traces/*.jsonl judges each, prints a section per trace and a closing tally, and exits with the worst trace’s status.

Other formats. --format json is the whole report as data, described by a JSON Schema; --format junit is a test report for CI; --format sarif is a SARIF 2.1.0 log for code scanning. Using it in CI covers all three.

Capturing from your client

A client records nothing by itself: you put mcp-trace-capture between it and the server. For a stdio server, the client launches the capture wrapper, which launches the server. For a streamable-HTTP server, the client talks to the capture proxy, which forwards to the server. Either way the bytes pass through unchanged and the trace is written as they go.

Two rules hold for every client configuration below:

• Give -o an absolute path. A desktop client starts servers in a working directory of its own choosing; a relative path lands somewhere you will not look. Without -o, the trace is mcp-trace.jsonl in that directory.
• Put {session} in the file name. Clients relaunch their servers — at startup, on reconnect, when you reopen a window — and the wrapper never overwrites a trace. With {session}, each launch writes the next number (my-server-001.jsonl, my-server-002.jsonl, …); without it, the second launch refuses to start. The directory must exist.

Desktop applications often start without your shell’s PATH, so use the absolute path to mcp-trace-capture as the command if the client cannot find it (which mcp-trace-capture prints it). Restart the client after editing its configuration.

Claude Desktop

The configuration file is claude_desktop_config.json, at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows (Settings → Developer → Edit Config opens it). Servers go under mcpServers; move the server’s own command behind --:

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-trace-capture",
      "args": [
        "-o", "/Users/me/traces/my-server-{session}.jsonl",
        "stdio", "--",
        "python", "/Users/me/src/my_server.py"
      ]
    }
  }
}

On Windows, write the paths with escaped backslashes ("C:\\Users\\me\\traces\\my-server-{session}.jsonl"). The server’s stderr still reaches the client’s own log, as without the wrapper.

VS Code

A workspace’s servers are in .vscode/mcp.json, under servers. A stdio server:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "mcp-trace-capture",
      "args": [
        "-o", "/home/me/traces/my-server-{session}.jsonl",
        "stdio", "--",
        "node", "/home/me/src/my-server/build/index.js"
      ]
    }
  }
}

A streamable-HTTP server is an entry with "type": "http" and a url: start the proxy in front of the server, and give VS Code the proxy’s URL instead of the server’s:

mcp-trace-capture -o '/home/me/traces/http-{session}.jsonl' http --upstream http://127.0.0.1:3000/mcp

{
  "servers": {
    "my-http-server": {
      "type": "http",
      "url": "http://127.0.0.1:8080/"
    }
  }
}

The proxy’s root path is the --upstream URL itself, so http://127.0.0.1:8080/ reaches http://127.0.0.1:3000/mcp; the proxy prints the URL to use when it starts. Stop it with Ctrl-C when the session is over: the trace is closed then.

Cursor

Cursor reads ~/.cursor/mcp.json (every project) and .cursor/mcp.json (one project), with servers under mcpServers. A stdio server has the same shape as Claude Desktop’s above. A remote server is an entry with a url, which for a recording is the capture proxy’s, as for VS Code:

{
  "mcpServers": {
    "my-http-server": {
      "url": "http://127.0.0.1:8080/"
    }
  }
}

Other clients

Most clients that launch stdio servers take a command and its arguments, in one of the two shapes above; the wrapper goes in front of both, with the server’s command after --. A client that connects to a URL is pointed at the proxy. The official SDKs’ stdio clients, for test suites, are covered in Using it in CI.

No client at all

To exercise a server without a client application, mcp-reference-host drives it: it lists the tools and calls each once with arguments derived from its schema, and with --sweep also drives prompts, resources, templates and completion. --trace-dir records the session:

cargo install mcp-reference-host
mcp-reference-host --server-cmd "python my_server.py" --sweep --trace-dir traces/
mcp-reference-host --url http://127.0.0.1:3000/mcp --sweep --trace-dir traces/
mcp-trace-validator validate traces/*.jsonl

--server-cmd is split on spaces, so a path containing one needs a wrapper script. --protocol-version 2026-07-28 speaks the stateless revision instead of 2025-11-25. The host’s own recording sits at the message seam and carries no HTTP headers; when transport behaviour matters, record through mcp-trace-capture instead, with the host pointed at the proxy. mcp-reference-host --help lists the rest — --subscribe, --cancel, --log-level and --probe each drive clauses a plain run leaves unobserved.

To exercise a client, run mcp-everything-server --transport http behind the proxy and point the client at it; with a known-good server on the other end, a finding is almost certainly the client’s.

Recording an SDK’s server

Capturing from your client records a session your own MCP host drives. This chapter is the other way round: you have a server built on an official SDK and want to know what it puts on the wire. It is worked through on the TypeScript (both of its lines) and Python SDKs’ own conformance servers — the servers each SDK runs the official suite against — but nothing here is specific to them: any Streamable HTTP server can stand in.

The commands are not copies. Each block below is included, by mdBook anchor, from interop/matrix.sh, the script the weekly scheduled job runs to keep the cross-SDK matrix true; cargo xtask sdk-matrix --check fails if this chapter stops including them, or the job stops running the script. What you read is what the job executed.

Prerequisites

Build the recorder and the validator, then install the pinned SDKs:

cargo build -p mcp-trace-capture -p mcp-trace-validator
cd interop
./setup.sh

setup.sh installs each SDK at the version interop/sdk-pins.env names, every one with integrity: npm from package-lock.json (npm ci), Python from the hash-locked requirements.txt (pip --require-hashes), Go from go.sum, Rust from Cargo.lock. A conformance server that lives in an SDK’s repository rather than its package is fetched from the exact commit the pins name and refused unless its SHA-256 matches. It needs node 20+, Python 3.11+, go, cargo and git.

Recording one session

Every session is the same four steps — start the server, put mcp-trace-capture’s proxy in front of it, drive one session through the proxy, stop the proxy so it writes the trace — followed by judging it:

# record NAME REVISION PORT -- SERVER...
#
# Starts SERVER (listening on 127.0.0.1:PORT), puts the capture proxy in
# front of it on PORT+100, drives one session through the proxy with the
# client for REVISION, stops the proxy (which writes the trace), and judges
# the trace. The ports are fixed rather than ephemeral because the proxy
# records the Host header, and a committed trace should not change with them.
record() {
  local name=$1 revision=$2 port=$3 proxy=$(($3 + 100)) status=0
  shift 4
  "$@" > "$OUT/$name.server.log" 2>&1 & local server=$!
  pids+=("$server")
  wait_for_port "$port"
  "$CAPTURE" -o "$OUT/$name.jsonl" http \
    --upstream "http://127.0.0.1:$port" --listen "127.0.0.1:$proxy" \
    2> "$OUT/$name.capture.log" & local capture=$!
  pids+=("$capture")
  wait_for_port "$proxy"
  export INTEROP_ERRORS=record
  case $revision in
    2025-11-25) node ts-client.mjs http "http://127.0.0.1:$proxy/mcp" || status=$? ;;
    2026-07-28) "$PYTHON" py-client.py http "http://127.0.0.1:$proxy/mcp" || status=$? ;;
  esac
  kill -INT "$capture"; wait "$capture" || true
  kill "$server" 2>/dev/null || true; wait "$server" 2>/dev/null || true
  judge "$name" "$revision" "$status"
}

The client is chosen by revision, and is the same for every server: the TypeScript SDK’s v1 client (ts-client.mjs) speaks 2025-11-25, the Python SDK’s (py-client.py) speaks 2026-07-28. Each lists what the server advertises, calls a tool, calls one that does not exist, reads a resource and gets a prompt. With INTEROP_ERRORS=record an error answer is logged and the session carries on: the server’s answer is the evidence, so the client must not stop at it.

The TypeScript SDK, v1

The v1 line is the single package @modelcontextprotocol/sdk, in maintenance. The server is test/conformance/src/everythingServer.ts from the SDK’s repository at the release tag. It imports the SDK by its path inside that repository; setup.sh rewrites those imports to the published package, so it runs on the pinned npm release, and tsx runs the TypeScript directly:

record sdk-typescript-2025-11-25 2025-11-25 38301 -- env PORT=38301 node_modules/.bin/tsx upstream/ts-everything-server.ts
record sdk-typescript-2026-07-28 2026-07-28 38301 -- env PORT=38301 node_modules/.bin/tsx upstream/ts-everything-server.ts

The second line is a session the server cannot serve: the TypeScript SDK’s 1.x line implements the specification up to 2025-11-25 (its SUPPORTED_PROTOCOL_VERSIONS stops there), so the Python client’s discovery falls back to the initialize handshake. py-client.py exits 3 when that happens, and the script files the recording as …not-served.jsonl rather than judging a session nobody asked for.

The TypeScript SDK, v2

The v2 line is a set of packages, @modelcontextprotocol/server and its companions, and it does serve 2026-07-28: its server answers server/discover with supportedVersions of ["2026-07-28"], and still answers the initialize handshake for 2025-11-25, from one process. The server is the same path in the SDK’s repository, test/conformance/src/everythingServer.ts, at the release tag. Nothing is rewritten: the file imports the published packages by name, which setup.sh installs from the lockfile (@modelcontextprotocol/server, node and express, pinned together in sdk-pins.env). Both revisions are recorded:

# The v2 line's server answers both revisions from one process: the initialize
# handshake for 2025-11-25 and server/discover for 2026-07-28.
record sdk-typescript-v2-2025-11-25 2025-11-25 38305 -- env PORT=38305 node_modules/.bin/tsx upstream/ts2-everything-server.ts
record sdk-typescript-v2-2026-07-28 2026-07-28 38305 -- env PORT=38305 node_modules/.bin/tsx upstream/ts2-everything-server.ts

The Python SDK

The server is the SDK repository’s examples/servers/everything-server, run on the hash-locked mcp release:

record sdk-python-2025-11-25 2025-11-25 38302 -- "$PYTHON" upstream/py_everything_server.py --port 38302
record sdk-python-2026-07-28 2026-07-28 38302 -- "$PYTHON" upstream/py_everything_server.py --port 38302

Judging, and what comes out

./matrix.sh ../target/debug

prints one line per session — the verdict and the totals — and leaves each trace and its JSON report in interop/out-matrix/. Read any one in full the usual way:

../target/debug/mcp-trace-validator validate out-matrix/sdk-python-2026-07-28.jsonl

A finding is a result, not a failure of the script: it exits non-zero only when a session could not be recorded at all. The same script records the Go and Rust SDKs’ servers, and the committed results of all of them are the cross-SDK matrix. To check a fresh run against them:

cargo xtask sdk-matrix --recaptured interop/out-matrix

Recording your own server

Replace the server command in a record line with yours, and give it a free port. If your server speaks stdio rather than HTTP, record it the way Getting started shows instead — mcp-trace-capture -o session.jsonl stdio -- <server> — and point a client at that command.

Testing a server or client

A recording judges only what its session did; most clauses read not observed because nothing exercised them. The official conformance suite exercises an implementation on purpose. mcp-conformance test runs the two together: the pinned suite drives your server or client, mcp-trace-capture records the traffic as it goes, and every recorded session is judged clause by clause. You get the suite’s checks, the clause report, and whether the two agree — from one command.

mcp-conformance is on main, not yet released (ADR-0021). Build it from a checkout with cargo install --path crates/mcp-conformance-cli.

Before you start

test needs Node.js 18 or newer, with npx, on PATH: the suite is a Node package. It checks, and tells you what to install when Node is missing; it installs nothing itself. npx fetches @modelcontextprotocol/conformance at exactly the version this build pins, and test refuses to go on if the suite reports any other version.

A server

Over streamable HTTP, give the endpoint URL. The suite reaches it through a recording proxy on 127.0.0.1:

mcp-conformance test --url http://localhost:3000/mcp

Over stdio, give the command. It is split at whitespace and run without a shell:

mcp-conformance test --command "python my_server.py"

The suite drives servers only over streamable HTTP, so test puts a loopback bridge in front of a stdio server and starts one server process per suite session, each under the recorder’s stdio wrapper. The trace is the stdio wire your server spoke. Three of the suite’s scenarios exercise the HTTP transport itself — dns-rebinding-protection, server-sse-polling and server-sse-multiple-streams — and would judge the bridge rather than your server, so they are not run; the report lists them as not run, with why.

To run some scenarios rather than the suite’s default set, name each:

mcp-conformance test --url http://localhost:3000/mcp --scenario tools-list --scenario ping

A client

Give the command that starts your client. The suite runs it through a shell, once per scenario, with the URL of the suite’s test server appended:

mcp-conformance test --client-command "node my_client.js"

By default that is the suite’s four protocol scenarios (initialize, tools_call, elicitation-sep1034-client-defaults, sse-retry). The auth/* scenarios need the suite’s authorization server as well as its MCP one, which the recording proxy does not stand in front of; name them with --scenario to run them anyway.

Reading the result

The human report has three parts:

• The official suite — each scenario with its checks’ statuses, and the message of any that failed or warned. The suite’s verdict is its own: a FAILURE or a WARNING fails it.
• The clause report — one validator report per recorded session, as mcp-trace-validator validate prints it (Reading a report). A session that holds nothing to judge (a request the server refused before any message was exchanged, say) is listed as not judged, with the reason.
• Agreement — every failing clause is a divergence from the suite’s verdict unless a divergence baseline explains it, and every baseline entry that explained nothing is stale. Agreement holds when there is neither.

--divergences names a baseline in the format of this repository’s conformance/agreement-divergences.json: each entry a requirement ID, a triage class (our-bug, suite-bug or spec-ambiguity) and an upstream link. --expected-failures passes the suite its own baseline of scenarios expected to fail.

mcp-conformance test --url http://localhost:3000/mcp --divergences divergences.json --expected-failures expected-failures.yaml

For CI, --format json carries all three parts; junit and sarif are the validator’s own renderings of the clause report (Using it in CI), and the suite’s checks and the agreement go to stderr whatever the format. -o writes the report to a file:

mcp-conformance test --command "python my_server.py" --format sarif -o conformance.sarif

The exit code is 0 when the suite passed and the two agree, 1 for findings — a suite check that failed or warned, or a disagreement — and 2 when the run could not be made or judged. The suite’s results and every trace are kept in the work directory, printed at the end (--work-dir chooses it): judge a trace again, or attach it to a bug report.

This repository’s own subjects

CI runs test against this repository’s everything server, over both transports, and its reference host, and holds each report to cargo xtask conformance’s results for the same subject: the same scenarios with the same check statuses, every failing clause the gate’s recordings show, and nothing beyond them that conformance/wire-findings.json does not list with its triage class and why only the wire shows it. From a checkout, after cargo build -p mcp-everything-server -p mcp-conformance-cli and cargo build -p mcp-reference-host --features cli:

mcp-conformance test --command "target/debug/mcp-everything-server --transport stdio"
mcp-conformance test --client-command target/debug/mcp-reference-host --divergences conformance/client-agreement-divergences.json

Watching a session live

mcp-trace-validator gives its verdict after the session; mcp-conformance test gives one after the suite has run. While you are building a server or a client you want to hear about a violation when it happens. mcp-conformance watch records a session exactly as mcp-trace-capture does and judges it as it runs: every new finding is printed as the exchange that shows it completes, a one-line tally keeps count, and the validator’s full report follows when the session ends.

mcp-conformance is on main, not yet released (ADR-0021). Build it from a checkout with cargo install --path crates/mcp-conformance-cli.

Starting it

watch takes the recorder’s two modes, and its flags by the same names — -o for the trace file (with {session} for a file per session), --force, --max-message-bytes. For a stdio server, configure your client to launch the wrapper in place of the server, exactly as capturing from your client describes for mcp-trace-capture:

mcp-conformance watch stdio -- python my_server.py

For a streamable-HTTP server, point your client at the proxy instead of the server:

mcp-conformance watch http --upstream http://localhost:3000/mcp
# the client connects to http://127.0.0.1:8080/   (the proxy's root is --upstream itself)

The proxy’s root path is the --upstream URL itself, and any other path is appended to it. With --upstream http://localhost:3000 (no path), the client connects to http://127.0.0.1:8080/mcp instead; giving the path in both places reaches /mcp/mcp, which the server answers with a 404.

The proxy listens on 127.0.0.1:8080 unless you say otherwise:

mcp-conformance watch -o traces/{session}.jsonl http --upstream http://localhost:3000/mcp --listen 127.0.0.1:9000

The trace file is the one mcp-trace-capture would have written, so everything else in this book applies to it unchanged. Stop an HTTP watch with Ctrl-C; a stdio one ends when your client stops the server.

What it prints

Everything goes to stderr: in stdio mode stdout carries the session itself. A finding looks like this — the outcome, the clause ID and its level, the event it points at, the detail, then the clause and where it is published:

mcp-conformance watch: WARN TOOL-006 (SHOULD) seq 5: tool name "weather lookup,v2!" contains characters outside A-Z, a-z, 0-9, underscore, hyphen, and dot: " ,!"
    spec: "The following SHOULD be the only allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.)"
    see:  https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names
mcp-conformance watch: WARN TOOL-007 (SHOULD NOT) seq 5: tool name "weather lookup,v2!" contains characters outside A-Z, a-z, 0-9, underscore, hyphen, and dot: " ,!"
    spec: "Tool names SHOULD NOT contain spaces, commas, or other special characters."
    see:  https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names
mcp-conformance watch: 3 exchange(s); findings so far: 0 fail, 2 warn

That is the corpus’s tool-006-name-charset session replayed through watch stdio (the test that replays it checks this page’s lines against what watch printed).

On a terminal the tally is one line rewritten in place; in a log it follows each batch of new findings. When the session ends, watch prints mcp-trace-validator’s report of the whole trace — the same report validate prints — and the tally once more.

Text quoted from the session (a method name, a tool name, an error message) is printed with control characters escaped as \u{…}, as the validator’s own report prints it: a recording is untrusted input, and an escape sequence in a tool name must not reach your terminal raw.

When a finding appears

After every completed exchange — a response paired with its request, a notification, or anything that is not a request still waiting for its answer, such as a line that is not JSON-RPC at all — the trace so far is judged at the revision it declares. A finding is printed the first time a pass shows it, and never again; the end-of-session report lists it with the rest. A violating response or notification is reported by the pass its own arrival triggers; a violating request, by the pass of the exchange its response completes (a request never answered is judged at the end).

Two things are deliberately not findings:

• An outcome that moves. As the session reaches a clause it goes from not observed to pass. That is progress, not news, and watch says nothing.
• A verdict about the future. Right after the initialize response, the trace so far has no initialized notification, so LIFE-003 fails — until the client sends it a moment later. Checks that conclude from what the rest of the trace does not hold wait for the end of the session. The repository holds this to the corpus: every committed trace, replayed line by line, prints nothing live that the whole trace does not show, and prints everything else by the pass at or after the line that makes it visible. Should a session the corpus does not cover still retract a finding, the end of the run names it as withdrawn.

It never slows the session

watch is read-only, like the recorder it is built on: bytes are forwarded unchanged, in order, and nothing waits for judging. The recorder hands each line it writes to a channel and goes on; judging happens on a thread of its own. If judging falls behind, the findings lag and the session does not — a test holds this, with a judge that sleeps 50 ms a pass behind a server sending 200 notifications 2 ms apart.

Each pass re-judges the whole trace so far. Measured in release builds (4 vCPU Intel Xeon @ 2.10 GHz, cargo bench -p mcp-conformance-cli --bench live), a pass takes about 0.17 ms on the largest committed capture (41 events) and about 80 ms on a synthetic 10,001-message session. So watch paces itself: after a pass that took d, the next waits 3d, and whatever arrived meanwhile is judged in one pass. A short session gets a pass per exchange; a 10,000-message one gets one about every 320 ms, its findings lagging by up to that much, and judging never takes more than a quarter of a core.

Spans for your tracing stack

--otlp sends one span per exchange to an OpenTelemetry collector, over OTLP/HTTP with JSON encoding. Give the collector’s base URL (/v1/traces is appended) or the full traces URL:

mcp-conformance watch --otlp http://localhost:4318 stdio -- python my_server.py

The spans follow the OpenTelemetry semantic conventions for MCP (read at that commit; their status is Development, so they may still change):

• Name {mcp.method.name} {target}, the target being the tool of a tools/call or the prompt of a prompts/get (tools/call get_weather), else the method alone.
• Kind CLIENT, for every exchange, whoever started it. The conventions define the client span as the initiator’s view, from sending the request to receiving the answer, and the server span as the receiver’s processing. A tap on the wire sees exactly the first and never the second, so it claims no timing it does not have.
• Attributes mcp.method.name; jsonrpc.request.id (not for a notification); mcp.session.id (HTTP); mcp.protocol.version; jsonrpc.protocol.version when not 2.0; network.transport (pipe for stdio, tcp for HTTP) with network.protocol.name and network.protocol.version for HTTP; server.address and server.port (the upstream) for a client’s request over HTTP; gen_ai.tool.name with gen_ai.operation.name = execute_tool, gen_ai.prompt.name, mcp.resource.uri (the URI up to its path: userinfo, query and fragment are dropped, since a presigned URI keeps its credential there).
• Errors set error.type and rpc.response.status_code to the JSON-RPC code and the span status to ERROR, described by the code and a fixed name for it (JSON-RPC error -32602 (invalid params)), never by the server’s own message, which can echo what it was sent; a tool result with isError: true sets error.type = tool_error; a request the session ended before answering, unanswered.
• Findings are span events named mcp_conformance.finding, with mcp_conformance.requirement.id, .requirement.level, .outcome, .revision, .spec.url, .check, .detail (cut at 512 characters, marked) and .trace.seq — this tool’s own namespace, since the conventions have none for conformance. A finding goes on the span of the exchange that holds its seq, or, when that span has already been sent, on the span of the exchange that surfaced it.

Each session is one trace id, each exchange a span id, both random per run from the operating system’s generator. None of the conventions’ opt-in attributes — tool arguments, tool results, prompt variables — is ever set: watch exports no payload.

Spans travel in batches, off the session’s path, through a bounded queue. A collector that is down, slow or refusing costs the spans sent to it and nothing else; the summary at the end says how many were exported and how many were not, and why. CI sends the spans of a corpus replay through a pinned OpenTelemetry Collector and reads back what it wrote.

What it listens on and what it sends

watch listens only where mcp-trace-capture would: nowhere in stdio mode, and on --listen in http mode — loopback by default, with the recorder’s warning for any other address, since anyone who can reach the proxy can send requests through it. It sends nothing anywhere unless --otlp names a collector, and then only the span fields above. An http:// collector that is not this machine gets a warning, because those fields — method and tool names, resource URIs up to their path, session ids, error codes, findings — would cross the network unencrypted. The trace file holds message bodies in full, as every recording does: read it before you share it.

Reading a report

A report answers one question per clause of the revision: did this session break it? Getting started lists the seven outcomes; this chapter is about acting on them.

The outcomes, and what to do about each

Over several traces, a trace that could not be judged at all — unreadable, malformed, of a revision this build does not know, or judging nothing — is listed with its error, and the run’s verdict is incomplete.

Triaging a finding

  FAIL  BASE-003 (MUST NOT)
        [client] seq 3: request "tools/list" reuses id 1, already used by the same party at seq 0
        spec: "The request ID MUST NOT have been previously used by the requestor within the same session."
        see:  https://modelcontextprotocol.io/specification/2025-11-25/basic#requests

1. Find the event. seq 3 is the event whose seq field is 3 — in a trace written by mcp-trace-capture, the line after seq 2. Many findings name a second event (at seq 0): the earlier one the offending event conflicts with. --format sarif puts each finding on its trace line in a SARIF viewer.
2. Find the party. The tag before the event ([client]) is the party the finding is held against: the party the clause binds, or, for a clause binding both, the sender of the message at seq (JSON carries it as the finding’s party, and each row’s actor is the party its clause binds). A finding the trace cannot pin on either side carries no tag. mcp-trace-validator requirements BASE-003 --revision 2025-11-25 prints the clause in full. When the other side of the session is not yours to fix — the official suite’s client, say — --party server counts only the server’s findings toward the verdict and exit status, and the verdict line says (server findings only).
3. Read the clause where it is published. The spec: line is the registry’s verbatim quote, and see: links the sentence in the revision the session was judged against. Read the surrounding section before changing code: the clause may carry conditions the quote alone does not.
4. Check the revision line at the top of the report (revision 2025-11-25 (declared by the trace)). A session judged against a revision it did not mean to speak fails clauses it never agreed to; --revision names the right one.

A few findings come from the recording rather than the implementation: two sessions in one trace (the validator notes this, and {session} in the capture’s -o separates them), or a capture started mid-session. Troubleshooting covers both.

The wire schema

Below the clause rows, every report judges each message against the revision’s own JSON Schema — the specification’s schema.json, which it calls “the source of truth for all protocol messages and structures”:

  FAIL  wire schema — fail (1 of 5 messages invalid)
        [server] seq 4: the server's message is not a valid ListResourcesResult under the 2025-11-25 schema: /result/resources/0: "uri" is a required property
        spec: "This is the source of truth for all protocol messages and structures."
        see:  https://modelcontextprotocol.io/specification/2025-11-25/basic#schema
        schema: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/<commit>/schema/2025-11-25/schema.json

The finding names the definition the message was held to and the path of the member at fault; a member that matched none of several alternatives (a content block, an input request) names the closest alternative’s defect. The schema catches what no sentence of the prose states on its own — a missing required member, a wrong type, a value outside an enumeration, image or audio data or a resource blob that is not base64 (the schema’s byte format; its uri and uri-template formats stay annotations, because asserting RFC 3986 would fail URIs the prose permits) — so it is reported beside the clauses rather than as one, has no requirement ID, and is not counted in the totals; a failure still fails the verdict. Where the published schema is stricter than schema.ts, the validator corrects it and says where (ADR-0020).

Extensions

An official extension — tasks (io.modelcontextprotocol/tasks) and skills (io.modelcontextprotocol/skills) at 2026-07-28 — is optional by definition, so conforming to the protocol cannot depend on one. A session that uses one is judged against the extension’s own clauses in a block of its own, and the block never moves the report’s totals, verdict or exit status. This session conforms to the protocol and breaks the tasks extension:

MCP trace validation — revision 2026-07-28 (declared by the trace)
extension io.modelcontextprotocol/tasks — not scored: its outcomes never change the verdict
  FAIL  TASK-001 (MUST NOT)
        [server] seq 3: a `resultType: "task"` result answered a `tools/call` request whose `_meta` client capabilities do not declare `io.modelcontextprotocol/tasks`
        spec: "A server MUST NOT return `CreateTaskResult` to a client that did not include the extension capability on its request, regardless of prior declarations."
        see:  https://modelcontextprotocol.github.io/ext-tasks/specification/2026-07-28/tasks#capability-negotiation
  extension totals: 2 pass, 1 fail, 0 warn, 24 excluded, 0 unsupported, 0 not applicable, 22 not observed — extension verdict: fail
totals: 35 pass, 0 fail, 0 warn, 320 excluded, 0 unsupported, 0 not applicable, 146 not observed
wire schema: pass (4 messages valid)
verdict: pass

The command exits 0. The official suite draws the same line: its requirement sets run an extension’s scenarios under not_scored: extension, reported and never counted. An extension appears only when the session exercised it — one of its clauses passed, failed or warned — so a session that never touched tasks or skills shows no block at all. JUnit gives the extension a suite of its own, named … (2026-07-28, extension io.modelcontextprotocol/tasks, not scored), whose findings are in passing cases’ <system-out> and never a <failure>; SARIF reports them at level note; the HTML page gives them a section after the verdict. --strict does not change any of it. Each clause links to the extension’s own specification, which its repository publishes; the extensions reference lists every one, and ADR-0023 records why.

Why so many clauses are not observed

A pass verdict says that nothing this session did broke a clause. A short session does little: one initialize and a tools/list says nothing about pagination, errors, resources, cancellation, or the HTTP transport. Those clauses report not observed, and the totals count them so that a thin session cannot read as a thorough one.

To put more of the specification to the test, record sessions that do more:

• exercise every feature the implementation offers — tools, prompts, resources, completion, subscriptions;
• include error paths: an unknown tool, a missing resource, invalid parameters;
• page through a long list, cancel a request, ask for progress and logs;
• record over both transports, since Streamable HTTP has its own clauses;
• for a server, let mcp-reference-host drive it with --sweep (and --cancel, --subscribe, --log-level at 2026-07-28) — see Capturing from your client.

validate traces/*.jsonl judges each recording separately: coverage is per trace, not pooled across them.

Disputing a verdict

If a finding disagrees with your reading of the specification, open an issue with the requirement ID, the specification text, and — if you can share it — the trace (traces record message content in full; read one before attaching it). Disputes are triaged into one of three outcomes: a bug here (fixed), a divergence from the official conformance suite (filed upstream), or an ambiguity in the specification (filed upstream). The contributing guide has the process.

The report as a page

--format html writes the report as one HTML file — the one to attach to a bug report against an SDK, or to open while debugging:

mcp-trace-validator validate session.jsonl --format html > report.html

From the top: the verdict, with every outcome’s count (one card per revision when the trace is judged at several) and the wire-schema outcome; then Clauses to act on, each failing, warning or unsupported clause with its level, the clause verbatim, a link to its published page, and every finding with the seq it points at; then the Message timeline, every event in capture order with its direction, kind, method and id, the request a response answers (both linked), HTTP requests and responses with their recorded headers, and each finding shown at its event. A finding links to its event and the event back to the finding, and the switch above the timeline hides the events no finding names. Accounting closes the page: the passed, not-observed, not-applicable and excluded clauses, collapsed, each excluded one with the registry’s reason and each not-applicable one with the capability the session never declared — the same arithmetic as the totals, clause by clause.

Anchors are names you can type: report.html#BASE-003 opens a clause, #e12 an event (#2026-07-28-BASE-045 when two revisions share a page, #t1-e12 in a page over several traces).

The page is safe to open from anyone. It loads nothing — no script, font or image — and the only style it applies is its own, which its Content Security Policy admits by digest; everything from the trace (method names, ids, headers, payloads) is shown as text, so a recording holding <script> shows the word. It is still a trace: payloads are shown in full up to 16 KiB per message, so read it before you share it, as you would the trace.

The page is for people. Its layout changes between releases; for anything a script reads, use --format json.

The report as data

--format json is the whole report, described by its JSON Schema. A single trace gives one object: revision, revision_source (how the revision was chosen), totals per outcome, verdict, and requirements, one row per clause with its id, level and outcome. A failing or warning row also carries source (the quote, its section and URL) and findings, each with the check that found it, the seq of the event, and a detail. An extension the session exercised is an entry of extensions, with its own extension, verdict, totals and requirements — read by nothing that decides the report’s verdict. Several traces, or several --revisions, give the multi-trace and multi-revision shapes the schema also describes.

To hold an extension you implement to its clauses yourself:

mcp-trace-validator validate --format json session.jsonl \
  | jq -e '[.extensions[]? | select(.extension == "io.modelcontextprotocol/tasks")
            | .verdict] | all(. == "pass" or . == "pass-with-warnings")'

The findings alone, for a script:

mcp-trace-validator validate --format json session.jsonl \
  | jq '.requirements[] | select(.outcome == "fail" or .outcome == "warn")
        | {id, level, findings}'

The workbench

mcp-conformance serve is a local web page over a library of recordings: search them, read one as a timeline with each finding at its event, compare two, follow one that is still being recorded, see what the library as a whole has exercised, and administer it — import, tag, expire, delete, export, and make redacted copies to share. It is ADR-0021’s decision 4; it runs on your machine, reads and writes one directory, and sends nothing anywhere.

mcp-conformance serve --library ./recordings

It prints the link to open:

mcp-conformance serve: library ./recordings (12 recordings)
mcp-conformance serve: open http://127.0.0.1:41245/?token=ae0c…4f71
mcp-conformance serve: the link works once; Ctrl-C stops the workbench
mcp-conformance serve: browsers scope the cookie to 127.0.0.1 as a whole, not to port 41245: any other server there that this browser visits is sent it

Open the link (--open does it for you). It works once: the first visit trades the token for a cookie that only that browser holds, and the address bar is redirected to a URL without it. To open the workbench in another browser, restart it.

The library

A library is a directory of traces, <id>.jsonl, each with an optional sidecar, <id>.meta.json:

{
  "format": 1,
  "tags": ["nightly", "sdk-go"],
  "source": { "kind": "imported", "importer": "mcpsnoop", "imported_from": "session.jsonl",
              "not_recorded": ["… what the source format does not record …"] },
  "added_at": "2026-10-13T09:12:00Z",
  "recorded_at": "2026-10-12T17:40:03Z",
  "verdict_cache": { "sha256": "…", "tool_version": "0.6.0", "reports": [ … ] }
}

The verdict is mcp-trace-validator’s, by the same rules validate applies; the cache is used only when it was computed from the same bytes (SHA-256) by the same version, so editing a trace or upgrading recomputes it. Point a recorder at the directory — mcp-trace-capture -o 'recordings/{session}.jsonl' … — and the recording appears on the next page load. An id is the file stem, limited to ASCII letters, digits, ., _ and -; any other .jsonl file is listed as not opened, and is never read.

Searching

The search box takes terms separated by spaces; every term must match.

A value ending in * matches by prefix (method:resources/*, req:TRAN-*); a leading - excludes (-tag:ci); quotes hold spaces. Results are ranked — a field term counts for more than free text, and more occurrences for more — and each links to the events it matched.

A session

The session view is the HTML report’s timeline, drawn with the report’s own stylesheet: every event in order, requests paired with their answers (with the latency when the trace records timestamps), notifications, HTTP exchanges and their headers, transport lifecycle. Findings are listed beside it; Go to event opens the event’s inspector (its full payload, up to 16 KiB shown), and each finding marked on an event links back. Only events with findings filters the timeline; HTML report downloads the same page --format html writes, to attach to a bug report.

Follow live polls the trace file once a second and adds what was appended, re-judging as it grows: point it at a trace a recorder is still writing. A last line not yet finished is left for the next poll.

Where the recording came from is stated above the verdict. For an import, that includes what the source does not record — the clauses that would need it read not observed, and nothing is filled in. For a redacted copy, it names the original and each rule applied.

Comparing two sessions

Select two recordings and Compare (or Compare with… on a session). The diff lists every clause whose outcome or number of findings differs at a revision both were judged at, then the messages aligned by direction, method (a response takes its request’s) and id, each pair the same or changed, each unpaired message only in A or only in B; a changed pair opens to both payloads. Recordings of the same client against two servers — two SDK versions, say — align message for message.

Dashboards

Verdicts by the day recorded, clause coverage per revision (how many of the registry’s clauses some recording judged, beside those the registry excludes from judging), and findings by area and by server. Every number is reproducible from the command line, and the page names the member of the output each chart draws:

mcp-conformance library --library ./recordings stats --format json

prints exactly — byte for byte, which a test holds — what the dashboards read.

Administration

Each action is a button in the page and a library subcommand:

Redaction makes a new recording and leaves the original alone. It replaces with "[redacted]" the values of headers named (by default Authorization, Cookie, Set-Cookie, Proxy-Authorization and Mcp-Session-Id), of JSON pointers into every message (/params/arguments/apiKey; * matches every member, as in /result/content/*/text), of every _meta member, and every occurrence of a literal string anywhere. A line that is not JSON stops the redaction rather than being copied. Member order within a line is not kept. Read the copy before sharing it: redaction removes what you name, and a recording holds whatever the session sent.

Retention deletes recordings made more than N days ago; one with no date (no recorded_at, no timestamps, no added_at, no file time) is never selected.

Importers

• mcpsnoop (its JSON Lines capture, read from captures 0.26.1 wrote): every frame becomes a message, a batch one array again; over HTTP, each exchange’s first frame is preceded by the request (a POST, with the headers mcpsnoop kept) or the response status. It does not record Host or Mcp-Session-Id, response headers but Content-Type, transport lifecycle, or the method and time of a request without a body (a GET stream, a DELETE), which is placed just before the server’s first frame on it with its method unstated.
• MCP Inspector (the web client’s protocol export, inspector-protocol-….json, read from @modelcontextprotocol/inspector 2.10.1): every message becomes an event, an answer folded into its request’s entry placed at the request’s time plus the recorded duration. It does not record the transport (say it: --transport), anything of HTTP, lifecycle, or messages the Inspector’s log had dropped (it keeps the latest 1000 by default).

Security

The library can hold credentials, and a local web server is reachable by every page your browser opens. So the workbench binds 127.0.0.1 (another address needs --dangerously-listen-non-loopback, and it warns); answers only requests whose Host is its own address — a DNS-rebound name is refused — and whose Origin, when present, is its own; needs the session cookie on every request; answers /api/… only to a request whose Sec-Fetch-Site is absent, same-origin or none (a page on another port of the same host is same-site and is refused); accepts a change only as a JSON body carrying its Origin; sends a Content Security Policy that allows no inline script or style and no connection elsewhere; and puts every string from a recording on the page as text, with control and bidirectional characters shown as \u{…}. The security model lists the threats and the tests.

The page and its API are for people, not a stable interface (STABILITY.md); library stats --format json is the way to read the numbers from a script.

Using it in CI

The shape is the same everywhere: the tests you already run drive your server or client through mcp-trace-capture, and a later step judges the traces they leave. The validator’s exit status is the verdict, so a failing clause fails the build.

Recording from a test suite

Wherever your tests start the server, put the capture in front of it. With the official SDKs’ stdio clients, the server’s command moves behind --:

StdioServerParameters(
    command="mcp-trace-capture",
    args=["-o", "traces/{session}.jsonl", "stdio", "--", "python", "my_server.py"],
)

For an HTTP server, start the proxy before the tests and stop it after:

mcp-trace-capture -o 'traces/http-{session}.jsonl' http --upstream http://127.0.0.1:3000 \
  2> proxy.log &
proxy=$!
# Wait until the proxy is listening; stop if it exited instead (proxy.log says why).
until grep -q 'listening on' proxy.log; do
  kill -0 "$proxy" 2> /dev/null || { cat proxy.log; exit 1; }
  sleep 0.2
done
npm test          # with the client pointed at http://127.0.0.1:8080/mcp
kill -INT "$proxy"
wait "$proxy"

The proxy prints its listening on line only once its port is bound, so waiting for it — rather than probing the port with a request, which the proxy would forward and record — keeps the first test from racing the proxy’s start.

{session} gives each test session its own numbered trace: each launch of the stdio wrapper, and each client session through the proxy (the traces/ directory must exist). The repository’s interop/ directory does exactly this with the official TypeScript and Python SDKs, and its run.sh is a working example of both transports; its matrix.sh records each official SDK’s own conformance server through the proxy (Recording an SDK’s server).

GitHub Actions

The repository is itself an action. After the step that records the traces:

- uses: tomtom215/mcp-conformance@<commit or tag>
  with:
    traces: traces/*.jsonl
- uses: github/codeql-action/upload-sarif@<sha>
  if: always()
  with:
    sarif_file: mcp-conformance.sarif
    category: mcp-conformance

The action builds mcp-trace-validator from the ref you name (or, with version: 0.6.0, downloads that release’s prebuilt binary and checks its checksum), prints the findings to the log and the job summary, writes mcp-conformance.sarif and mcp-conformance-junit.xml, and fails the step when a clause fails. Uploading the SARIF log needs permissions: security-events: write on the job; findings then appear in the repository’s code scanning view, each on the trace line that holds the event. The inputs — revision, strict, fail-on-findings, the output paths — are listed in action.yml.

Recording with the action

The action can also take the recording: set capture, give it the server and the client command that drives it, and it runs the session through mcp-trace-capture, then judges every session recorded (with any traces you name too). This is not yet released: it is on main, so pin a commit for it, and it needs the action’s own source build (version empty) until a release carries it.

# stdio: the client launches $MCP_SERVER_COMMAND in place of the server.
- uses: tomtom215/mcp-conformance@<commit>
  with:
    capture: stdio
    server: python my_server.py
    client: pytest tests/mcp -k e2e   # its fixture launches $MCP_SERVER_COMMAND

# Streamable HTTP: the client talks to $MCP_PROXY_URL, which reaches `upstream`.
- uses: tomtom215/mcp-conformance@<commit>
  with:
    capture: http
    server: node dist/server.js --port 3000   # optional: started, waited for, stopped
    upstream: http://127.0.0.1:3000/mcp
    client: npm run e2e -- --url "$MCP_PROXY_URL"

Every launch of MCP_SERVER_COMMAND, and every session through the proxy, is its own trace. The stdio wrapper carries the server’s command line itself rather than reading the environment, because clients commonly launch stdio servers with a reduced one; the server runs with whatever environment the client gives it. A client that exits non-zero fails the action — after the sessions it did record are judged and reported — and its status is the client-exit-code output. CI exercises capture on Linux runners (both transports, driving the repository’s everything server with its reference host); the stdio wrapper is a bash script, which a Windows client cannot launch as a command.

Container image

From the release that follows 0.6.0, each release also publishes both CLIs as ghcr.io/tomtom215/mcp-conformance:<version> (linux/amd64), built from the repository’s Dockerfile and attested like the binaries:

docker run --rm -v "$PWD:/work" ghcr.io/tomtom215/mcp-conformance:<version> \
  mcp-trace-validator validate --format junit traces/*.jsonl > mcp-conformance.xml
gh attestation verify oci://ghcr.io/tomtom215/mcp-conformance:<version> \
  --repo tomtom215/mcp-conformance

The image is distroless: no shell and no package manager, running as UID 65532, with /work as its working directory — mount the directory holding your traces there (and make it writable by that user to record into it). With no shell, mcp-trace-capture stdio can only launch a server that is in the image, so to record a stdio server in a container, build FROM this image and add yours; mcp-trace-capture http needs nothing more.

Any other CI

mcp-trace-validator validate traces/*.jsonl                       # findings in the log
mcp-trace-validator validate --format junit traces/*.jsonl > mcp-conformance.xml
mcp-trace-validator validate --format sarif traces/*.jsonl > mcp-conformance.sarif

Each invocation exits with the same status, so run the human report as the gate and the other two for the reports your CI ingests (GitLab, Jenkins and most others read JUnit). Several traces give one document: a JUnit suite per trace and revision, one SARIF run with each result in its own trace file.

Choosing what fails the build

A trace that cannot be judged — empty, malformed, or of a revision this build does not know — exits 2 or 3, never 0: a broken recording step fails the build rather than passing it. fail-on-findings: false gives that up as well: the action’s step then succeeds whatever the exit status, 2 and 3 included, so a step that relies on it should read the action’s exit-code output and fail on 2 and 3 itself. When the validator cannot start at all — a traces pattern matching nothing, or a lone trace it cannot read — the action still writes both reports, as a SARIF run marked executionSuccessful: false and a JUnit <error>, so an if: always() upload step finds a valid file.

Upgrading

Before 1.0, a minor release (0.6 → 0.7) may change what the tools decide, not only their Rust API: a check that learns to catch a defect fails a session that passed, and a check that stops failing conforming sessions passes one that failed. STABILITY.md says what counts as breaking. Every such change is in the release’s changelog entry, which since 0.5.0 opens with a table of each one and its migration (earlier entries state them in their opening paragraphs).

Before you upgrade

1. Read the release’s table. Each row names the surface (a requirement ID, a report format, a flag), the change, and what to do: Unreleased (on main), 0.6.0, 0.5.0.

2. Judge your recordings with both versions and compare by requirement ID, not by totals: rows are added and moved between checked and excluded between releases, so the totals move even when nothing about your session’s conformance did.

   mcp-trace-validator validate --format json session.jsonl \
     | jq -r '.requirements[] | select(.outcome == "fail" or .outcome == "warn") | .id' \
     | sort > findings-new.txt
   

   The same command with the old binary gives findings-old.txt; diff the two. A row in one and not the other is a verdict change the table explains. The report’s wire_schema member (on main since 0.6.0) is judged beside the rows; compare its outcome too.

3. Expect SARIF alerts to move once where the table says a fingerprint changed; an alert whose finding is unchanged keeps its fingerprint.

Pin the version you gate on

A CI gate should change its verdicts when you upgrade it, not when a release happens. Pin it:

• cargo install mcp-trace-validator --version 0.6.0 --locked, or cargo binstall [email protected] for the attested prebuilt binary;
• the GitHub Action at a tag or commit (uses: tomtom215/[email protected]), or with version: 0.6.0 to download that release’s prebuilt binaries rather than build from the action’s source;
• the container image by version or, stricter, by digest (ghcr.io/tomtom215/mcp-conformance:X.Y.Z@sha256:…), for releases after 0.6.0;
• mcp-trace-validator = "=0.6.0" for the library.

mcp-trace-validator --version names the build that judged a report; on main since 0.6.0 it also names the protocol revisions that build judges.

Library users

The Rust API follows the same release rule: a minor release may break it, the changelog’s table names every break, and cargo-semver-checks compares each release with its predecessor on crates.io before it is published. A deprecated item stays for at least one minor release, deprecated with its replacement named, before it is removed. Types that will grow — reports, findings, outcomes, options — are #[non_exhaustive], so a new field or variant is not a break: match them with a wildcard arm, and set options through their builder methods (HumanOptions::default().all(false)) rather than struct literals.

Troubleshooting

Each entry starts from what you see.

The validator

error: … judged no requirement at all — an empty or contentless trace is a capture that failed, not a session that conformed (exit 2). The trace has no messages: the client never connected, connected to the server directly instead of through the capture, or the capture was stopped before the session. Check the capture’s exit summary, which counts what it recorded.

error: … records 1 client message(s) and none from the server (exit 2). The client spoke and the server never answered: the capture recorded that it could not reach the server (transport-abort), or the client’s initialize went unanswered. The client’s side alone would pass, so the run is refused rather than reported green. Check that the server is running and reachable — for the HTTP proxy, that --upstream names it — and record again.

error: the trace declares protocol revision(s) 2025-06-18, which no available registry describes (exit 2). The session ran an older revision than this build has requirements for (2025-11-25 and 2026-07-28). Judging it against either would report that revision’s rules as violations, so it is refused. --revision 2025-11-25 judges it anyway, if the differences do not matter to you.

note: this trace records 2 sessions and is judged as one. Two clients, or one client twice, were recorded into one file — a proxy left running across test runs, or a client that reconnected. Findings that span them (a request id the second session reuses, a session id that changed) come from recording them together. Put {session} in the capture’s -o (-o traces/{session}.jsonl) to get a trace per session.

note: the trace declares no protocol revision; judging it against 2026-07-28. The recording holds no initialize, no _meta protocol version and no MCP-Protocol-Version header — often a trace that starts mid-session. Pass --revision to say which rules apply.

error: malformed trace: … (exit 3). The file is not a trace as written by a recorder. Given several traces, the error starts with the trace’s name (error: traces/b.jsonl: malformed trace: …), the report lists it as not judged, and the overall verdict reads incomplete:

The capture tool

… exists; appending would break the trace's sequence numbers (exit 2). The output file is there from an earlier run. Put {session} in the file name for a new numbered trace each run — the usual choice in a client’s configuration, which relaunches servers — or use --force to overwrite.

The server works directly but not through the HTTP proxy, with 403. The server checks the Host header against the names it accepts. For a server on this machine (localhost, 127.0.0.0/8, ::1) the proxy passes the client’s Host through, so the server judges what the client sent, localhost:8080 included: a server that accepts only its own host:port refuses it. --no-preserve-host sends the server its own name instead, which makes its Host check pass for every request the proxy forwards, a browser’s under a rebound name included, so use it for the recording and not as a default. For a server on another machine the proxy sends the upstream’s own name, as a virtually hosted server needs, and --preserve-host passes the client’s instead. mcp-trace-capture’s README explains the trade-off, including what the default rewrite does to a server’s DNS-rebinding check.

TRAN-004 (or TRAN-117) fails on a line like "Server starting...". The server writes something other than protocol messages to stdout — log lines, a banner. The capture records each such line as it was written, and the validator judges it: it is a stdio transport violation, and the same line fails BASE-008 at 2025-11-25 (BASE-042 at 2026-07-28): every message must be JSON-RPC. Send logs to stderr.

A client configuration cannot find mcp-trace-capture. Desktop applications often start without your shell’s PATH. Use the absolute path to the binary as the command, for example the output of which mcp-trace-capture.

Still stuck

Open an issue with the command, the full output, and — if you can share it — the trace. Traces record message content in full; read one before attaching it.

Architecture

This chapter orients you in the design. The authoritative treatment — ten decisions, each with its cost — is the standalone design note, written for an upstream audience:

📄 Design note: trace-validation architecture and trade-offs

The internal workspace layout and dependency rules live in 02-architecture.md.

The foundational split: capture, then judge

The validator judges a recorded trace, not a live session. Its engine is a pure function with no network, clock, or I/O. Whoever owns the socket — the server’s session tap, the host’s capture wrapper, or mcp-trace-capture for any other implementation — produces the trace, assigning the total-order seq at capture. The judge only judges.

This buys determinism, replayability, SDK-agnostic input, and auditable verdicts. It costs one hard thing: capture fidelity becomes a first-class engineering problem — interleaving, partial writes, and SSE framing all have to be recorded faithfully by the component that holds the bytes.

The decisions that follow, in brief

• The judge never links the SDK it judges. mcp-trace-validator does not depend on rmcp. A validator built on the SDK under test would inherit that SDK’s interpretation of the spec as ground truth — exactly the thing being examined. The cost is re-expressing the protocol as our own data.
• The spec as data. Every normative clause becomes a registry record with its RFC 2119 level, actor, a verbatim source quote, an optional capability gate, and either one or more mechanical checks or a written reason it cannot be judged from a trace. There is no “not yet looked at” state. A scheduled job re-verifies every quote against the live spec text so the registry cannot silently drift.
• Determinism by canonicalization. All JSON is canonicalized (RFC 8785) before any comparison, so a report is byte-identical across platforms and runs. Correctness here is a fixpoint property, tested as one — a real bug hid until a fuzzer first generated -0.0.
• A pass has to be earned. A requirement gated on a capability that was never negotiated is reported as not-applicable, and one whose subject matter the session never carried is reported not-observed — never as a vacuous pass. Every check counts the subjects it considered, so the report can tell “complied with” from “never came up”. Inflating a pass rate with checks that had nothing to look at is how a conformance tool loses credibility.
• Calibration against the authority. The agreement check (see the Introduction) diffs our verdicts against the official runner’s on every CI run; an unexplained divergence fails the build, and a stale recorded divergence fails it too.
• Falsifiability. Every check is killed by at least one committed injected-violation trace; a check with no killer trace is unfalsifiable. The corpus is both the regression suite and the evidence each check does what it claims.
• Verdicts are a contract. A change that makes a previously-passing trace fail is a breaking change even when no function signature moved; it is named in the changelog and the version is bumped accordingly. API-signature compatibility is additionally checked mechanically against the published crates.io baseline.

The trace format

A trace is JSON Lines: one event per line. Each event carries a capture-assigned seq (the only ordering authority — never inferred later), a direction (client-to-server / server-to-client), a transport, and a kind:

• message events hold the JSON-RPC payload (as parsed JSON: every value, not its whitespace, member order, or the spelling of its numbers);
• http events record the conformance-relevant headers, a response’s status, and a client request’s method — Streamable HTTP binds different obligations to POST, GET, and DELETE, so a clause addressed to one of them is judged only where the recording says which it was; and
• lifecycle events mark the transport’s moments: transport-open (it became usable), transport-close (it closed in an orderly way) and transport-abort (it failed or was torn down abnormally — an unreachable upstream, a response cut off, a forced stop).

The format is published as a JSON Schema (draft 2020-12), trace-event.schema.json, for recorders written in any language. It states every rule the validator’s reader applies to one record — a test runs both over every corpus record and one violation of each rule — and says where JSON Schema cannot follow: the document-level rules (one record per line, seq strictly increasing), and integers written as 1.0, which the reader refuses. Unknown members are ignored, so producers may add their own.

The redaction rules that keep credential-bearing headers out of a trace by construction are in 05-security-model.md.

One worked example

The example below is embedded verbatim from the README, where a test (readme_examples.rs) pins it to the validator’s real output — so what you read here cannot drift from what the tool actually produces. It is a session that reuses a request ID, and the verdict that catches it:

{"seq":0,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-host","version":"1.0.0"}}}}
{"seq":1,"direction":"server-to-client","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"my-server","version":"1.0.0"}}}}
{"seq":2,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","method":"notifications/initialized"}}
{"seq":3,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"method":"tools/list"}}

and the validator answers with the violated clause, addressed to the offending event:

  FAIL  BASE-003 (MUST NOT)
        [client] seq 3: request "tools/list" reuses id 1, already used by the same party at seq 0
        spec: "The request ID MUST NOT have been previously used by the requestor within the same session."
        see:  https://modelcontextprotocol.io/specification/2025-11-25/basic#requests
totals: 17 pass, 1 fail, 0 warn, 246 excluded, 0 unsupported, 6 not applicable, 78 not observed
wire schema: pass (4 messages valid)
verdict: fail

The totals line distinguishes the verdict’s components, and two of them are not passes. The not-applicable rows are capability-gated requirements this session never negotiated (the resources and prompts clauses); the not-observed rows are clauses whose subject matter never appeared at all — nothing was paginated, no binary content was sent, no error was returned. A four-line session earns 17 passes, not a hundred. See Architecture for why that distinction is load-bearing.

Two revisions at once

MCP is a dated specification. 2026-07-28 is the current revision, and 2025-11-25 stays in wide use while implementations migrate. 2026-07-28 removes the initialize handshake outright (SEP-2575), makes every request carry its own _meta envelope, and adds caching hints, multi-round-trip requests, subscriptions, and a discovery probe. That is not a version bump anyone should take on faith.

So this toolkit judges both, and can judge one trace against both in a single pass. A migration stops being an inventory of changes somebody read in a changelog and becomes a measurement.

What “both” means here

The two registries are extracted per revision rather than sharing entries: each clause is quoted from its own revision’s published text, and a clause restated with different words gets its own ID. 2025-11-25’s BASE-003 forbids reusing a request ID within a session; 2026-07-28’s BASE-045 forbids reusing one that is still in flight, so reuse after a response is now legal. Those are two clauses, not one clause with a footnote — and pointing the new one at the old one’s check would have reported conforming traces as violations.

The cost of that method is that no clause is in force at both revisions, so a side-by-side report never shows one clause passing at one revision and failing at the other. What it shows instead is presence, which is what a migration actually consists of.

A trace judged against both

This is a conforming 2025-11-25 handshake — the client offers a version, the server answers, the client confirms:

{"seq":0,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"corpus-client","version":"0.1.0"}}}}
{"seq":1,"direction":"server-to-client","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{},"serverInfo":{"name":"corpus-server","version":"0.1.0"}}}}
{"seq":2,"direction":"client-to-server","transport":"stdio","kind":"message","payload":{"jsonrpc":"2.0","method":"notifications/initialized"}}

Judged against both revisions at once:

$ mcp-trace-validator validate --revision 2025-11-25 --revision 2026-07-28 --all handshake.jsonl

(--all lists every clause; without it the report lists only the failing, warning and unsupported ones.) Four rows out of the report say the whole thing:

  LIFE-001   (MUST)  2025-11-25=pass  2026-07-28=absent  *differs
  DISC-001   (MUST)  2025-11-25=absent  2026-07-28=not-observed  *differs
  BASE-030   (MUST)  2025-11-25=absent  2026-07-28=fail  *differs
  BASE-045   (MUST NOT)  2025-11-25=absent  2026-07-28=pass  *differs

• LIFE-001 — “the client MUST initiate the lifecycle” — is a clause the newer revision removes. It reads pass then absent.
• DISC-001 — the server/discover probe that replaces the handshake — is a clause the newer revision adds, and this session carried nothing it binds to, so it reads not-observed rather than counting as a pass.
• BASE-030 — every request must carry an io.modelcontextprotocol/clientCapabilities _meta member — is a clause the newer revision adds that this session breaks. It reads fail, and it is the migration work this trace has actually discovered.
• BASE-045 — the narrowed request-ID rule — reads pass, because reusing an ID after its response is exactly what the new text permits.

And the verdict splits:

per revision:
  2025-11-25: 17 pass, 0 fail, 0 warn, 246 excluded, 0 unsupported, 14 not applicable, 71 not observed — verdict pass
  2025-11-25: wire schema pass (3 messages valid)
  2026-07-28: 15 pass, 8 fail, 0 warn, 320 excluded, 0 unsupported, 0 not applicable, 158 not observed — verdict fail
  2026-07-28: wire schema fail (1 of 3 messages invalid)
overall verdict: fail

A conforming session today, and eight concrete failures tomorrow — nine, with the 2026-07-28 schema’s own finding: the initialize result carries no resultType, which every result at that revision must. Both summary lines account for every clause in their revision — the counts add up to 348 and 501 — because a line that quietly omits an outcome is a line that overstates what was measured.

The example above is executed by a test (book_examples.rs) against the real validator on every cargo test, so this page cannot drift from what the tool actually prints.

Which revision a trace is judged against

A trace is not silent about which revision it belongs to — the handshake states it, a stateless session states it in every request’s _meta, and the HTTP transport states it in a header. So by default the validator judges a trace against the revision it declares, and says so in the report’s first line: revision 2026-07-28 (declared by the trace). Where there was a handshake, the server’s initialize result is the authority: the session ran under the revision it names — that is what negotiation means — so it is judged under that one alone, and a note on stderr says when the client had proposed another (--revision judges the proposal instead). A negotiated revision this build cannot judge is refused (exit 2) rather than approximated by the proposal, and so is a trace declaring only revisions this build cannot judge. A trace declaring nothing is judged against the newest supported revision, with a note on stderr.

Judging against the wrong rules is easy to do on purpose, with --revision. Force 2025-11-25 onto a 2026-07-28 recording and every clause the two revisions disagree about becomes a finding: the session opens with tools/list rather than initialize, so LIFE-001 fails; it reuses request ids after their responses, so BASE-003 fails. Both are correct answers to the question that was asked, and neither is a defect in the implementation. This session says 2026-07-28 twice over:

{"seq":0,"direction":"client-to-server","transport":"streamable-http","kind":"http","method":"POST","headers":{"accept":"application/json, text/event-stream","mcp-protocol-version":"2026-07-28"}}
{"seq":1,"direction":"client-to-server","transport":"streamable-http","kind":"message","payload":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}}
{"seq":2,"direction":"server-to-client","transport":"streamable-http","kind":"message","payload":{"jsonrpc":"2.0","id":1,"result":{"tools":[],"resultType":"complete"}}}

so validating it with --revision 2025-11-25 says so, above the rows and again under the verdict:

  NOTE  this session declares protocol revision 2026-07-28, not 2025-11-25.
        Every outcome here judges it against rules it was not playing by;
        re-run with `--revision 2026-07-28` to judge it against its own.

It is deliberately quiet. A session that proposed one revision and negotiated another is judged under the negotiated one by default, but the client did state the proposal, so asking for that revision with --revision draws no note; a version a server refused states nothing, because the session never ran under it; and a recording that declares no revision at all gets no note, since there is nothing to disagree with.

The four ways a clause is not a pass

A side-by-side report is where these stop being pedantry, because all four appear at once and they mean different things:

None of them is a pass, and the report never quietly promotes one. That rule is the whole reason the numbers here are smaller than a conformance tool’s numbers usually are.

What is measured at 2026-07-28 today

• The reference server serves the stateless surface with --protocol-version 2026-07-28, and the official suite’s 2026-07-28 scenarios score 42 passing / 0 failing against it.
• Eight committed captures — a conforming session over each transport, a probe session of deliberately malformed requests, the official runner’s two, and three of the official SDKs’ own conformance servers (the cross-SDK matrix) — evidence 148 of the 181 judgeable clauses between them. What no capture reaches is named, one clause at a time, in the corpus chapter.
• The project’s CI re-runs that measurement weekly and ratchets it against a committed baseline: any change in either direction fails the build, so a change in the score is recorded in the commit that caused it rather than estimated.

That ratchet has already paid for itself in the direction nobody plans for. Through suite 0.2.0-alpha.9 the runner scored the reference server identically whichever revision it served — its scenarios exercise features, not revisions, so it could not tell the two apart. This project’s registry could, and flagged the 2025-11-25 server for returning cacheable results without the cache hints 2026-07-28 requires (CACH-001). Six weeks later alpha.11 added a schema check and found the same clause, independently, from the other side. The server’s SDK then fixed it: since rmcp 3.5.1 both legs score 42 passing / 0 failing.

The next revision

The specification’s unreleased next revision (draft) is watched, never judged. No build can validate against it — --revision draft is refused like any revision the build does not ship — but the project reads it weekly and records what it has changed against 2026-07-28: pages added or dropped, keyword counts that moved, and each 2026-07-28 clause whose sentence the draft rewords or removes. So far that is one wording edit: the draft bounds a header-mirrored integer “for integers represented using IEEE754 double-precision floating point numbers” where the released transport page says “for JavaScript”. The interval is the same, so the 2026-07-28 verdict is the same. When the draft ships as a dated revision, its registry starts from that record rather than from scratch.

Full detail is in the corpus chapter, the ecosystem register and the conformance strategy.

Trace corpus

Fixtures for the golden-corpus tests (crates/mcp-trace-validator/tests/golden.rs):

• good/ — sessions that must validate with verdict pass, at the revision each declares: validate with no flags passes all of them but one, the session whose server answers initialize with 2024-11-05 (stdio-server-negotiates-2024-11-05), which validate refuses by default (exit 2) and passes with --revision 2025-11-25. The CI jobs that run the shipped Action and image over this directory name that exception.
• violations/ — single-issue sessions, each falsifying at least one check; named after the requirement whose check they exist to kill.
• draft/{good,violations}/ — the same two kinds for revision 2026-07-28, judged against that revision’s registry.
• draft/captured/ — sessions recorded off the wire from implementations this repository did not write. No verdict is asserted for them; their whole report is byte-pinned instead. See Captured versus authored below.
• captured/ — the 2025-11-25 counterpart: the official SDKs’ conformance servers recorded by interop/matrix.sh, judged against that revision’s registry, likewise pinned without an asserted verdict. Their 2026-07-28 sessions sit in draft/captured/ beside the others. See The official SDKs’ conformance servers below.
• golden/ — the byte-pinned expected report for every trace, with golden/draft/ holding the 2026-07-28 corpus’s. Regenerate only via cargo xtask bless and review the diff like code.
• golden/exclusions/ — one ledger per revision, holding the clauses that revision’s registry declines to judge from a trace, and why.

The revisions keep separate golden directories so that where a golden lives says which revision’s registry produced it. Trace names would not collide without the split: a requirement ID names one clause in one revision and is never reused (STABILITY.md), so base-045-… can only be a 2026-07-28 trace — BASE-045 is not a 2025-11-25 requirement. A sentence both revisions carry has an ID in each.

What a golden pins

A report states two kinds of fact, and they are pinned separately (ADR-0013).

golden/<stem>.json holds what the trace decided: the revision, the whole totals, and every pass / fail / warn / not-observed / not-applicable / unsupported row, in registry order.

golden/exclusions/<revision>.json holds what the registry decided: the excluded rows, whose outcome and prose come from the registry alone and are identical for every trace judged against it — engine::build_row never consults the session for them. One distinct set per revision, and before the split every golden restated its revision’s whole set: at the time that was 59% of the corpus’s lines.

Every cell is verified against the corpus by cargo xtask ci (xtask::coverage::corpus). It is checked rather than trusted because it had already drifted twice: this paragraph is prose, and prose does not recount itself.

Nothing stopped being pinned. Splicing a golden back together with its ledger reproduces the whole report, and assert_reconstructs_the_full_report proves it does on every trace, on every run — so a judged row that went missing, a ledger that drifted from its registry, or rows that interleave in any order but the registry’s all fail the suite. totals.excluded stays in every golden as the per-trace tie back to the ledger: a clause entering or leaving the excluded set moves every golden for that revision, one line each.

Only excluded collapses. not-observed and not-applicable are per-trace evidence, and the table’s third row is the measure of it: near one distinct set per golden, in both revisions. Collapsing those would delete exactly what makes the captures differentiate each other.

Violation naming contract

A violation trace is named area-nnn-<slug>.jsonl and must produce a Fail/Warn row with findings for exactly requirement AREA-NNN — the golden harness enforces the attribution by name (violation_traces_fail_and_match_goldens, and draft::draft_violation_traces_fail_and_match_goldens for draft/), so a defect re-routed to a different requirement cannot re-bless silently. A stem that does not begin with a requirement ID fails the suite loudly. The one other prefix is wire-schema-<slug>.jsonl: such a trace must fail the report’s wire schema — the messages against the revision’s own JSON Schema, which no requirement row carries (ADR-0020).

Captured versus authored

Everything in good/, violations/ and draft/{good,violations}/ is authored: hand-written to exercise one clause. That is what makes them precise, and it is also their limit — an authored fixture can only ever confirm its author’s reading of the specification. A check that is wrong in the same way the author is wrong passes its unit tests and its corpus alike, and neither notices.

draft/captured/ exists to close that gap. Its traces are real recordings of traffic between implementations neither of which was written to satisfy these checks, so they can disagree with us — and when they do, the disagreement is information rather than a test failure. Their goldens are pinned without any pass/fail expectation, because a real implementation is whatever it actually is; what the golden protects is which requirements fire, on which events, with what detail. A check that starts misfiring on real traffic moves it — which is precisely the half of the report that stays in the per-trace file.

Provenance ledger

Every trace’s origin, in one reviewable place that survives history rewrites (the invariant test in golden.rs fails if a trace is added without a ledger row). All current traces share one provenance: hand-authored for this repository as synthetic sessions (no third-party traffic, no recorded production data), written against the 2025-11-25 spec text fetched live from modelcontextprotocol.io on 2026-06-09 (re-verified clause-by-clause against the live text on 2026-06-11) and validated against the embedded registry at the commit that introduced them.

Traces under draft/captured/ are the exception and record their own origin below: the implementations on both ends, the tool that recorded them, and when.

good/

violations/

Each file injects exactly the violation its name states; golden/ shows every row the trace decided, including any intrinsic secondary findings the injected defect causes (a malformed notification also fails lifecycle accounting, for example).

2026-07-28 captured (corpus/draft/captured/)

Two recordings of the same client driving the same scenarios, differing in one variable: which revision the server was serving. That is what makes the pair worth committing — a single capture shows what one implementation does, while a matched pair shows what the revision costs, and every difference between the two reports is attributable to that one change.

Both carry server/discover, tools/list, tools/call, completion/complete, resources/{list,read}, prompts/{list,get} and progress notifications; every request carries the revision’s per-request _meta envelope and its SEP-2243 metadata headers, and neither carries an initialize anywhere. Their tools/list results differ by two entries, which is the point of recording both: test_url_elicitation and test_list_changed are listed by the legacy server (18 tools) and not by the stateless one (16), because what each tool does has no place at 2026-07-28: that revision removed notifications/elicitation/complete and URL mode’s elicitationId (URL-mode elicitation itself remains), and moved list_changed notifications into subscriptions. Each listing is the first page; neither session follows nextCursor.

The one finding left: BASE-037, a warning, on the legacy leg. Of that server’s 24 results only the server/discover one carries io.modelcontextprotocol/serverInfo in its _meta; rmcp sets it there and on subscriptions/listen and nowhere else. The stateless server names itself on all 24, as it has since 2026-10-13. The legacy server is left without the field on purpose: it implements 2025-11-25, which names the server once, in initialize, and the measurement is that server held to a revision it does not implement (ServedRevision::names_itself_on_results). It is a SHOULD that exempts a server “specifically configured not to”, so it warns and never fails a run. The same warning stands on every other rmcp server that does not add the field itself (sdk-rust-2026-07-28); the Go and Python SDK servers set it on every result (sdk-go-2026-07-28, sdk-python-2026-07-28).

Two findings that used to be here were ours, not the implementations’. An earlier version of this pair reported TRAN-058 (client POSTs missing Mcp-Method/Mcp-Name) and TRAN-068 (SSE responses missing X-Accel-Buffering: no). Both were artifacts of the tap’s recording allowlist, which predated SEP-2243 and did not record those headers — the client sent them (rmcp’s transport rejects a 2026-07-28 request without Mcp-Method before dispatch, and the suite scored 23/23) and the server sent them (rmcp sets X-Accel-Buffering on every SSE response it builds). The allowlist was extended; both clauses now pass on both captures. The lesson is recorded rather than quietly fixed: a check can only be as honest as the recording it reads, and a capture path that silently drops evidence manufactures findings against conforming implementations.

The same lesson, a third time, one field over (2026-08-20). The tap recorded an exchange’s headers but not its method, so TRAN-025 and TRAN-039 — the Accept obligations of a POST and of a GET — were enforced as one rule applied to every client request whatever its form. That was wrong twice over, and both halves were found by pointing this workspace’s own reference host at its own reference server over HTTP and validating the tap: the conforming session-teardown DELETE, which owes no Accept header at all, drew two MUST-level failures, while a POST omitting application/json — the verbatim violation TRAN-025 names — was reported pass, because the one shared rule could only demand what both clauses had in common. EventBody::Http now carries the method, each clause is judged against the requests it binds, and an exchange whose method the capture did not record is judged by neither. These two captures were re-recorded on 2026-08-20 so the method is present, on 2026-10-04 when the draft ratchet moved to alpha.12, and on 2026-10-13 (below).

Why the runner’s 23/23 and our 59-vs-60 were both right — and how the runner caught up. The suite’s 2026-07-28 scenarios exercise features — list a thing, call a thing, read a thing — and a 2025-11-25 server answers all of them, because rmcp serves a per-request-versioned POST whichever revision the handler advertises. At 0.2.0-alpha.9 that was the whole of the runner’s reading, so it scored both servers 23/23. The registry here judges the specification’s prose instead, so it saw the one place the two servers actually differ: CACH-001, no ttlMs on cacheable results.

0.2.0-alpha.11 found the same thing, six weeks later. Its new wire-schema-valid check validates every message against the negotiated revision’s JSON schema, and it fails the 2025-11-25 leg’s four resource scenarios for must have required property 'cacheScope' / 'ttlMs' — that clause, independently. Measured at alpha.11, the legacy leg scored 37 passing / 4 failing and the stateless leg 41 / 0, so the runner separated the two servers it could not tell apart before. Neither instrument was wrong; they were measuring different things, and one of them saw this first. The pair is still the evidence for taking both readings — now with a worked example of the prose-level reading arriving earlier than the schema-level one.

And then the implementation closed the gap. rmcp 3.5.1 fills in missing cache hints for any peer speaking 2026-07-28 (rust-sdk #1308), so since the workspace moved to it (2026-10-12) the legacy server’s results carry ttlMs and cacheScope too (ttlMs: 0 on resources/list, rmcp’s default rather than this server’s choice), and cargo xtask draft-readiness scores both legs 42 passing / 0 failing. The pair was re-recorded on 2026-10-13, so the legacy leg no longer fails CACH-001 or the wire schema; until then it was kept as recorded on 2026-10-04 (69 pass, CACH-001 failing; the runner 38 passing / 4 failing), and this section’s history above is the evidence for what each instrument caught and when. With the hints filled in, the runner again scores both servers alike, and only the registry’s BASE-037 warning tells them apart.

The 110 not-observed rows are the honest denominator: of the 181 clauses this revision’s registry can judge, these sessions carried subject matter for 71. They open no subscription, present no cursor, draw no JSON-RPC error, and send no malformed _meta, so those clauses are neither passed nor failed here — they are untested, and the report says which.

Regenerate both with cargo xtask draft-readiness and copy target/draft-readiness/<revision>/tap/001-stateless.jsonl; the ephemeral port in the host header changes per run, so re-copying is a deliberate act with a golden diff, not something to do casually.

The stdio capture

It is the only capture that exercises subscriptions/listen. The official suite drives no subscription, so the four judged SUBS clauses — and BASE-039, which binds a subscription stream’s notifications — are backed by this file alone: an acknowledgment, a filter the server narrowed, four tagged notifications and an empty graceful-closure result. The same holds for the MRTR clauses. In the two HTTP captures every one of those rows now reads not observed; here they read pass.

Two defects were found by enriching it, and neither could have been found any other way. Until the session read a resource the catalog does not have, nothing in this workspace had ever exercised the server’s not-found path at this revision — and it answered -32002, which 2026-07-28 withdraws outright (basic/index#error-codes lists it under “Implementations of this protocol version MUST NOT emit these codes” and names -32602 as the replacement). The second was ours: the host’s recorder assigned seq when the send future completed rather than when the message was handed to the transport, so a reply received while that future was still pending landed in the trace ahead of its own request. That reads as the server answering an id nobody asked, and it failed BASE-046 on roughly one capture in three. Both are fixed, both have regression tests, and both are the argument for driving more traffic rather than more fixtures.

That asymmetry is the reason to keep all three, and it used to be invisible. Until the vacuous-pass fix, those rows read identically across the three files — pass everywhere, whether or not the session had opened a stream — and this paragraph recorded that as a known reporting limitation. It is a limitation no longer: every check counts the subjects it examined, so a clause with nothing to look at reports not-observed. Read in the other direction, the captures are complementary rather than redundant: the HTTP pair evidences the transport header and status clauses, which no stdio recording can carry, and this one evidences the subscription, MRTR, prompts, resources, logging, completion and error-code clauses, which theirs never reach.

What the 48 not-observed rows still are, and why. Thirty-three are Streamable HTTP mechanisms a stdio recording structurally cannot carry: twenty-five clauses of the TRAN-056…TRAN-102 band (it holds 27 judged clauses, and the two a stdio session does reach, TRAN-060 and TRAN-066, are judged here), the seven rows of the x-mcp-header behaviour table (TRAN-130…TRAN-136), and TOOL-034 — header mirroring is an HTTP mechanism, and “Clients using other transports (e.g., stdio) MAY ignore x-mcp-header annotations entirely”. Eight are server rejection rules — BASE-031, BASE-032, BASE-035, BASE-036, VERS-001, VERS-002, VERS-008, LOG-010 — reachable only by a client that deliberately sends something malformed, which this session does not: it is the conforming capture, and a probe session is a separate recording with a separate expected report. Two, CANC-003/CANC-011, bind a server that sends notifications/cancelled, and this one ends every subscription gracefully instead. TOOL-022 is the interesting one: rmcp’s client caches tools/list under the server’s own ttlMs, so a second listing never reaches the wire — a conforming client cannot exercise the deterministic-order clause within the TTL, which is a property of the caching feature working rather than a gap to close (the official suite’s runner does not cache, and judges it on both of its captures). The remaining four are not driven by this host: TRAN-128 and DISC-002’s dual-era probe, MRTR-024, and VERS-004.

The client-feature pages added twelve more on 2026-10-13, on both legs (review item 2.5). The session’s one sampling round carries no tools, so nothing it sends exercises the tool-use clauses (SAMP-026, SAMP-030…SAMP-033, SAMP-042) or the deprecated includeContext permission (SAMP-029); it asks for no roots (ROOT-013, ROOT-014, ROOT-018), and none of its elicitations is in URL mode (ELIC-064, ELIC-065). The three form elicitations and the sampling round are judged. When they were first judged one of them warned: ELIC-095 (“Clients SHOULD validate all responses against the provided schema”) on the host, whose AcceptWithDefaults policy answered the probe form — username and email required, neither with a default — with accept and empty content. That was a finding against this project’s own client, on both legs, not a reading the text leaves open, and it was fixed the same day: the policy now fills each required field without a default with a deterministic value of its type ("scripted" for both of these plain strings), and declines a form whose required fields no value can satisfy rather than accepting it with content the schema rejects (mcp_reference_host::script::accepted_content states the rule). Both legs were re-recorded with the fix and pass it.

Five used to be on that list for want of server surface; four have left it. CACH-015/CACH-016 needed a catalogue served in pages and PROM-017 a prompt carrying audio, and both are on the listings’ second pages now; TOOL-033 needed an x-mcp-header designation, and judges it as listed, which any transport carries (TOOL-045 passes beside it). The fifth, TOOL-034, is in the HTTP group above: the designation exists now, and only the transport keeps it unobserved here.

The HTTP capture of the same session

Recorded by the server, not the host, and that is the whole point. The host’s recorder sits at rmcp’s Transport seam, which carries protocol messages and nothing else — redaction by construction, and no HTTP framing to record even if it wanted to. So a host-side HTTP recording would report the Streamable HTTP clauses as not observed exactly like the stdio one. The server’s tap sits above the transport and sees the status line and the conformance-relevant headers, which is why this leg is the only recording in the corpus that can bear on them at all. Same session, both ends, one file each: the difference between the two reports is attributable to the transport and to nothing else.

At 125 of the 181 judgeable clauses it is the best-covered capture here, and the fourteen it gained on 2026-10-13 are the server’s own doing: the second pages carry the pagination clauses (CACH-015/CACH-016), the audio prompt (PROM-017), and a tool designating three arguments for Mcp-Param-* mirroring, which rmcp’s client mirrors when the tool loop calls it — two supplied and mirrored, one left out and not, which is the header table’s “value provided” and “not in arguments” rows from both sides (TOOL-033, TOOL-034, TOOL-045, TRAN-079…TRAN-082, TRAN-130, TRAN-134, TRAN-135, TRAN-137). Its 33 not-observed rows are the fourteen rejection rules only the probe exercises, seven clauses judged on the stdio leg and not on this one (CANC-005, PROG-005, PROG-008, TRAN-117, TRAN-118, TRAN-123, TRAN-124), TOOL-022 (rmcp’s client caches tools/list under the server’s own ttlMs, so a second listing never reaches the wire), VERS-004, which only the Rust SDK’s capture evidences, and the ten clauses no capture reaches, each with its reason under What the captures evidence, together.

The probe session

A conforming client cannot exercise a rejection rule. The clauses of this revision that say what a server owes a request it must not serve all reported not observed on every recording here, because nothing had ever sent such a request. This file is that request, ten times over.

The probes are built outside rmcp, and that is the point rather than a shortcut: rmcp’s client is what makes the other captures trustworthy — it builds the _meta envelope, mirrors the SEP-2243 headers, and will not emit an ill-formed request — so it is structurally incapable of being the probe. The bytes here are the fixture.

Its verdict is a ledger, not a pass. The probe breaks client-side clauses by construction: BASE-030 because its first request omits a required _meta field, TRAN-071/TRAN-072 because two probes are about exactly those headers, TRAN-079/TRAN-130 because the last one leaves out the header whose absence TRAN-136 obliges the server to reject. Demanding a clean report would mean demanding a probe that probes nothing. So every finding is listed in conformance/probe-baseline.json with a reason, and the gate holds the set in both directions: a finding not in the ledger is a new defect or a regression, and a listed finding that stopped occurring is either a fix that should retire its entry or a check that quietly stopped firing.

It has already worked in both directions. The first probe run drew two server-side findings — the server served a request naming log level "chatty", and honoured a cursor it never issued — which went into the ledger as open defects. When they were fixed, the gate refused the change until their entries were retired, which is the half of a ratchet that is easy to leave out. A third went the same way on 2026-10-13: BASE-037 entered the ledger as an open server-side warning the day the clause became judged, and its entry was retired in the change that put serverInfo on every result. Every rejection clause the probe reaches now passes; fourteen clauses pass on this capture and on no other (BASE-031, BASE-032, BASE-035, BASE-036, LOG-010, TRAN-073, TRAN-074, TRAN-075, TRAN-098, TRAN-102, TRAN-136, VERS-001, VERS-002, VERS-008). The fabricated cursor is still sent, and judged by nothing: on 2026-10-04 PAGE-010 and PAGE-011 were excluded at this revision, because its caching rules make a cursor issued before the recording began a valid one (the registry entries record the reasoning). The server still refuses it, and a_fabricated_cursor_is_refused_on_the_stateless_revision in mcp-everything-server’s tests holds it to that.

Its provenance is weaker than the pair above, and deliberately labelled so. Both ends of this session are ours: the official suite drives servers over --url only, so there is no third-party client for stdio to be recorded against. What it still supplies that an authored fixture cannot is that neither end was written to satisfy these checks, and that the machinery producing every byte — the stateless lifecycle, the _meta envelope, the MRTR retry loop — is rmcp’s, not this repository’s.

It is also the only capture that judges a verdict rather than pinning a report. cargo xtask draft-capture fails on any finding, because a finding in a session where both ends are ours is a defect here rather than news about somebody else’s code. Regenerate with BLESS=1 cargo xtask draft-capture (which rewrites this file) followed by cargo xtask bless.

That gate was red for part of 2026-10-13, on two warnings, and is clean again. BASE-037 became judged that day, and this server — rmcp’s result types — named itself in _meta.io.modelcontextprotocol/serverInfo only on its server/discover and subscriptions/listen results; the client-feature pages added ELIC-095 against the host (above). The gate was left red rather than loosened until both were fixed here: the everything server now puts serverInfo on every result it builds at 2026-07-28 (mcp_everything_server’s private server::identity module, applied at each handler’s return beside the caching hints), and the host’s form answers satisfy their schema. Both reference-host captures and the probe were re-recorded with the fixes, and the probe baseline’s server-side BASE-037 entry was retired in the same change.

What it caught. The first recording of this session reported six failures the HTTP captures could not: TRAN-060/066/119/120 and MRTR-001, because the interactive tools still sent elicitation/create and sampling/createMessage as independent server-to-client requests — the mechanism SEP-2322 replaced — and LOG-008, because the logging tool emitted notifications/message for a request that had not asked for them. The official suite’s 2026-07-28 scenarios exercise no interactive tool and no logging tool, so an HTTP-only corpus would have shipped both defects. That is the argument for capturing both transports rather than treating one as representative.

What the captures evidence, together

The table below is generated from the committed golden reports by cargo xtask draft-coverage and verified by cargo xtask ci — per ADR-0001 these numbers are a projection of the data, not prose anyone maintains. The same gate parses every count stated elsewhere in the living Markdown — the “N of the M judgeable clauses” claims and the “N pass, M fail” verdicts alike — and fails when one disagrees, which is how the counts in this section stopped being wrong. A number quoted rather than asserted goes in backticks, and is read as a specimen instead.

Across all 9 captures, 148 of the 181 judgeable clauses are evidenced by at least one recording. Each capture’s own judged count is what that recording carried subject matter for; everything else it reports not observed rather than counting it as a pass.

The 33 clauses no capture reaches: AUTH-097, AUTH-124, AUTH-129, AUTH-130, AUTH-131, AUTH-132, AUTH-133, CANC-003, CANC-011, DISC-002, ELIC-064, ELIC-065, MRTR-024, ROOT-013, ROOT-014, ROOT-018, SAMP-026, SAMP-029, SAMP-030, SAMP-031, SAMP-032, SAMP-033, SAMP-042, TOOL-035, TOOL-046, TRAN-061, TRAN-070, TRAN-083, TRAN-084, TRAN-096, TRAN-128, TRAN-132, TRAN-133.

The probe session closed the largest group — the rejection rules — and the cancellation round closed the next. The official SDKs’ conformance servers (below) closed six more without a line of this repository changing: each of the three that serve this revision lists a tool carrying an x-mcp-header designation, which TOOL-033, TOOL-045, TRAN-080, TRAN-082 and TRAN-137 judge, and the Rust SDK’s declares an extension, which VERS-004 judges.

The reference server’s own surface closed ten more on 2026-10-13. Every listing is now served in two pages — the suite’s catalogue first, then what the suite does not name — and both captures of the host follow nextCursor: the pages are CACH-015/CACH-016’s subject, and the second prompt page carries audio for PROM-017. A second-page tool designates three arguments for Mcp-Param-* mirroring, and the host’s tool loop calls it over HTTP with two supplied and one left out, so rmcp mirrors two headers and omits the third (TOOL-034, TRAN-079, TRAN-081, TRAN-130, TRAN-134, TRAN-135). The probe then sends the same call with one header missing, which the server must refuse and does (TRAN-136).

What is left — 33 clauses — is not backlog in the ordinary sense; each stays for a reason a richer session would not remove. Ten are the transport and lifecycle clauses below; the other 23 came with the client-feature and authorization pages and are grouped after them.

Two are out of an rmcp client’s reach: TRAN-132/TRAN-133, the behaviour table’s “Parameter value is null” row. A client can only send null for a designated argument whose schema admits it, and rmcp’s client drops any tool whose designated property’s type is not a single primitive — ["string", "null"] included — so a nullable designation never reaches an rmcp client’s call, and this host synthesizes only required arguments and never a null. The row’s pass path is authored (good/http-x-mcp-header-omitted.jsonl), and the rmcp restriction is a candidate to raise upstream.

One cannot be recorded by the server’s tap: TRAN-096, a recognized Mcp-Param-… header holding invalid characters. HTTP parsing strips a value’s edge whitespace before any handler sees it, and the tap records only values that decode as visible ASCII — rmcp likewise reads anything else as no header at all, and refuses the call as a missing one — so the antecedent never reaches the recording however the request is built. Authored traces carry both halves (draft/violations/tran-096-invalid-param-header-accepted.jsonl, draft/violations/tran-077-param-header-value-rejected.jsonl).

Three belong to a client no capture has: TRAN-061 needs a client to POST a notification over Streamable HTTP, and no 2026-07-28 capture contains one — rmcp’s stateless client cancels by closing the response stream, and neither the official runner nor the SDK client sends any. DISC-002 and TRAN-128 need a dual-era client that probes before falling back to initialize, and this host speaks only the stateless revision.

Two need server behaviour this one does not have: CANC-003/CANC-011 bind a server that sends notifications/cancelled, which at this revision may only tear down a subscriptions/listen stream. This server ends every subscription gracefully instead — the closure SUBS-005/SUBS-006 judge, and pass — so tearing one down by cancellation would be a second closure path, added to light up a check; the pass path is authored (good/subscription-server-teardown.jsonl).

One cannot be reached by a conforming host at all, and saying so is more useful than closing it. MRTR-024 is a server re-asking after a client’s shortfall, and a retry that omits requested input is the client violation MRTR-015 names: driving it would make the reference host non-conforming, which is the one thing this capture may not be. It is evidenced by an authored violation trace instead, where the fault belongs. VERS-004 used to be its pair — a capture would have to declare an extension, and this host implements none, and declaring one only to light up a check is precisely the vacuous evidence the corpus exists to avoid. The Rust SDK’s conformance server declares one of its own accord, and that is evidence.

One is a recording gap rather than a session gap: TRAN-070 needs a response stream to close mid-session, and the server’s tap records no lifecycle events at all, so no HTTP capture can carry one however the session is driven.

Seven need a protected server: AUTH-097, AUTH-124 and AUTH-129–AUTH-133 read a WWW-Authenticate challenge, and no committed capture is of a server that requires authorization. Authored traces carry each (draft/violations/auth-*).

Four need a server that advertises a malformed x-mcp-header: TOOL-035, TOOL-046, TRAN-083 and TRAN-084 bind a client to reject such a tool and never call it. This server advertises only what it implements, and every designation it serves is valid, so no client of it has anything to reject. Authored traces carry both halves (tran-082-invalid-tool-excluded-valid-called, tran-083-invalid-tool-called).

Twelve need a client feature no captured session uses. No capture carries a URL-mode elicitation (ELIC-064, ELIC-065): the everything server’s only one is test_url_elicitation, which it does not offer at 2026-07-28, and the SDK servers send none. The one sampling request captured is plain (no tools, no includeContext), so tool-enabled sampling and its toolChoice and result-pairing rules (SAMP-026, SAMP-029–SAMP-033, SAMP-042) are unreached. No server in any capture sends roots/list, so ROOT-013, ROOT-014 and ROOT-018 are too. Each has an authored violation trace under draft/violations/.

BASE-047 used to be on this list. It left without a trace being written, because it was never a corpus gap: the check behind it counted only malformed responses as subjects, so every capture full of well-formed results reported the clause not observed — the tool saying it had seen nothing to judge about a session that had carried dozens of them.

The official SDKs’ conformance servers (captured/, draft/captured/)

Nine recordings of the Tier 1 SDKs’ own conformance servers (the TypeScript SDK’s two lines are two servers) — the server its maintainers run the official suite against — driven over Streamable HTTP by an official SDK client. Neither end is ours: this repository supplies only the recorder and the judge. They are the evidence behind the book’s cross-SDK matrix, which cargo xtask sdk-matrix generates from their goldens; the verdicts and counts live there, once, and are not restated here.

The trace bytes are not reproducible, and are not normalized. Each server mints a fresh session id on every run, and nothing is rewritten after recording — a recording edited after the fact is no longer a recording. What is held fixed instead is everything that changes a result: the ports (the proxy records the Host header), the client script, the pins, and the one race the session had. The TypeScript client opens its standalone GET stream in the background, and while that GET and the next POST both awaited a status the validator — correctly — attributed neither, so TRAN-040 read not observed on some runs and pass on others; the client now waits for the GET to be answered before its next request. Five consecutive local runs then produced identical reports, seq for seq. The weekly comparison ignores a finding’s seq all the same, because a session whose replies land a line apart is the same session.

Regenerate with interop/setup.sh and interop/matrix.sh, then BLESS=1 cargo xtask sdk-matrix --recaptured interop/out-matrix, cargo xtask bless, cargo xtask sdk-matrix and cargo xtask draft-coverage, and review the golden diff.

2026-07-28 authored (corpus/draft/)

Fixtures for revision 2026-07-28, judged by its registry. Hand-authored rather than captured, so each is a minimal trace written to exercise one clause, which is what keeps a violation attributable to the check it kills. Recorded 2026-07-28 sessions are in draft/captured/ (above), and the interop job records the official Python SDK’s client and server at that revision and requires them to judge clean (interop/README.md).

Where a trace falsifies more than one requirement, the row says so and why. There are only three reasons, and none is sloppy authorship: several clauses state one rule across several sections and share a check by design, one clause’s antecedent is itself a violation by the other party — a server can only fail to reject a bad header if the client sent one — or the shape a trace exists to carry is a violation in its own right: an HTTP answer with "id": null that the framing ties to its request is BASE-052’s whenever that request’s id could be read. Every other row falsifies exactly the requirement it is named for.

Every result names its server, and every request its client (2026-10-13). When BASE-033, BASE-037 and DISC-003 stopped being excluded, the authored traces were brought up to the two SHOULDs they had been written without: each result answering a request under the per-request envelope gained _meta.io.modelcontextprotocol/serverInfo (corpus-server 0.1.0), and the eight violation traces whose requests lacked clientInfo gained it. Nothing else in any trace changed, and no other row’s outcome moved; without the edit every authored trace would carry a warning unrelated to the clause it exists for. The three traces named for those clauses are the only ones left without.

Every form elicitation carries its schema (2026-10-13). When the client-feature pages entered the registry (review item 2.5), seven authored traces were found asking for form mode elicitation without the requestedSchema the page requires, or with no parameters at all — fixtures written for MRTR clauses that never needed one: mrtr-004, mrtr-015, mrtr-016-request-state-not-echoed, mrtr-018, mrtr-024, tran-066 and base-034-input-request-for-undeclared-capability. Each gained the same message and requestedSchema; nothing else changed. The wire schema had been failing all but the last of them for the omission, unrelated to the clause each exists for; it now passes them, and no existing requirement’s outcome moved.

Extensions at 2026-07-28 (corpus/draft/, ADR-0023)

Fixtures for the tasks (io.modelcontextprotocol/tasks) and skills (io.modelcontextprotocol/skills) extensions, hand-authored like the rest of corpus/draft/ and judged by the 2026-07-28 registry, whose extension clauses report in each report’s extensions block and never move its verdict. Every violation trace here leaves the core verdict pass unless its row says otherwise, which is the separation the corpus exists to show: the extension’s own verdict fails, the report’s does not. A task-… or skill-… trace is named for the extension clause it falsifies, and the golden tests look for that row in the extension block.

Conformance results

A conformance toolkit should be willing to measure real implementations — its own and others’ — against the official suite, and publish what it finds. These measurements are stewardship artifacts: every number is the official suite’s number, captured by running it, with this project’s registry used only to read each failure back to a specific spec clause. Every claim has a command that reproduces it.

This project’s reference implementations

The reference server and host are a hard CI gate, not a one-off measurement: on every run, the conformance job drives the pinned official suite against mcp-everything-server (server scenarios) and mcp-reference-host (client scenarios), and replays the captured sessions through the validator for the agreement check. A regression fails the build. The live status is whatever the latest main run reports.

The agreement check covers the wire schema too: where the suite reports its wire-schema-valid check (from 0.2.0-alpha.11, so the alpha-tracking job and the 2026-07-28 readiness run, not yet the stable pin), every message it flags is matched against the messages the validator flags in the recorded sessions, and a message flagged by only one side fails the run unless the committed conformance/wire-schema-divergences.json explains it.

rmcp tier-gap report

The published measurement of the official Rust SDK (rmcp) against the suite is the worked example of the method:

📄 rmcp tier-gap report — 2025-11-25

It records the server-scenario pass count, the requirement-level reading of each failure, a concrete close-the-gap checklist, and the exact commands to reproduce it — including a note on why the suite’s tier-check aggregate is not the figure to trust (it is GitHub-token-gated and its conformance counter carries a known upstream counting bug). The headline finding at the report’s measurement date: two failing server scenarios, neither of which is a 2025-11-25 normative-clause violation — one sits just below the spec’s RFC 2119 floor (template-argument substitution is schema prose), the other is a SEP-1330 serialization bug already filed upstream. That is the kind of distinction a requirement-level tool exists to draw; see the report for the current count and the close-the-gap steps.

pmcp tier-gap report

The same method applied to a community SDK, to show it generalizes beyond the official one:

📄 pmcp tier-gap report — 2025-11-25

pmcp ships no server wired to the suite, so the report builds a small one from the SDK’s public API (its harness is committed beside the report) and states that caveat plainly. Each failing scenario is traced to a specific limitation of the SDK’s Streamable HTTP surface, both on the wire and in the SDK’s source.

A second reader of recordings

The official suite runs live scenarios. The one other tool that judges a recorded session, mcpsnoop, is run over the whole trace corpus too, and every place its verdict differs from this project’s is triaged — which tool is right, by which clause, and what was fixed or drafted for upstream:

📄 A second opinion: mcpsnoop

The 2026-07-28 surface

The official suite has no stable release for 2026-07-28 yet, so this project measures its reference server against the suite’s pinned pre-release every week and records the score in a committed baseline; Two revisions at once has the current figures and what they have already shown.

The cross-SDK matrix

Each Tier 1 SDK the matrix covers — TypeScript, Python, Go and Rust — ships a conformance server: the server its maintainers run the official suite against. TypeScript has two lines and so two rows: v1 (@modelcontextprotocol/sdk, the maintenance line, which implements the specification up to 2025-11-25) and v2 (@modelcontextprotocol/server and its companions, which also serves 2026-07-28). This page records each of those servers, at each revision it serves, while an official SDK client drives it, and judges every recording with this project’s validator. Nothing of this project’s speaks MCP in these sessions; the recorder and the judge are the only parts of it involved.

The table below is generated by cargo xtask sdk-matrix from the golden reports committed under corpus/, and cargo xtask gates fails when it drifts from them. A scheduled job re-records every session with the pinned SDKs each week and fails if the results differ from the committed ones, so a row here is what the pinned release does today rather than what it did once. How each session is recorded, with the exact commands, is Recording an SDK’s server.

At 2025-11-25 every server is driven by the same TypeScript SDK (v1) client (ts-client.mjs). At 2026-07-28 every server is driven by the same Python SDK client (py-client.py).

Findings. Every failing or warning row of a committed report, with the first of its findings as the validator words it; the report link holds the rest.

• TypeScript v1, 2025-11-25 — BASE-086 (SHOULD, warn, 8 findings): the server sent tool “test_tool_with_logging”’s inputSchema declaring $schema “http://json-schema.org/draft-07/schema#”; JSON Schema 2020-12 (https://json-schema.org/draft/2020-12/schema) is the recommended dialect
• Go, 2026-07-28 — BASE-034 (MUST NOT, fail, 1 finding): server asked for elicitation/create, which needs the elicitation capability, but the request’s clientCapabilities did not declare it
• Go, 2026-07-28 — TRAN-068 (SHOULD, warn, 6 findings): SSE response does not carry X-Accel-Buffering: no
• Go, 2026-07-28 — MRTR-012 (MUST NOT, fail, 1 finding): server asked for elicitation/create, which needs the elicitation capability, but the request’s clientCapabilities did not declare it
• Go, 2026-07-28 — MRTR-013 (MUST NOT, fail, 1 finding): server asked for elicitation/create, which needs the elicitation capability, but the request’s clientCapabilities did not declare it
• Go, 2026-07-28 — ELIC-059 (MUST NOT, fail, 1 finding): inputRequests[user_context] (elicitation/create) asks for form mode, but the request’s clientCapabilities does not declare elicitation at all
• Rust, 2026-07-28 — BASE-037 (SHOULD, warn, 5 findings): result answering tools/list carries no io.modelcontextprotocol/serverInfo in its _meta; servers should include it in every result unless specifically configured not to

Reading a row

Each row is one recorded session. Verdict and the four counts are the report’s, with the same meaning as in Reading a report: not observed counts the clauses the session carried nothing to judge, so a short session is not mistaken for a conforming one. Wire schema is every message checked against the revision’s published JSON Schema. Not served means the server does not implement that revision — the client asked, and the server answered with an older one — so there is no session to judge.

Every server at a revision is driven by the same client running the same script, so the difference between two rows of one revision is the server’s. The script is small — list, call, read, get — so these sessions evidence the common surface. Compare like with like: a row with more passes did not necessarily conform better; it may only have been asked more.

Findings are reported, not hidden

A failing row is a finding against that SDK’s pinned release, stated with the clause it breaks and a link to the report and the recording it came from. Each was read against the recording before being published — a check can only be as honest as the capture it reads, and the corpus’s own history has findings that turned out to be the tool’s, not the implementation’s (the trace corpus). A finding you believe is wrong is a bug to file with its requirement ID; the dispute process says how each is triaged.

A second opinion: mcpsnoop

mcpsnoop is the one other tool that judges a recorded MCP session offline: mcpsnoop check reads a capture and fails on a fixed set of rules. The official suite calibrates this project against live scenarios; mcpsnoop calibrates it against a reader of recordings, which is what this project is. This page is that comparison over all 358 corpus traces, with every disagreement triaged: which tool is right, by which clause, and what was done about it.

How the comparison is made

The binary. mcpsnoop 0.26.1, the current npm release when measured, taken from the npm registry and never built from source. The mcpsnoop package is a launcher with no install script; the Go binary ships in a per-platform package. Both tarballs were fetched with npm pack and checked against the registry’s integrity:

• [email protected] — sha512-midlHuFR9PGrrW8BUm/F16k76ccPmVfE8OVBWR7DkSQzZjaGookgTH4ACpytuWnD5VnKIxvNN2Y8smwjyq4xMw==
• @mcpsnoop/[email protected] — sha512-mNsXyDgs4vznFP6BQz9oxAJYLEo+I2YC2F9vDICd5Z4FSUPTjHWT/A6HW+i6/FvyUu0Ymf3HnMc2zM9X2xZQ2Q==

The binary inside, package/bin/mcpsnoop, has SHA-256 81c3636fa5a371833ab4558d6ac417d9d94a86f99949e0cff32bb09ccf69c2a9. To measure, point MCPSNOOP at it and run cargo xtask mcpsnoop; without it the task skips loudly. mcpsnoop is never a gate on a pull request — a scheduled, informational job re-measures it.

The same session in front of both. Our traces are converted into the capture format mcpsnoop writes itself (xtask/src/mcpsnoop/convert.rs). On stdio the conversion is lossless. On HTTP a frame gets the headers, status and exchange the trace’s own order settles — the rules our validator’s framing applies — and no more; a frame whose context the trace cannot settle is marked unframed, and a finding that reads such context there is set aside, not counted. The conversion is checked against mcpsnoop’s own recordings on every measurement: sessions recorded through both tools at once — the reference host against the everything server, committed under conformance/mcpsnoop/native/ — must draw the same mcpsnoop findings from the converted trace as from mcpsnoop’s capture once that capture’s frames share one connection, the single field the conversion fixes rather than carries. In the committed run 3 of 3 such sessions did: http-2025-11-25 (28 findings), http-2026-07-28 (22 findings), stdio-2025-11-25 (28 findings).

What is compared. mcpsnoop’s conformance signals — invalid, warn and mismatch, the three its own rule descriptions call protocol violations — against our fail and warn rows, an extension’s among them although they never decide our verdict, and the wire schema. Its other signals (a call that ended in an error, one still pending when the capture ended, a deprecated feature) are counted per trace but say nothing about conformance. Each mcpsnoop rule is mapped to the registry clauses its condition violates, read from both texts (conformance/mcpsnoop/rules.json, tabulated below); a mapping is partial where the rule checks only part of the clause. Then, per trace: a fired rule one of whose clauses we flag is agreement; a fired rule none of whose clauses we flag is a mcpsnoop-only divergence; a clause we flag that a rule maps fully, with that rule silent, is an ours-only divergence; a clause we flag that no rule maps fully is beyond mcpsnoop, a difference of scope rather than of reading.

Summary

Verdicts, ours against mcpsnoop’s conformance signals:

Traces by how the two readings relate:

mcpsnoop flagging less than we do is mostly scope, not disagreement: its rules cover a part of the registry, and the traces it passes while we fail are the beyond mcpsnoop row. Across the corpus we flag 268 distinct clauses (counted per revision) that no mcpsnoop rule maps fully. Findings were set aside for reading HTTP context the conversion could not supply on 7 traces.

Divergences

Every divergence the run shows, and its triage (conformance/mcpsnoop/triage.json). --check fails while any divergence is untriaged or any triage entry matches nothing.

1. invalid-frame (mcpsnoop-only)

The server answers initialize with "code": -32602.5. We report BASE-007, the clause that names the defect; mcpsnoop’s decoder refuses the frame and reports it as not JSON-RPC at all. Both are true — a non-integer code breaks JSON-RPC 2.0, which BASE-008 incorporates — and the two readings convict the same frame. The difference is only which clause carries the finding: ours attributes it to the most specific clause and leaves BASE-008 to framing faults, mcpsnoop has no rule finer than the parse.

BASE-007 (MUST): Error codes MUST be integers. — source

BASE-008 (MUST): All messages between MCP clients and servers MUST follow the JSON-RPC 2.0 specification. — source

Resolution: none: the same defect on the same frame, reported at different granularity

2. request-id-in-flight (mcpsnoop-only)

On Streamable HTTP the client POSTs tools/call id 1 and the server answers that POST, in its own application/json body, with an error whose id is null although the request’s id was readable — a BASE-052 violation both tools report. The client then sends a new tools/call reusing id 1. mcpsnoop reports the reuse as an id already in flight: having failed to match the null-id error by id, it keeps request 1 open forever. But the answer arrived as the response to that very POST, so the client has received a response for it, and BASE-045 forbids reuse only of an id the sender has “not yet received a response for”. Our framing ties a null-id answer to the request whose exchange framed it; mcpsnoop records the exchange (exchange is in its own capture) but does not use it here. The conversion is not the cause: the request and the error carry the same exchange, exactly as mcpsnoop’s proxy records them.

BASE-045 (MUST NOT): The request ID MUST NOT match the ID of any other request the sender has issued and not yet received a response for. — source

BASE-052 (MUST): Error responses MUST include the same ID as the request they correspond to (except in error cases where the ID could not be read due a malformed request). — source

Resolution: upstream: mcpsnoop-null-id-answer

3. server-rejected-header-mismatch (mcpsnoop-only)

In each trace the server answers -32020 (HeaderMismatch) to a POST whose headers match its body: a tools/list with every header correct (tran-098), and a tools/call that omits Mcp-Param-Region because region is null or absent — exactly what the client must do (tran-133, tran-135). mcpsnoop reports each as “a routing header disagrees with the body”. By its own documentation a server’s -32020 “counts as the same condition” as a disagreement, so it takes the server’s word over its own comparison — which on these frames found nothing. The defect is the server’s (TRAN-133/TRAN-135: the server MUST NOT expect the header; TRAN-098: the rejection must be 400), and mcpsnoop’s finding attributes it to the client’s headers. Where the client really was at fault (tran-089-sentinel-markers-miscased, tran-077-param-header-value-rejected, tran-079-param-header-value-not-mirrored) the same rule agrees with us.

TRAN-133 (MUST NOT): Parameter value is null | Client MUST omit the header | Server MUST NOT expect the header — source

TRAN-135 (MUST NOT): Parameter not in arguments | Client MUST omit the header | Server MUST NOT expect the header — source

TRAN-098 (MUST): Servers MUST reject requests with a 400 Bad Request HTTP status and JSON-RPC error code -32020 (HeaderMismatch) if any validation fails. — source

Resolution: upstream: mcpsnoop-trusts-header-mismatch-rejection

4. BASE-030 (ours-only)

Each trace’s only request carries "_meta": {} — no protocol version anywhere, in the body or (base-032, HTTP) in a header. We judge the trace at 2026-07-28 because the corpus files it under draft/, which is how this repository assigns a revision; mcpsnoop infers the revision from the session and finds none, so it applies no 2026-07-28 rule. Given what each tool is told, each is right: an empty _meta is a violation at 2026-07-28 and none at 2025-11-25. mcpsnoop does flag the same field set as missing wherever the session names 2026-07-28 (base-030-request-meta-missing-required-field and the probe capture agree with us).

BASE-030 (MUST): Client requests carry the following io.modelcontextprotocol/* fields in meta; fields marked as required MUST be included on every request. — source

Resolution: none: the revision is stated to our validator out of band and is absent from the trace

5. MRTR-002 (ours-only)

The same request and the same reasoning as BASE-030 above: MRTR-002 restates the rule on the multi round-trip page.

MRTR-002 (MUST): Every request MUST include the required meta fields; see meta. — source

Resolution: none: the revision is stated to our validator out of band and is absent from the trace

6. TOOL-016 (ours-only)

The same request and the same reasoning as BASE-030 above: TOOL-016 restates the required _meta fields on the tools page.

TOOL-016 (MUST): Every request MUST include the required meta fields; see meta. — source

Resolution: none: the revision is stated to our validator out of band and is absent from the trace

7. BASE-030 (ours-only)

A legacy client sends initialize naming 2025-11-25. In vers-008 the server speaks only 2026-07-28 and refuses; in base-030-legacy-initialize-negotiated-2026-07-28 it answers naming 2026-07-28 and the session goes on under it. Judging the whole trace at 2026-07-28 (the corpus’s draft/ assignment for the first; the server’s initialize result, which is the session’s revision, for the second), we report the initialize as a request missing the required _meta fields — deliberately: checks/stateless/meta.rs exempts this request from BASE-031, citing basic/versioning‘s compatibility matrix (which says of exactly this request that it “also lacks the required _meta fields”), and states that the client’s own defect is still reported, by BASE-030. mcpsnoop 0.26.1 draws nothing on either trace. Measured 2026-10-25 on edited copies of the second trace’s converted capture: it applies request-meta-missing to a request only when that request’s own _meta carries io.modelcontextprotocol/protocolVersion 2026-07-28 (an initialize whose _meta names it and lacks the other fields is flagged, so initialize is not exempt); a request with no _meta, an empty one, or one naming 2025-11-25 draws nothing, and setting the initialize params’ protocolVersion to 2026-07-28 changes nothing. So its per-request revision is the one the request states in _meta, not params.protocolVersion and not the server’s answer; an earlier version of this note said it reads the request’s own protocolVersion, which that measurement does not support. Whether a 2026-07-28 clause binds a request that is itself speaking 2025-11-25 is not settled by the text: the matrix describes the request as lacking the fields without saying the legacy client is non-conformant for it, and nothing makes a 2025-11-25 client subject to 2026-07-28. The same question sits under our TRAN-071 finding on the probe capture’s legacy initialize.

BASE-030 (MUST): Client requests carry the following io.modelcontextprotocol/* fields in meta; fields marked as required MUST be included on every request. — source

VERS-008 (SHOULD): A server that supports only modern versions SHOULD name the protocol versions it supports in any error it returns to an initialize request, on any transport: legacy clients have no fall-forward mechanism, and this message may be the only diagnostic they can surface to users. — source

Resolution: open: decide whether a legacy-era request inside a 2026-07-28 trace is held to that revision’s request-envelope clauses (BASE-030 and its restatements, TRAN-071); the current reading is recorded in checks/stateless/meta.rs

8. MRTR-002 (ours-only)

The legacy initialize of either trace above, under MRTR-002’s restatement of the same rule.

MRTR-002 (MUST): Every request MUST include the required meta fields; see meta. — source

Resolution: open: the same decision as BASE-030 on these traces

9. TOOL-016 (ours-only)

The legacy initialize of either trace above, under TOOL-016’s restatement of the same rule.

TOOL-016 (MUST): Every request MUST include the required meta fields; see meta. — source

Resolution: open: the same decision as BASE-030 on these traces

10. LIFE-018 (ours-only)

A 2025-11-25 HTTP session negotiates, then sends a request without MCP-Protocol-Version. 2025-11-25 requires the header on every request after initialization; mcpsnoop’s rule for a missing routing header (“missing where the negotiated revision requires it”) fires only at 2026-07-28. Reproduced on a session recorded by mcpsnoop’s own proxy, so the conversion is not the cause: native/version-header-omitted-2025-11-25.mcpsnoop.jsonl (initialize, notifications/initialized with the header, tools/list without it) passes mcpsnoop check with every signal enabled.

LIFE-018 (MUST): If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server. — source

TRAN-017 (MUST): If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server, allowing the MCP server to respond based on the MCP protocol version. — source

Resolution: upstream: mcpsnoop-version-header-2025-11-25

11. TRAN-017 (ours-only)

The transport page’s statement of LIFE-018’s rule; the same missing header and the same mcpsnoop gap.

TRAN-017 (MUST): If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server, allowing the MCP server to respond based on the MCP protocol version. — source

Resolution: upstream: mcpsnoop-version-header-2025-11-25

12. response-unmatched (mcpsnoop-only)

A POST carrying Host and Origin evil.example.com is refused with HTTP 403 and a JSON-RPC error that has no id; the session then proceeds from localhost. The transport’s security warning, at both revisions, describes exactly that answer: “If the Origin header is present and invalid, servers MUST respond with HTTP 403 Forbidden. The HTTP response body MAY comprise a JSON-RPC error response that has no id.” The refusal happens before the request is read, so there is no id to echo, and BASE-009/BASE-052’s id rule does not reach a body the transport clause permits to have none. mcpsnoop reports the id-less error as matching no request. We did the same, as BASE-009, until 2026-10-13 — on the official suite’s dns-rebinding-protection scenario against the everything server (conformance/wire-findings.json) — and these two traces are the regression pair for that fix.

BASE-009 (MUST): Error responses MUST include the same ID as the request they correspond to (except in error cases where the ID could not be read due a malformed request). — source

BASE-052 (MUST): Error responses MUST include the same ID as the request they correspond to (except in error cases where the ID could not be read due a malformed request). — source

Resolution: upstream: mcpsnoop-origin-refusal-unmatched

13. progress-after-completion (mcpsnoop-only)

A conforming 2025-11-25 task session: the server answers a task-augmented tools/call with a CreateTaskResult (seq 4) and sends progress under the request’s token while the task is working (seq 5, and seq 10 after a tasks/get that still says working); the task is completed only at seq 12. The tasks page has the token “continue to be used for progress notifications throughout the task’s lifetime, even after the CreateTaskResult has been returned” (PROG-014) and stops progress at the task’s terminal status (PROG-016), which this session respects; our validator passes it. mcpsnoop 0.26.1 warns on both notifications as arriving “after its request completed”, with the text “2026-07-28 requires them to stop”: it takes the CreateTaskResult for the request’s completion and applies that revision’s rule to a 2025-11-25 session. The same rule fires, correctly, on prog-019 (progress after an ordinary response) and, for the earlier of its two notifications, wrongly on prog-016 for the same reason as here; both traces agree with us at the trace level.

PROG-014 (MUST): For task-augmented requests, the progressToken provided in the original request MUST continue to be used for progress notifications throughout the task’s lifetime, even after the CreateTaskResult has been returned. — source

PROG-016 (MUST): Progress notifications for tasks MUST stop after the task reaches a terminal status (completed, failed, or cancelled) — source

Resolution: open: whether to report it upstream is the maintainer’s call; the reproduction is corpus/good/stdio-task-progress.jsonl, whose task handling the 2025-11-25 tasks page defines (PROG-014)

Found on live recordings

Divergences that only a session recorded by mcpsnoop itself shows, because they turn on something our trace format does not record.

response-unmatched — mcpsnoop-defect, right: ours

Recorded live: the reference host drives the everything server over Streamable HTTP at 2025-11-25, through mcp-trace-capture and mcpsnoop’s proxy at once. The server sends elicitation/create (and sampling/createMessage) on a tool call’s SSE stream; the client answers each with a new POST, as the transport requires — and its HTTP pool sends that POST on a different TCP connection. mcpsnoop pairs a server request with its answer only within one connection, so it reports each answer as “response id has no matching request” and each server request as never answered: five false warn findings and five false pending ones. Rewriting the capture’s conn_id to one value removes exactly those ten and nothing else, and our converted trace — which carries no connection — draws the remaining findings exactly. A JSON-RPC id is scoped to the session, never to a connection, and nothing obliges a client to reuse one.

Evidence: conformance/mcpsnoop/native/http-2025-11-25.mcpsnoop.jsonl, conformance/mcpsnoop/native/http-2025-11-25.trace.jsonl.

BASE-003 (MUST NOT): The request ID MUST NOT have been previously used by the requestor within the same session. — source

TRAN-024 (MUST): Every JSON-RPC message sent from the client MUST be a new HTTP POST request to the MCP endpoint. — source

Resolution: upstream: mcpsnoop-connection-scoped-ids

protocol-version-header-missing — mcpsnoop-defect, right: ours

The live reproduction of divergence LIFE-018 above: a 2025-11-25 session through mcpsnoop’s proxy whose tools/list POST omits MCP-Protocol-Version after a completed handshake. mcpsnoop check with every signal enabled exits 0.

Evidence: conformance/mcpsnoop/native/version-header-omitted-2025-11-25.mcpsnoop.jsonl.

LIFE-018 (MUST): If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server. — source

TRAN-017 (MUST): If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server, allowing the MCP server to respond based on the MCP protocol version. — source

Resolution: upstream: mcpsnoop-version-header-2025-11-25

Upstream issue drafts

Written for mcpsnoop’s tracker and not filed: filing is the owner’s call.

mcpsnoop-connection-scoped-ids: check: server-to-client requests answered on another connection are reported as unanswered (HTTP)

Version: mcpsnoop 0.26.1 (npm, linux-x64).

What happens. On a streamable-HTTP session at 2025-11-25, the server sends elicitation/create on a tools/call SSE stream. The client answers it with a new POST, as the transport requires (“Every JSON-RPC message sent from the client MUST be a new HTTP POST request to the MCP endpoint”). The client’s HTTP pool sent that POST on a different TCP connection, so it was recorded with a different conn_id. mcpsnoop check then reports response id has no matching request (warn) on the answer and elicitation/create (id 0) never got a response (pending) on the request — once per server request in the session.

Expected. A JSON-RPC id is scoped to the session, not to a connection (2025-11-25 basic: “The request ID MUST NOT have been previously used by the requestor within the same session”), and a client may send each POST on any connection. A server request should be paired with the client’s response by id within the session.

Evidence. Recorded by mcpsnoop http in front of a streamable-HTTP server, with the reference client answering four elicitation/create and one sampling/createMessage: ten findings (five warn, five pending). Rewriting every conn_id in the capture to one value and re-running check removes exactly those ten.

Suggested fix. Key outstanding server-to-client requests by session (and direction), not by conn_id; keep the connection only for routing-header attribution.

mcpsnoop-null-id-answer: check: an id-less error returned in a POST’s own body leaves the request in flight, so a later reuse is reported

Version: mcpsnoop 0.26.1.

What happens. Streamable HTTP, 2026-07-28. The client POSTs tools/call with id: 1; the server answers that POST, in its own application/json body, with {"jsonrpc":"2.0","id":null,"error":{"code":-32602,...}}. check correctly reports response id has no matching request — the id was readable, so the server should have echoed it. The client then POSTs a new request reusing id: 1, and check reports request reuses an id already in flight.

Expected. The request is not in flight: its answer arrived as the response to the very POST that carried it, and both envelopes carry the same exchange. The specification forbids reusing an id only while “the sender has issued and not yet received a response for” it. The null id is the server’s defect, already reported; the reuse is not the client’s.

Suggested fix. On HTTP, when a response with a null (or unmatched) id arrives on an exchange that carried exactly one request, close that request — or at least do not count it as in flight for the reuse rule.

mcpsnoop-trusts-header-mismatch-rejection: check: a server’s -32020 is reported as “a routing header disagrees with the body” even when every header matches

Version: mcpsnoop 0.26.1.

What happens. Streamable HTTP, 2026-07-28. A tools/call whose tool marks region with x-mcp-header, sent with "region": null and therefore no Mcp-Param-Region header — the behaviour table says “Parameter value is null | Client MUST omit the header | Server MUST NOT expect the header”. The server wrongly rejects it with -32020 (HeaderMismatch). check reports mismatch: a routing header disagrees with the body. The same happens when the parameter is absent from the arguments, and when a server answers -32020 to a tools/list whose Mcp-Method and MCP-Protocol-Version match the body.

Expected. No header disagrees with the body in these requests, and mcpsnoop’s own comparison found none. The faulty party is the server. The rule description says a server’s -32020 “counts as the same condition”, which convicts the client’s headers on the server’s word.

Suggested fix. Report a -32020 as a mismatch only when mcpsnoop’s own comparison agrees, or could not be made (for instance, the tool definition was not captured). When the comparison ran and found the headers consistent, report the rejection as the server’s — a separate message, or none.

mcpsnoop-version-header-2025-11-25: check: a missing MCP-Protocol-Version header is not reported on 2025-11-25 sessions

Version: mcpsnoop 0.26.1.

What happens. A streamable-HTTP session negotiates 2025-11-25 (initialize, then notifications/initialized carrying MCP-Protocol-Version: 2025-11-25), then POSTs tools/list without the header. check --fail-on error,invalid,warn,mismatch,pending,late-result,duplicate,deprecated,incomplete exits 0.

Expected. 2025-11-25 requires the header: “If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server.” The mismatch signal’s description already covers a routing header that “is missing where the negotiated revision requires it”; at present only 2026-07-28 is treated as requiring it.

Reproduce. mcpsnoop http --target <server>/mcp, then with curl: an initialize POST, an initialized POST with the header and the returned Mcp-Session-Id, and a tools/list POST with the session id but no MCP-Protocol-Version. Run mcpsnoop check on the session.

Suggested fix. At 2025-11-25 (and 2025-06-18), require the header on every POST after the initialize exchange.

mcpsnoop-origin-refusal-unmatched: check: the id-less error body of a 403 Origin refusal is reported as a response with no matching request

Version: mcpsnoop 0.26.1.

What happens. Streamable HTTP, 2025-11-25 or 2026-07-28. A POST arrives with Origin: http://evil.example.com; the server refuses it with 403 Forbidden and the body {"jsonrpc":"2.0","error":{"code":-32600,"message":"Forbidden: Origin not allowed"}}. check reports response id has no matching request on that error.

Expected. No finding. The transport’s security warning reads: “If the Origin header is present and invalid, servers MUST respond with HTTP 403 Forbidden. The HTTP response body MAY comprise a JSON-RPC error response that has no id.” The server refuses before it reads the request, so it has no id to echo, and the specification permits the body that results.

Suggested fix. When an id-less error is the body of a 403 answering a request that carried an Origin header, treat it as that exchange’s refusal rather than as an unmatched response.

The rule map

Each mcpsnoop rule, the message template that identifies it (* is any run), and the clauses it corresponds to; italic ids are partial. Fired counts traces where the rule fired and was not set aside. A rule no trace fires was read from the binary’s strings and is untested here.

Every trace