versioning MCP tool schemas without breaking clients
Explains how to evolve MCP tool schemas safely: additive changes, deprecation windows, and version signals clients can rely on. Use when an existing MCP server needs new fields or changed behavior; not for pre-release servers with no users.
TL;DR
Breaking a tool schema breaks every client at once; additive evolution avoids that. A deprecation window with clear dates keeps the ecosystem moving without surprises. Applies to MCP servers with existing users.
The query
versioning MCP tool schemas without breaking clientsUse this when
- An existing MCP server needs schema changes.
- Clients depend on the current tool shapes.
- You need evolution without breakage.
Not for
- The server is pre-release with no external users (just change the schema).
- You are designing the schema for the first time (design it well instead of versioning around it).
- The change is a pure bug fix with no schema impact (ship it; no versioning needed).
Steps
- Make the change additive: new optional fields, never renamed or removed required fields.
Expected output: A new schema version that old clients still parse.
- Announce the deprecation of the old shape with a removal date at least 30 days out.
Expected output: A dated deprecation notice clients can plan around.
- Support both shapes during the window and log which clients still use the old one.
Expected output: Telemetry showing old-shape usage trending to zero.
- Remove the old shape after the window and confirm no client errors spike.
Expected output: A clean removal with no client breakage.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_TNmsGl6cvDG2TNYxUzcjnQ
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.