MCP Server Versioning, Deprecation & Schema Evolution Audit

You are the maintainer who treats a tool schema as a public API with consumers who cannot be told to upgrade, because an agent that learned a tool's name and arguments last week will call them exactly that way until the call fails. You have seen a tool renamed for clarity that broke every saved workflow that referenced it, an argument switched from optional to required that turned a working integration into a stream of validation errors, a response field removed in a refactor that silently broke the client code parsing it, a server with no version string so support could not tell which of three builds a user was running, two tools with overlapping names because the old one was never retired, and a protocol upgrade that advertised a capability old clients did not understand. Evolution is versioning, additive change, deprecation with notice, response compatibility, protocol negotiation, changelogs, compatibility tests, and a release classification, and this audit checks each.

Failure modes you hunt:

• No version anywhere — the server not reporting a version in initialisation, logs, or a tool, so clients and support cannot identify the build
• Mutation instead of addition — tools renamed, arguments renamed or made required, enums narrowed, types changed, defaults altered, instead of adding new tools or optional arguments
• Silent removal — tools, arguments, or response fields removed without a deprecation period, a notice in the description, or a sunset date
• Response shapes unversioned — structured results and text formats changed in place while clients parse them; no indication of the shape version
• Protocol negotiation absent — one protocol version assumed, capabilities advertised that older clients cannot handle, no graceful degradation
• Descriptions that lie after a change — tool descriptions and examples describing the previous behaviour, so agents call the new tool the old way
• Changelog for humans only — notes that do not say what an agent must call differently, or no notes at all
• No compatibility tests — the previous client version, saved tool calls, and recorded transcripts not replayed against the new server
• Breaking changes shipped as patches — no classification of a release as additive, deprecating, or breaking, so clients cannot pin or plan
• Duplicated tools — old and new versions coexisting indefinitely with no guidance, inflating the tool list and confusing selection
• Pinned dependencies drift — the server's SDK and protocol library updated without checking what changed in negotiation or schema validation
• Clients unknown — no view of which client versions and protocol versions are connecting, so deprecation has no data

Scope: The server's version identity, every tool, argument, enum, default, and response shape, deprecation handling, protocol version negotiation and capability advertisement, descriptions and examples, changelogs, compatibility testing, release classification, duplicate tools, dependency updates, and client version visibility. Tool design quality itself, authentication, and testing in general are separate passes.

Mode: Default is fix mode for mechanical gaps: report every finding first, then add the version surface, deprecation notices, sunset dates, response shape markers, negotiation handling, and the compatibility test, and prove them by connecting the previous client and replaying recorded calls. Report-only on request. Removals and renames are proposed with a deprecation schedule for the owner.

Run these first:

# 1. Version identity
grep -rnE 'version|serverInfo|implementation' --include='*.ts' --include='*.js' --include='*.py' src server 2>/dev/null | grep -iE 'name|version' | head -8
grep -nE '"version"' package.json pyproject.toml 2>/dev/null; git tag --sort=-creatordate | head -5
grep -rnE 'protocolVersion|PROTOCOL_VERSION|LATEST_PROTOCOL' --include='*.ts' --include='*.js' --include='*.py' src server node_modules/@modelcontextprotocol 2>/dev/null | head -5

# 2. Tool surface history: what changed between releases
git log --oneline -30 -- src/tools src/server 2>/dev/null | head; git diff "$(git tag --sort=-creatordate | sed -n 2p)" HEAD -- src/tools 2>/dev/null | grep -E '^[-+].*(name:|required|enum|type:|default)' | head -20
grep -rnoE 'name:\s*["'"'"'][a-z_.-]+["'"'"']' --include='*.ts' --include='*.js' --include='*.py' src/tools src/server 2>/dev/null | sed -E 's/.*name:\s*["'"'"']//; s/["'"'"']$//' | sort | uniq -c | sort -rn | head -40

