{"schemaVersion":1,"id":"https://lucioduran.com/projects/mcp-contract-harness","url":"https://lucioduran.com/projects/mcp-contract-harness","title":"MCP Contract Harness","description":"Read-only MCP server and independent clients for checking stdio negotiation, pagination, errors and cancellation, with actual wire messages and reproducible reports.","language":"en","datePublished":"2026-10-21","dateModified":"2026-10-21","contentFormat":"text/markdown","content":"[Projects]() / MCP Contract Harness\n\n# MCP Contract Harness\n\nRead-only MCP server and independent clients for checking stdio negotiation, pagination, errors and cancellation, with actual wire messages and reproducible reports.\n\nAuthor: [Lucio Durán]() · Python 3.11.9 / Node 24.8.0 / MCP 2025-06-18 · License: [MIT]()\n\nPage published: 2026-10-21 · Page updated: 2026-10-21\n\n[Repository]() · [Client report]()\n\n## Problem and relevance to agents\n\nA successful initialize response does not establish that an integration handles a second page, cancellation or errors. This project checks those contracts against a specific MCP version and preserves exchanged messages.\n\nAgents need tool discovery, complete resource retrieval and a distinction between protocol and execution errors. This implementation exposes those boundaries through client checks and transport traces.\n\n## Architecture\n\n1. **Bounded server.** A Python standard-library server implements a subset of MCP 2025-06-18 over stdio JSON-RPC. It exposes three fictional notes and two read-only tools without filesystem or network access.\n2. **Three clients.** A custom Python client, official Python SDK 2.3.0 and official TypeScript SDK 1.32.1 connect to the same server. SDK clients negotiate from 2025-11-25 to the supported version.\n3. **Wire recording.** A proxy records actual lines from SDK clients before forwarding them. The custom client records its own transport. Traces preserve direction and JSON-RPC messages.\n4. **Contract validation.** An additional validator checks correlation, cursor chains, unanswered cancelled requests and a subsequent answered ping. Tool execution failures use isError; protocol failures use JSON-RPC errors.\n\n- [Design and protocol sources]()\n- [MCP contract and errors]()\n- [Server implementation]()\n- [Wire evidence validator]()\n\n## What this demonstrates\n\n- Implementation of a versioned MCP contract without a server-side SDK dependency.\n- Measured interoperability with three clients, explicit per-client coverage and inspectable messages.\n- Validation of negative cases, pagination and cancellation beyond successful initialization.\n\n## Published results\n\nThe published report records three clients exercising one local server. The custom client completed 13 scenarios and each SDK client completed eight. All three negotiated MCP 2025-06-18.\n\nThe recorded run uses Python 3.11.9 and Node 24.8.0 on an Intel Xeon W-3223. Every client traverses resource and tool pages, reads a note, checks results and errors, submits an invalid cursor and cancels an operation before sending another ping.\n\n### Recorded client runs\n\n| Client | Version | Checks | Messages | Protocol |\n| --- | --- | --- | --- | --- |\n| Custom reference | 0.1.0 | 13 | 34 | 2025-06-18 |\n| Official Python SDK | 2.3.0 | 8 | 23 | 2025-06-18 |\n| Official TypeScript SDK | 1.32.1 | 8 | 23 | 2025-06-18 |\n\nThese are fixed correctness scenarios for a stdio subset. The 13, 8 and 8 checks do not represent identical coverage or a client ranking. The result certifies neither full MCP conformance nor compatibility with graphical hosts.\n\nThe matrix identifies checks performed only by the custom client: pre-initialization errors, unknown methods and resources, invalid JSON and unknown cancellations. [Interoperability matrix and scope]().\n\nDocumented negative tests alter a page, the negotiated version, a duplicated response and a response to a cancelled request. The client report is not a statistical defect-detection measurement. [Interoperability matrix and scope]().\n\n## Reproduce\n\nThe server and raw client use the Python standard library. SDK reproduction requires Python 3.11.9, Node 24.8.0, npm 11.6.0 and the repository lock files. No models, accounts or paid APIs are required.\n\nThe first command runs the custom client against a real subprocess. Full reproduction installs pinned dependencies, verifies saved traces and writes a new run into an unused directory. Do not use Python -O: clients rely on contract assertions.\n\n### Run the custom client\n\n```\ngit clone https://github.com/lucioduran/mcp-contract-harness.git\ncd mcp-contract-harness\ngit checkout 44e77c071525127cd7e9ef5008b1b9f41e02ad07\npython -m clients.raw\n```\n\n### Reproduce all three clients\n\n```\npython -m venv .venv\n. .venv/bin/activate\npython -m pip install --require-hashes -r requirements-dev.lock\nnpm ci --ignore-scripts\npython -m clients.reproduce verify --output results/reference\npython -m clients.reproduce run --output build/reproduced\npython -m clients.reproduce verify --output build/reproduced\n```\n\n## Scope and limitations\n\n- HTTP, OAuth, subscriptions, prompts, sampling, elicitation, progress and resource templates are unsupported. This is not MCP certification.\n- ChatGPT, Claude Desktop, IDEs and other graphical hosts were not tested. SDK compatibility does not establish compatibility with those hosts.\n- Cancellation uses a deliberate 400 ms delay and a silence window of at least 600 ms. It does not prove all scheduling races or absence of leaks under load.\n- Limits are 64 KiB per message, 32 active requests and 10,000 identifiers per session. Performance, backpressure, exhaustive fuzzing and adversarial resource exhaustion were not evaluated.\n- Tool annotations are descriptive. The actual restriction comes from reading a compiled catalog; there is no security audit or sandbox for arbitrary tools.\n- Traces and hashes support consistency inspection. They do not authenticate who performed the measurement or constitute independent review.\n\n- [Model Context Protocol and tool integration]()\n\n## Sources and revision\n\nValues on this page come from the linked report. They are not live measurements. The report records the executed revision; the reviewed revision includes the subsequent publication of that report.\n\n- Reviewed revision: [` 44e77c071525127cd7e9ef5008b1b9f41e02ad07 `]()\n- Revision recorded by the experiment: [` 781f24d4188cae00d231460ccce04638f877f33c `]()\n- Report timestamp (UTC): 2026-10-21T21:33:32.334799+00:00\n- [Fictional note catalog]() SHA-256: ` 163b61136fba3454add6694d38492f6ee6b899c34864f4c10b971faaab720fdc `\n\n- [README]()\n- [Design and protocol sources]()\n- [MCP contract and errors]()\n- [Interoperability matrix and scope]()\n- [Client report]()\n- [Raw-client messages]()\n- [Python SDK messages]()\n- [TypeScript SDK messages]()\n- [Server implementation]()\n- [Fictional note catalog]()\n- [Wire evidence validator]()\n- [MIT license]()","headings":[{"level":1,"text":"MCP Contract Harness","url":"https://lucioduran.com/projects/mcp-contract-harness#title"},{"level":2,"text":"Problem and relevance to agents","url":"https://lucioduran.com/projects/mcp-contract-harness#problem"},{"level":2,"text":"Architecture","url":"https://lucioduran.com/projects/mcp-contract-harness#architecture"},{"level":2,"text":"What this demonstrates","url":"https://lucioduran.com/projects/mcp-contract-harness#demonstrates"},{"level":2,"text":"Published results","url":"https://lucioduran.com/projects/mcp-contract-harness#results"},{"level":3,"text":"Recorded client runs","url":"https://lucioduran.com/projects/mcp-contract-harness#results-interop"},{"level":2,"text":"Reproduce","url":"https://lucioduran.com/projects/mcp-contract-harness#reproduce"},{"level":3,"text":"Run the custom client","url":"https://lucioduran.com/projects/mcp-contract-harness#reproduce-raw"},{"level":3,"text":"Reproduce all three clients","url":"https://lucioduran.com/projects/mcp-contract-harness#reproduce-all"},{"level":2,"text":"Scope and limitations","url":"https://lucioduran.com/projects/mcp-contract-harness#scope"},{"level":2,"text":"Sources and revision","url":"https://lucioduran.com/projects/mcp-contract-harness#sources"}],"sections":[{"heading":"MCP Contract Harness","level":1,"url":"https://lucioduran.com/projects/mcp-contract-harness","content":"[Projects]() / MCP Contract Harness"},{"heading":"MCP Contract Harness","level":1,"url":"https://lucioduran.com/projects/mcp-contract-harness#title","content":"Read-only MCP server and independent clients for checking stdio negotiation, pagination, errors and cancellation, with actual wire messages and reproducible reports.\n\nAuthor: [Lucio Durán]() · Python 3.11.9 / Node 24.8.0 / MCP 2025-06-18 · License: [MIT]()\n\nPage published: 2026-10-21 · Page updated: 2026-10-21\n\n[Repository]() · [Client report]()"},{"heading":"Problem and relevance to agents","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#problem","content":"A successful initialize response does not establish that an integration handles a second page, cancellation or errors. This project checks those contracts against a specific MCP version and preserves exchanged messages.\n\nAgents need tool discovery, complete resource retrieval and a distinction between protocol and execution errors. This implementation exposes those boundaries through client checks and transport traces."},{"heading":"Architecture","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#architecture","content":"1. **Bounded server.** A Python standard-library server implements a subset of MCP 2025-06-18 over stdio JSON-RPC. It exposes three fictional notes and two read-only tools without filesystem or network access.\n2. **Three clients.** A custom Python client, official Python SDK 2.3.0 and official TypeScript SDK 1.32.1 connect to the same server. SDK clients negotiate from 2025-11-25 to the supported version.\n3. **Wire recording.** A proxy records actual lines from SDK clients before forwarding them. The custom client records its own transport. Traces preserve direction and JSON-RPC messages.\n4. **Contract validation.** An additional validator checks correlation, cursor chains, unanswered cancelled requests and a subsequent answered ping. Tool execution failures use isError; protocol failures use JSON-RPC errors.\n\n- [Design and protocol sources]()\n- [MCP contract and errors]()\n- [Server implementation]()\n- [Wire evidence validator]()"},{"heading":"What this demonstrates","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#demonstrates","content":"- Implementation of a versioned MCP contract without a server-side SDK dependency.\n- Measured interoperability with three clients, explicit per-client coverage and inspectable messages.\n- Validation of negative cases, pagination and cancellation beyond successful initialization."},{"heading":"Published results","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#results","content":"The published report records three clients exercising one local server. The custom client completed 13 scenarios and each SDK client completed eight. All three negotiated MCP 2025-06-18.\n\nThe recorded run uses Python 3.11.9 and Node 24.8.0 on an Intel Xeon W-3223. Every client traverses resource and tool pages, reads a note, checks results and errors, submits an invalid cursor and cancels an operation before sending another ping."},{"heading":"Recorded client runs","level":3,"url":"https://lucioduran.com/projects/mcp-contract-harness#results-interop","content":"| Client | Version | Checks | Messages | Protocol |\n| --- | --- | --- | --- | --- |\n| Custom reference | 0.1.0 | 13 | 34 | 2025-06-18 |\n| Official Python SDK | 2.3.0 | 8 | 23 | 2025-06-18 |\n| Official TypeScript SDK | 1.32.1 | 8 | 23 | 2025-06-18 |\n\nThese are fixed correctness scenarios for a stdio subset. The 13, 8 and 8 checks do not represent identical coverage or a client ranking. The result certifies neither full MCP conformance nor compatibility with graphical hosts.\n\nThe matrix identifies checks performed only by the custom client: pre-initialization errors, unknown methods and resources, invalid JSON and unknown cancellations. [Interoperability matrix and scope]().\n\nDocumented negative tests alter a page, the negotiated version, a duplicated response and a response to a cancelled request. The client report is not a statistical defect-detection measurement. [Interoperability matrix and scope]()."},{"heading":"Reproduce","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#reproduce","content":"The server and raw client use the Python standard library. SDK reproduction requires Python 3.11.9, Node 24.8.0, npm 11.6.0 and the repository lock files. No models, accounts or paid APIs are required.\n\nThe first command runs the custom client against a real subprocess. Full reproduction installs pinned dependencies, verifies saved traces and writes a new run into an unused directory. Do not use Python -O: clients rely on contract assertions."},{"heading":"Run the custom client","level":3,"url":"https://lucioduran.com/projects/mcp-contract-harness#reproduce-raw","content":"```\ngit clone https://github.com/lucioduran/mcp-contract-harness.git\ncd mcp-contract-harness\ngit checkout 44e77c071525127cd7e9ef5008b1b9f41e02ad07\npython -m clients.raw\n```"},{"heading":"Reproduce all three clients","level":3,"url":"https://lucioduran.com/projects/mcp-contract-harness#reproduce-all","content":"```\npython -m venv .venv\n. .venv/bin/activate\npython -m pip install --require-hashes -r requirements-dev.lock\nnpm ci --ignore-scripts\npython -m clients.reproduce verify --output results/reference\npython -m clients.reproduce run --output build/reproduced\npython -m clients.reproduce verify --output build/reproduced\n```"},{"heading":"Scope and limitations","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#scope","content":"- HTTP, OAuth, subscriptions, prompts, sampling, elicitation, progress and resource templates are unsupported. This is not MCP certification.\n- ChatGPT, Claude Desktop, IDEs and other graphical hosts were not tested. SDK compatibility does not establish compatibility with those hosts.\n- Cancellation uses a deliberate 400 ms delay and a silence window of at least 600 ms. It does not prove all scheduling races or absence of leaks under load.\n- Limits are 64 KiB per message, 32 active requests and 10,000 identifiers per session. Performance, backpressure, exhaustive fuzzing and adversarial resource exhaustion were not evaluated.\n- Tool annotations are descriptive. The actual restriction comes from reading a compiled catalog; there is no security audit or sandbox for arbitrary tools.\n- Traces and hashes support consistency inspection. They do not authenticate who performed the measurement or constitute independent review.\n\n- [Model Context Protocol and tool integration]()"},{"heading":"Sources and revision","level":2,"url":"https://lucioduran.com/projects/mcp-contract-harness#sources","content":"Values on this page come from the linked report. They are not live measurements. The report records the executed revision; the reviewed revision includes the subsequent publication of that report.\n\n- Reviewed revision: [` 44e77c071525127cd7e9ef5008b1b9f41e02ad07 `]()\n- Revision recorded by the experiment: [` 781f24d4188cae00d231460ccce04638f877f33c `]()\n- Report timestamp (UTC): 2026-10-21T21:33:32.334799+00:00\n- [Fictional note catalog]() SHA-256: ` 163b61136fba3454add6694d38492f6ee6b899c34864f4c10b971faaab720fdc `\n\n- [README]()\n- [Design and protocol sources]()\n- [MCP contract and errors]()\n- [Interoperability matrix and scope]()\n- [Client report]()\n- [Raw-client messages]()\n- [Python SDK messages]()\n- [TypeScript SDK messages]()\n- [Server implementation]()\n- [Fictional note catalog]()\n- [Wire evidence validator]()\n- [MIT license]()"}],"links":[{"text":"Projects","url":"https://lucioduran.com/projects"},{"text":"Lucio Durán","url":"https://lucioduran.com/"},{"text":"MIT","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/LICENSE"},{"text":"Repository","url":"https://github.com/lucioduran/mcp-contract-harness"},{"text":"Client report","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/report.json"},{"text":"Design and protocol sources","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/docs/design.md"},{"text":"MCP contract and errors","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/docs/contract.md"},{"text":"Server implementation","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/mcp_contract/server.py"},{"text":"Wire evidence validator","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/clients/evidence.py"},{"text":"Interoperability matrix and scope","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/docs/interoperability.md"},{"text":"Model Context Protocol and tool integration","url":"https://lucioduran.com/blog/model-context-protocol-mcp-ai-integration"},{"text":"44e77c071525127cd7e9ef5008b1b9f41e02ad07","url":"https://github.com/lucioduran/mcp-contract-harness/commit/44e77c071525127cd7e9ef5008b1b9f41e02ad07"},{"text":"781f24d4188cae00d231460ccce04638f877f33c","url":"https://github.com/lucioduran/mcp-contract-harness/commit/781f24d4188cae00d231460ccce04638f877f33c"},{"text":"Fictional note catalog","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/mcp_contract/catalog.py"},{"text":"README","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/README.md"},{"text":"Raw-client messages","url":"https://raw.githubusercontent.com/lucioduran/mcp-contract-harness/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/raw.jsonl"},{"text":"Python SDK messages","url":"https://raw.githubusercontent.com/lucioduran/mcp-contract-harness/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/python.jsonl"},{"text":"TypeScript SDK messages","url":"https://raw.githubusercontent.com/lucioduran/mcp-contract-harness/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/typescript.jsonl"},{"text":"MIT license","url":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/LICENSE"}],"structuredData":[{"@context":"https://schema.org","@graph":[{"@type":"WebPage","@id":"https://lucioduran.com/projects/mcp-contract-harness#page","url":"https://lucioduran.com/projects/mcp-contract-harness","name":"MCP Contract Harness","description":"Read-only MCP server and independent clients for checking stdio negotiation, pagination, errors and cancellation, with actual wire messages and reproducible reports.","inLanguage":"en","datePublished":"2026-10-21","dateModified":"2026-10-21","author":{"@id":"https://lucioduran.com/#person"},"mainEntity":{"@id":"https://lucioduran.com/projects/mcp-contract-harness#software"}},{"@type":"SoftwareSourceCode","@id":"https://lucioduran.com/projects/mcp-contract-harness#software","name":"MCP Contract Harness","description":"Read-only MCP server and independent clients for checking stdio negotiation, pagination, errors and cancellation, with actual wire messages and reproducible reports.","url":"https://lucioduran.com/projects/mcp-contract-harness","codeRepository":"https://github.com/lucioduran/mcp-contract-harness","programmingLanguage":"Python / JavaScript","runtimePlatform":"Python 3.11.9 / Node 24.8.0 / MCP 2025-06-18","license":"https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/LICENSE","version":"44e77c071525127cd7e9ef5008b1b9f41e02ad07","identifier":{"@type":"PropertyValue","propertyID":"git-commit","value":"44e77c071525127cd7e9ef5008b1b9f41e02ad07"},"author":{"@type":"Person","@id":"https://lucioduran.com/#person","name":"Lucio Durán","url":"https://lucioduran.com"},"isAccessibleForFree":true,"citation":["https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/README.md","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/docs/design.md","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/docs/contract.md","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/docs/interoperability.md","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/report.json","https://raw.githubusercontent.com/lucioduran/mcp-contract-harness/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/raw.jsonl","https://raw.githubusercontent.com/lucioduran/mcp-contract-harness/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/python.jsonl","https://raw.githubusercontent.com/lucioduran/mcp-contract-harness/44e77c071525127cd7e9ef5008b1b9f41e02ad07/results/reference/typescript.jsonl","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/mcp_contract/server.py","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/mcp_contract/catalog.py","https://github.com/lucioduran/mcp-contract-harness/blob/44e77c071525127cd7e9ef5008b1b9f41e02ad07/clients/evidence.py"]},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Projects","item":"https://lucioduran.com/projects"},{"@type":"ListItem","position":2,"name":"MCP Contract Harness","item":"https://lucioduran.com/projects/mcp-contract-harness"}]}]}],"contentHash":"002fca2a5ae4d85029be8ffac845078290790480e55b0e34b46436569d039ba7","provenance":{"method":"Deterministic serialization of the server-rendered main element","source":"https://lucioduran.com/projects/mcp-contract-harness","hashAlgorithm":"sha256","hashScope":"JSON document fields before contentHash and provenance","sourceHTMLBytes":48802,"contentBytes":9364}}