## 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

```text
versioning MCP tool schemas without breaking clients
```

## Use 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

1. Make the change additive: new optional fields, never renamed or removed required fields.
   Expected output: A new schema version that old clients still parse.
2. 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.
3. 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.
4. 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