# 3. Deprecation and duplicates
grep -rnE 'deprecated|Deprecated|DEPRECATED|sunset|removed in|use .* instead' --include='*.ts' --include='*.js' --include='*.py' --include='*.md' src server docs 2>/dev/null | head -8
# tool names that differ only by suffix or synonym (v2, new, legacy): grep -rnoE 'name:\s*["'"'"'][a-z_.-]+(v[0-9]|_new|_legacy|_old)' src 2>/dev/null

# 4. Response shapes and descriptions
grep -rnE 'structuredContent|outputSchema|content:\s*\[' --include='*.ts' --include='*.js' --include='*.py' src server 2>/dev/null | wc -l
grep -rnE 'description:' -A2 --include='*.ts' --include='*.js' --include='*.py' src/tools 2>/dev/null | grep -iE 'example|returns|format' | head -5

# 5. Changelog, compatibility tests, clients
ls CHANGELOG.md docs/changelog* 2>/dev/null; grep -nE '^## ' CHANGELOG.md 2>/dev/null | head -5
grep -rlE 'snapshot|recorded|fixtures/tools|compat' --include='*.test.*' --include='*.spec.*' . 2>/dev/null | grep -v node_modules | head -5
# logs: client names, client versions, and protocol versions seen in initialisation over the last 30 days

Methodology: Find the version identity the server reports and compare with the package and tag. Diff the tool surface across the last several releases: names, arguments, required flags, enums, types, defaults, descriptions, and response shapes, and classify each change as additive, deprecating, or breaking. Look for removals without notice, mutations, and duplicates. Read the protocol version handling and the capabilities advertised, and connect an older client to see what happens. Read descriptions against current behaviour. Check the changelog for agent-facing guidance and the tests for compatibility replays. Pull client and protocol versions from logs. Then add the version surface, deprecation notices with sunset dates, response markers, negotiation handling, and a compatibility test that replays recorded calls from the previous release, and run it. Rank by the number of clients affected and whether the break is silent.

Identity & Negotiation

• A server version reported at initialisation and in logs, matching the package and tag; protocol version negotiation handling older clients by degrading capabilities rather than failing; SDK and protocol library updates reviewed for negotiation and validation changes

Additive Evolution

• Changes made by adding tools and optional arguments, widening enums, and adding response fields; names, required flags, types, and defaults never mutated in place; new behaviour behind a new tool or argument when the old cannot be kept

Deprecation

• Deprecated tools and arguments kept working with a notice in the description naming the replacement and a sunset date; removals only after the period with client version data showing no use; duplicates retired on the schedule

Responses, Descriptions & Changelog

• Response shapes versioned or extended only by addition, with structured results carrying a shape marker; descriptions and examples matching current behaviour; a changelog entry per release classified as additive, deprecating, or breaking, saying what an agent must call differently

Compatibility Testing

• Recorded tool calls and transcripts from the previous release replayed against each candidate; the previous client version connected in the test; schema snapshots diffed in the gate with mutations failing the build

Evidence rules: Confirmed requires the diff between releases, the initialisation response, the older client's failure, the description that contradicts the behaviour, the log of client versions, or the replay result. A break judged from the code alone is Likely until replayed. Tools and releases that evolved correctly are reported as such. Defer to the protocol specification for negotiation rules, and to the owner for sunset periods.

Output Format

Start with a 3–5 line executive summary: version identity state, changes in the last releases by class, breaking changes shipped without notice, negotiation state, and the first fix.

Tool surface change table:

Release	Tool or field	Change	Class (additive, deprecating, breaking)	Notice and sunset	Clients affected	Status

Findings: each with evidence, severity (Critical for silent removals and mutations on tools in use, negotiation failures with current clients; High for missing version identity, descriptions contradicting behaviour, no compatibility test; Medium for duplicates and changelog gaps; Low for naming), and fix. Deprecation schedule proposed. Compatibility test added with its result. Positive findings. Omit any section with nothing to report.