C.W.K.
Stream
Lesson 04 of 04 · published

Compatibility Matrix

~22 min · matrix, testing, ci, interop

Level 0Curious Reader
0 XP0/48 lessons0/14 achievements
0/100 XP to next level100 XP to go0% complete

If you ship an MCP server (or client) that anyone else uses, you owe a compatibility matrix: a published list of which protocol revisions × which clients × which transports you have actually tested against. The matrix is two columns of honesty: known-good, and explicitly known-untested. Both reduce support pain.

The cheapest matrix that adds value: three revisions deep (current and two prior), the three most-used clients (Claude Desktop, Cursor, your own host if any), and both transports (stdio, Streamable HTTP). For each cell, a CI job that boots the server and runs an end-to-end smoke test (initialize → list tools → call one tool → shutdown). Failing cells are bugs; passing cells are commitments.

The matrix also gives you a place to publish caveats. "Streamable HTTP works under Cloudflare Workers, but you must enable websockets" is exactly the kind of note that saves the next user a day of debugging. The matrix is your README's most useful section.

Code

Sample compatibility matrix in your README·markdown
| Server v1.4.0          | 2025-03-26 | 2025-06-18 | 2025-11-25 |
|------------------------|:----------:|:----------:|:----------:|
| Claude Desktop (stdio) | ✅         | ✅         | ✅         |
| Cursor (stdio)         | ✅         | ✅         | ✅         |
| Custom host (HTTP)     | ✅         | ✅         | ✅         |
| Bare HTTP+SSE          | ✅         | ⚠️ deprecated | ❌      |

Notes:
- Async tasks: only on 2025-11-25 hosts (auto-falls-back to sync otherwise).
- Sampling: requires host to advertise `sampling` capability.
CI smoke test pinned to a revision·yaml
matrix:
  protocol_version: ["2025-11-25", "2025-06-18", "2025-03-26"]
  transport: ["stdio", "streamable-http"]
steps:
  - run: pytest tests/smoke.py --protocol $PROTOCOL_VERSION --transport $TRANSPORT

External links

Exercise

For one server you ship, draft a 3×3×2 compatibility matrix in the README. Run the smoke test in each cell you can. Mark untested cells. Push the README. The exercise reveals which cells you really know and which were optimism.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.