Version a tool contract without breaking callers

Agents and clients can fail silently when a tool renames fields or changes an enum. Classify compatibility from actual caller expectations.

Compare three versions

The MCP contract lab creates authored schemas.

from mcp_cases import contract_version_case

result = contract_version_case()
assert result["versions"] == ["1.0", "1.1", "2.0"]
assert result["v1_to_v11_additive"] is True
assert result["v1_to_v2_breaking"] is True

V1.1 adds optional group_by and response source_version; v2 replaces required fields. The check uses sets, not an MCP runtime.

Define compatibility policy

Adding optional input or output may be compatible only if clients tolerate unknown fields. Renames, removed fields, changed types/units or enum meaning are breaking. Semantic changes can break callers even when JSON stays identical.

Publish version and deprecation dates, keep contract tests for supported callers and expose stable errors. Run both versions during migration where justified; do not silently route v1 names to new semantics.

Test recorded interactions

Replay valid/invalid calls from each supported version. Verify output parsing, authorization and business invariants. Record which host/client versions were tested.

The Generative & Agentic AI course connects tool versioning to schema drift and release review.

Exercise

Evolve a tool through one additive and one breaking change. Build compatibility tests, a migration guide and a removal gate based on observed approved clients.

Continue learning

This article is part of the MCP and integration contracts sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Avoid token passthrough in delegated integrations.
• Continue with Handle pagination in an AI-facing data tool.

Reference: Semantic Versioning.