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.