The moment more than one team or client depends on an MCP server you maintain, the question of how you change it without breaking someone else's integration stops being theoretical. A tool signature that changes shape, a parameter that becomes required, a response format that shifts, any of these can silently break a client that was working perfectly yesterday, and the failure often shows up as a confusing model error rather than an obvious crash.
Why MCP versioning is harder than API versioning
A REST API breaking change usually throws a clear HTTP error a developer can debug. An MCP tool that changes shape might instead cause the model to call it with the wrong parameters, get back an unexpected shape, and produce a subtly wrong answer without any error at all. That failure mode, silent and plausible-looking rather than loud and obvious, is exactly why versioning discipline matters more here than it might for a typical internal API.
Additive changes (new optional parameters, new tools): safe, don't require a version bump
Changing a parameter from optional to required: breaking, needs a new tool name or major version
Changing response shape or field names: breaking, silent failure risk is highest here
Renaming or removing a tool: breaking, always needs a deprecation window
A practical versioning approach that works
The simplest reliable pattern is semantic-style versioning applied to the server as a whole, with a clear changelog, plus keeping deprecated tools live and functioning (even if flagged as deprecated in their description) for a defined window, typically 60 to 90 days for an internal server, before removing them. Never silently change what an existing tool name does, if the behaviour needs to change meaningfully, ship it as a new tool name and deprecate the old one, rather than mutating the contract underneath existing callers.
What a Sydney dev team learned the hard way
A Sydney logistics software vendor maintaining an internal MCP server for their own ops team changed a tool's date parameter from an optional filter to a required one during a routine cleanup, without a version bump or changelog note. Three internal automations that called the tool without that parameter started failing silently, returning empty result sets the model then confidently summarised as 'no orders today,' for four days before anyone noticed the ops dashboard looked wrong. The fix took twenty minutes. Finding it took four days, worth roughly $1,200 in wasted investigation time at a senior engineer's rate, entirely avoidable with a changelog entry and a heads-up in the team channel.
A pre-release checklist worth keeping
Run the full existing test suite of client calls against the new server version before shipping
Diff the tool schema against the previous version and flag anything beyond a pure addition
Keep deprecated tools live and working, not just documented as deprecated, for the agreed window
Notify every known caller directly, don't rely on a changelog nobody reads
Documenting the contract, not just the code
A short, plainly written changelog that any caller can scan in thirty seconds does more for preventing breakage than an elaborate versioning scheme nobody reads. Keep one file, dated entries, plain language: what changed, whether it's breaking, what callers need to do. For an internal server with a handful of known callers, a message in the team channel alongside that changelog entry closes the loop faster than hoping someone checks documentation before their automation breaks.
Testing deserves the same discipline as any other production change. Before shipping a schema change, run every known caller's actual call pattern against the new version in a staging environment, not just a manual spot-check of the new tool in isolation. The Sydney logistics example above would have been caught in under a minute by running the existing internal automations against the updated server before deploying it, the kind of check that's cheap to build once and easy to skip under time pressure, which is exactly when it matters most.
For Australian businesses building MCP servers that external clients or partners depend on, a written compatibility policy, even a simple one, stating how long deprecated tools stay live and how breaking changes get communicated, is worth having in writing before the first breaking change happens rather than improvised in the middle of an incident. It costs an hour to write and saves considerably more than that the first time it's needed.
None of this needs to be heavyweight. For a small internal server with two or three callers, a shared changelog document and a five-minute heads-up message before a breaking change ships covers most of the risk. The discipline that matters is treating every schema change as a decision, not an afterthought, because the cost of a silent MCP failure tends to be discovered much later than the cost of a loud one.
