MCP version compatibility: test the version you support instead of echoing a date

MCP compatibility means implementing and testing a revision, not returning whatever date a client supplied. Keep protocol revision, SDK package version and host build as three separate fields. Test accepted revisions, unsupported revisions and inconsistent request metadata. A server may support both legacy initialization and the July 2026 request-metadata lifecycle, but each promise needs an actual implementation path.

Put the supported set in the release record

Start with a small table maintained alongside compatibility fixtures. For every revision, record transport, lifecycle, advertised capabilities and known host coverage. An SDK release number alone does not tell a reader which revision the application enabled. A host can also cache schemas or use an older adapter. Preserve the resolved versions from the lockfile and the observed request sequence, not only a package range from a manifest.

The July 2026 versioning specification defines per-request declarations and an unsupported-version error with the supported set. Its HTTP binding also requires matching version metadata and headers. Legacy clients establish their session through initialization under their supported revision; they should not be rejected merely for following that older agreed lifecycle.

MCP versioning: supported revisions and dual-era behavior

MCP HTTP metadata validation and compatibility rules

Four synthetic cases that expose different mistakes

Our isolated policy model declares support for 2026-07-28 and 2025-11-25. A request with an unknown matching date returns an unsupported-version classification, including the supported values. A header/body mismatch returns a different classification. The model also retains an accepted legacy entry. It does not implement a complete legacy handshake, so that accepted row is an inventory decision rather than proof of legacy host conformance.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2026-07-28", "2025-11-25"],
      "requested": "1900-01-01"
    }
  }
}

The example uses the current documented modern error shape. Do not send that shape as an improvised replacement for all errors in every historical revision. Route the request through the era and binding it actually uses. The client should inspect the response, select a mutually supported version where possible and avoid an unbounded negotiation loop. A recognized modern validation failure is evidence to correct the modern request, not permission to downgrade silently.

Version agreement is only the first acceptance gate

After selecting a revision, run meaningful operations: complete paginated discovery, call a permitted read tool, reject an unauthorized record and classify a tool failure. If your integration uses resources or subscriptions, test those mechanisms as well. A request that echoes a date and returns one tool list does not exercise these contracts. Keep fixture names tied to behavior so a future package upgrade reveals what changed.

Build a separate application-schema matrix. A compatible transport can still expose a renamed required argument or a new response enum that an older consumer cannot interpret. Conversely, an unchanged tool schema does not prove that new mirrored-header requirements or lifecycle semantics are implemented. Keeping these matrices separate gives release reviewers a precise reason to accept or reject an upgrade.

Bound the compatibility statement

A defensible release note says which server build was tested with which host builds, revisions and transport, and lists unsupported optional features. It does not say every MCP client works. Include denial and disconnect behavior because they frequently involve paths that a happy-path read misses. Re-run only the affected matrix after a relevant code or dependency change, preserving the earlier artifact for comparison.

The saved local result demonstrates the four classification decisions and their expected status categories. It is intentionally smaller than an SDK test suite. Use it to review policy before integrating the real transport, then add a wire-level capture with synthetic requests. Retire a supported revision through an explicit client migration plan; a new specification date by itself does not invalidate older supported behavior.

MCP tool schema versioning

Evaluate the tool action, not just the answer.

Bring one tool workflow, supported hosts and a sanitized failure trace for a scoped AI integration review.

AptixLabs ai agent development