What must be versioned in an MCP client-server contract?

Ask which component’s version changed

“We upgraded MCP” is insufficient for a release decision. It might mean a new protocol revision, a client SDK update, a server image, or a tool description change. Those changes have different consumers and can fail independently.

Maintain a short component inventory with owners and verified sources of version information. Deployment supplies the server artifact; the host records the catalog used for selection; policy supplies the decision revision. Preserve a peer’s self-reported build as a claim when it cannot be tied to an admitted artifact.

Separate wire compatibility from meaning

The 2026-07-28 transport specification changes the protocol’s session model and request metadata requirements. Mixing its rules with a legacy implementation can fail before tool logic executes.

After the wire works, application compatibility remains. A caller can send valid JSON and receive a schema-valid result whose units, absence semantics, ordering, or scope changed. Record those promises in the tool contract and test the direction that matters: old caller to new server is not the same claim as new caller to old server.

An optional field changes the meaning of a missing price

Take a hypothetical inventory tool returning price and currency. Server revision 8 introduces an optional include_estimates input and a new price_status result. A new host recognizes estimated; an old host ignores the field and displays every numeric price as confirmed.

The input addition is harmless only if its default preserves the old result meaning. The team decides that callers omitting include_estimates will still receive confirmed prices or explicit absence. Estimated prices require an admitted new host and a distinct result contract.

Both host generations can now coexist, but only under recorded constraints. Merely accepting the old request shape would have missed the user-visible incompatibility.

Record combinations and their permitted behavior

Use a matrix like this for the affected contract. The labels and outcomes are hypothetical and should be replaced with tested local versions.

Consumer	Producer	Contract condition	Support decision	Required evidence
Host 4, catalog 21	Server 7, confirmed prices	Existing behavior	Supported baseline	Known-price and absent-price tests
Host 4, catalog 21	Server 8, estimates omitted	Confirmed-only default retained	Supported with constraint	Old rendering and default tests
Host 5, catalog 22	Server 8, estimates requested	Status displayed explicitly	Supported for pilot	Estimate labeling and user review
Host 5, catalog 22	Server 7	New input unavailable	Unsupported	Explicit rejection check
Unidentified host	Either server	Result interpretation unknown	Untested	Identify consumer before admission

Attach protocol revision, SDK builds, artifact digests, policy revision, backend API, test date, and owner to the matrix. The compact rows summarize a claim; they do not replace the evidence supporting it.

Use version labels to communicate a defined promise

Semantic Versioning is useful when a component declares its public API and follows the convention. Establish which behaviors belong in that API, including defaults and result meaning. Do not assume that a protocol date, registry record, model label, and container tag share one ordering scheme.

Compatibility review should include descriptions when models consume them to select tools. A wording change can redirect calls without changing a parser. Evaluate those selection consequences against a recorded task set rather than attempting to infer them from the release number.

Retest the boundary implicated by the change

Organize checks around changed promises: wire handling, omitted inputs, result interpretation, permitted fields, cache reuse, and recognizable failures. Keep representative old clients until their support period ends. Include a test where the new host accidentally reaches an old server and must fail clearly.

For stochastic selection, record the model and host configuration and compare repeated representative tasks. A deterministic schema test and a selection evaluation establish different parts of the same support claim.

Expire support deliberately

Give each constrained row an owner and removal condition. Observe which real consumers still use it, including infrequent workflows, before retiring compatibility code. If a combination was never exercised, preserve that uncertainty instead of converting “no reported failures” into a pass.

The matrix answers which combinations are permitted. Rolling out with stale catalogs addresses how to move production from one permitted combination to another.