MCP Tool Versioning and Deprecated Tools
Quick answer: MCP does not define a standard version or deprecated field for a tool, so you evolve tools by convention: keep breaking changes under a new name (such as search_v2), mark the old tool as deprecated in its d
Quick answer: MCP does not define a standard version or deprecated field for a tool, so you evolve tools by convention: keep breaking changes under a new name (such as search_v2), mark the old tool as deprecated in its description, keep it working with a warning, and remove it only after a fixed sunset window. Additive changes can stay on the same name; anything that changes the input shape or the meaning of output needs a new version.
Why tools need versioning
An MCP server keeps changing after clients connect: a tool gains a parameter, a field changes type, or a value changes unit. Saved agents and prompts still call the old name, and a silent change can produce wrong results with no signal. Versioning makes the change visible so callers move on their own schedule rather than getting a new contract on an old name.
What the protocol gives you
A tool returned from tools/list carries a name, an optional description, and an input schema. There is no required semantic-version field and no boolean that marks a tool as deprecated; the optional tool annotations cover hints such as read-only or idempotent, not retirement. That means versioning and deprecation are conventions you enforce, not fields the host will act on automatically. Treat the tool name as the stable contract the model relies on.
How teams version a tool
| Approach | What it looks like | When to use it |
|---|---|---|
| Versioned name |
search_v1, search_v2
|
Any breaking change; the model sees a distinct tool |
| Description note | Version stated in the description | Communicating revision without a new name |
| Schema field | Optional version input parameter |
Caller needs to select behavior explicitly |
| Server metadata | Server version in the init handshake | Tracking the whole server, not one tool |
The versioned name is the most reliable lever because the model chooses tools primarily by name and description. A new name is a new tool, so an old agent that named search_v1 does not silently get v2 behavior.
How to deprecate without breaking callers
Do not delete the old tool on the day the new one ships. Saved prompts and long-running agents still reference the old name, and a missing tool becomes a hard failure. First, prefix the old description with a clear DEPRECATED note and name the replacement. Keep the tool functioning but return a warning alongside its result so the model is nudged toward the new one. Publish a sunset date, then remove the name only after that window; logging calls to the old tool shows whether anything still depends on it.
Compatible versus breaking changes
| Change | Same name or new | Reason |
|---|---|---|
| Add optional input parameter | Same | Old callers omit it and still work |
| Add a response field | Same | Callers that ignore unknown fields are fine |
| Change a field type or unit | New | Old parsing and assumptions break |
| Remove or rename a parameter | New | Existing calls fail or misbehave |
| Change what a value means | New | Correct output silently becomes wrong |
The last row is the dangerous one: a field that keeps its name but changes meaning passes every schema check and still breaks reasoning. To confirm a v2 output really differs from v1, send both requests side by side and compare the schemas; Powerduck keeps the two responses visible so the difference is evidence rather than a guess.
What the model actually sees
The model reads the tool name and description at selection time; it does not run a version resolver, and it is not guaranteed to honor a deprecation note the way a compiled client would honor a typed header. A warning in the result helps, but the host cannot assume every call migrates by the sunset date. That is why the old name must stay functional through the window rather than throwing.
Honest limits
These patterns are conventions, not protocol guarantees, and different hosts may surface descriptions differently. A deprecation note does not prove the model switches tools, and naming alone does not prevent collisions across many servers, which needs separate prefixing. Registry-level lifecycle, where a published package is listed, retired, or replaced across an ecosystem, is a separate concern from versioning a tool inside your own server. Importing or connecting a server also does not deploy a backend, and the protocol does not validate that a new tool's behavior is correct.
Frequently asked questions
Does MCP have a built-in tool version field? No. A tool exposes name, description, and input schema; teams add versioning through naming and descriptions.
How do I mark a tool as deprecated? Add a clear DEPRECATED note to its description, name the replacement, and return a warning while keeping the tool working until a sunset date.
Can I change an existing tool's input schema in place? Only for additive, optional changes. Anything that breaks old callers should ship under a new versioned name.
When can I remove the old tool? After the published sunset window, once logs show no remaining calls to the old name.
The bottom line
Because MCP leaves versioning and deprecation to you, use the tool name as the contract: ship breaking changes under a new versioned name, keep the old one alive with a visible warning and a fixed sunset, and reserve same-name edits for purely additive changes. For more on building and operating these servers, see the MCP server guide hub.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.