Operations & Gateways
MCP Server Versioning: Protocol and Tool Contract Changes
By MCP Beast·
MCP server versioning involves three different contracts: the MCP protocol revision a request uses, the server software release you deploy, and the behavior of the tools or other capabilities that server exposes. Record all three. A server can support the same protocol revision while changing a tool's required arguments, authorization rules or result shape.
For operators, the useful question is whether a specific client, server build and capability contract still work together for an approved task. A single “latest” label cannot answer that question. Build a small compatibility record, test representative operations, and retain enough evidence to distinguish a protocol mismatch from an application change.
Separate the version identifiers
The MCP versioning specification for 2026-07-28 describes protocol compatibility. Semantic Versioning 2.0.0 describes a release convention for software with a declared public API. These are different mechanisms; MCP does not make every server publisher follow Semantic Versioning.
| Identifier | What it describes | What it does not prove |
|---|---|---|
| MCP protocol revision | The message and transport rules being used | That a particular tool preserves its meaning |
| Server release or artifact digest | The deployed implementation | That every connected upstream stayed unchanged |
| Tool schema and documented behavior | The operation an agent may invoke | That credentials grant the same access in every environment |
| Client release and configuration | The host's implementation and enabled features | Compatibility with every server claiming MCP support |
Keep the artifact identifier independently of its friendly version label. A rollback needs the actual previous build, configuration and dependency constraints, not a screenshot saying that yesterday's release was stable. If you consume a hosted server, ask what change history and compatibility guarantees the provider publishes instead of assuming you control its deployment schedule.
Use the correct protocol-era compatibility check
MCP 2026-07-28 uses per-request protocol versions rather than an initialization handshake. Servers expose server/discover; clients may use it as a preflight check. An unsupported-version response can include supported and requested versions, allowing a client to choose a mutually supported version or report that none is available. Supporting a protocol era is still an implementation claim that needs testing with the actual client.
Older 2025-11-25 and earlier deployments use a different lifecycle. A migration record should explicitly say whether the client and server support the modern era, the legacy era, or both. Do not diagnose a legacy initialization failure by assuming a modern per-request flow, or copy an old session-based tutorial into a current deployment checklist.
Optional extensions need their own compatibility decision. A mutually supported core revision does not mean both parties implement every extension. Record whether the workflow has a supported fallback or should reject the operation when an extension is unavailable. The transport selection guide helps keep that protocol decision separate from where the server process runs.
Review a tool change as a public contract change
Consider a fictional document-search tool whose limit argument was optional and then becomes required. These are structural JSON Schema excerpts, not complete MCP messages or a real product's schema:
{
"before": {
"type": "object",
"properties": {
"query": { "type": "string" },
"limit": { "type": "integer", "minimum": 1 }
},
"required": ["query"]
},
"after": {
"type": "object",
"properties": {
"query": { "type": "string" },
"limit": { "type": "integer", "minimum": 1 }
},
"required": ["query", "limit"]
}
}
A caller that previously supplied only query now fails validation. The unchanged tool name and protocol revision do not make that compatible. Under a publisher's declared SemVer contract, an incompatible public API change calls for a major release. That convention is useful only when the publisher defines the public API and follows it; a consumer still needs evidence.
Classify the changed consumer assumption before choosing its acceptance test. This table guides review; the publisher's declared compatibility and release policy determines the release label and required approval.
| Change | Affected consumer assumption | Smallest useful acceptance test | Release / approval decision under publisher policy |
|---|---|---|---|
| New required input | Previously valid calls may omit the field | Replay a representative old call without it, then the migrated call with it | Decide whether migration or a compatibility period is required; classify the demonstrated incompatibility |
| Narrower enum | A previously accepted value remains usable | Submit a removed value and a retained value through the affected workflow | Identify consumers of removed values and approve their replacement path before rollout |
| Broader sensitive output | The response stays within the approved data boundary | Use a synthetic sensitive field and verify output under permitted and restricted identities | Data/access owner reviews the expanded disclosure even if parsing still succeeds |
| Changed default | Omitting an optional argument preserves behavior | Compare the same omitted-argument call and an explicit-value control | Decide whether the changed behavior requires migration or renewed approval |
| Description-only selection change | The same task selects the intended tool | Run the representative ambiguous task with old and new descriptions under the same catalog/model conditions | Assess observed selection effects; prose edits are not automatically breaking or harmless |
| Removed tool | Saved consumers can still invoke the operation | Exercise a known dependent workflow and its proposed replacement or clear unsupported path | Approve migration/retirement conditions before accepting removal |
| Added tool | Discovery and policy still expose only intended capabilities | Check selection alongside similar tools and denied invocation by a restricted identity | Review discovery and permissions; adding a tool does not itself authorize its use |
The MCP tool-schema reviewer can provide a structural first pass on a sanitized definition. It cannot establish behavioral compatibility, correct selection, permissions or downstream effects. Optional additions can still change defaults or consumer behavior; test the affected assumption rather than classifying safety from the field's optional flag alone. Review pagination and error meanings when they change, too.
Capture the catalog under a known identity
The current tools specification allows tool sets to change and to vary by authorization. Tool names are unique within a server, not globally across every server. When comparing catalogs, preserve the server identity and the authorization context alongside each name.
Collect all pages of the tool list using the same approved identity and configuration. Store a redacted baseline containing names, descriptions, input schemas, output schemas where supplied, and annotations. Do not store credentials with the snapshot. A missing tool may mean access changed, pagination was incomplete or an upstream was unavailable; it is not automatically a release deletion.
Classify differences before accepting the new baseline. An added tool needs a discovery and policy review. A removed or renamed tool can break saved workflows. A schema tightening needs negative tests against previously valid inputs. A newly available write operation needs a separate authorization and approval check. For a fleet-level inventory, use the owner and environment record described in MCP server management.
Build a small compatibility matrix
Choose rows from real supported workflows, not every theoretical permutation. Include the main client release, the candidate server artifact, the current production artifact and any legacy combination you explicitly promise to support. For each row, record the protocol revision and the identity used to test it.
A useful acceptance run checks discovery, one valid read, one intentionally invalid argument set and one denied operation. For writes, use a safe test destination and verify the resulting state. Confirm that structured results still match their documented shape and that errors remain useful to the caller. If the tool wraps an external service, record that service's relevant version or endpoint configuration too.
Keep test output bounded and redacted. Include the operation name, artifact identifiers, pass or fail result, and a correlation reference that an operator can follow. The logging guide explains how to retain useful diagnostic evidence without copying full arguments and credentials into every record.
Roll out and roll back deliberately
Promote a candidate only after its compatibility record is complete. Start with a limited, representative workload, compare errors and outcomes, then expand according to your deployment process. A lower error rate is not enough if an operation now returns incomplete data or applies a different permission boundary.
Before rollout, identify the previous artifact and configuration, who can restore them, and how to verify restoration. Separate software rollback from data recovery: redeploying an older server does not undo messages sent, records deleted or migrations already applied. For an uncertain write outcome, inspect the destination before repeating it; the timeout diagnosis workflow covers this ambiguity.
Finally, record the accepted catalog baseline and the reason for the change. That turns the next upgrade into a comparison against known behavior instead of another attempt to infer what “latest” meant.
Frequently Asked Questions
Is an MCP protocol version the same as a server version?
No. The protocol revision defines communication rules, while a server release identifies an implementation. Tool behavior can change without changing the protocol revision.
Does MCP require servers to use Semantic Versioning?
No. Semantic Versioning is a separate release convention. Check the publisher's declared compatibility policy and test the public capability contracts you depend on.
Can a tool change while keeping the same name?
Yes. Arguments, results, permissions or behavior can change under the same name. Compare a catalog captured under a known identity and test representative operations.
Does rolling back a server undo its tool calls?
No. Restoring software does not automatically reverse external side effects or data changes. Verify the destination state and use an explicit recovery procedure when needed.
When evaluating MCP Beast for a changing server catalog, bring one representative client workflow and its before-and-after schemas. Use those artifacts to review discovery, routing and the evidence needed to accept an upgrade.