how to deprecate an MCP tool gracefully
Lays out a graceful MCP tool deprecation: announcing the replacement, supporting both during a window, and removing the old tool without breaking clients. Use when replacing or removing a tool clients depend on; not for pre-release tools with no users.
TL;DR
Clients hard-code tool names; removing one without warning breaks them silently. A deprecation window with a named replacement is the professional path. Applies to MCP servers with existing client usage.
The query
how to deprecate an MCP tool gracefullyUse this when
- A tool clients use needs replacing or removal.
- You can offer a named replacement.
- You want zero-surprise migration.
Not for
- The tool is pre-release with no users (just remove it).
- Nobody uses the tool (check telemetry first; unused tools can go quietly).
- You are renaming for style reasons only (add an alias instead of deprecating).
Steps
- Announce the deprecation: name the tool, the replacement, and the removal date.
Expected output: A dated notice clients can plan around.
- Keep the old tool working during the window, returning a deprecation note in its output.
Expected output: Clients keep working while being nudged to migrate.
- Track old-tool usage and personally nudge the heaviest users before the deadline.
Expected output: Usage trending to zero with no surprised stragglers.
- Remove the tool on the announced date and monitor client error rates.
Expected output: A clean removal with no error spike.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_2aWIcB1T1DdWnGcnHb1r7w
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.