---
title: How do you deprecate an MCP server without breaking agents?
url: https://opencontroller.lyzr.com/blog/deprecate-an-mcp-server-safely
published: 2026-11-17
updated: 2026-11-17
author: Lyzr
---

# How do you deprecate an MCP server without breaking agents?

**Retire an MCP server in stages: find every agent that actually calls it from usage logs, mark it deprecated in your registry, give owners a dated notice period, offer a replacement or shim, block new connections, and only then revoke its credentials and shut it down. The order matters: credentials and network access are removed last, after usage has reached zero or the deadline has passed.**

Internal MCP servers multiply quickly. Teams build one per system, then replace them with consolidated or vendor-hosted servers. Shutting one off without a plan breaks agents in ways that are hard to diagnose, because an agent with a missing tool often fails softly—it tries something else or hallucinates an answer.

## Why is retiring an MCP server harder than retiring an API?

Three reasons.

1. **Consumers are not always registered.** A developer can add an MCP server to a coding agent's local config in seconds. Your list of known consumers is usually incomplete.
2. **Failure is quiet.** When a tool disappears from `tools/list`, many agents do not error. They route around it, which can produce wrong results instead of an outage.
3. **Tool names are part of prompts.** System prompts and skills often mention a tool by name. A rename on the replacement server can break behaviour even if the function is identical.

## How do you find every agent that depends on the server?

Do not rely on the registry alone. Combine sources:

| Source | What it shows | Gap |
|---|---|---|
| Registry entries | Agents declared as using the server | Undeclared and local usage |
| Server access logs | Every client and token that called it, with tool names | Needs client identity to be useful |
| Gateway or proxy logs | Calls by agent ID and acting user | Only traffic that passes the gateway |
| Developer-device discovery | Local MCP configs referencing the server | Requires an endpoint agent |
| Prompt and skill search | Hard-coded tool names | Text search only |

Build a dependency list with agent, owner, tools used, call volume over the last 30 days, and last call date. That list drives the notice process. If you log every tool call well, this step is a query, not a project; see [what to log for every MCP tool call](/blog/what-to-log-for-every-mcp-tool-call).

## What notice period should you give?

There is no standard in the MCP specification for server deprecation windows. Use your internal API policy as a baseline and scale by risk:

- **Read-only tools, few consumers:** 30 days is usually enough.
- **Write tools or production agents:** 60–90 days, with a test window on the replacement.
- **Tools used by external or partner agents:** match your contractual API deprecation terms.

For comparison, the MCP project itself deprecated Roots, Sampling and Logging in the 2026-07-28 revision with a minimum twelve-month window, which shows how long protocol-level changes take to flow through clients.

If you publish to the public MCP Registry, the registry's `status` field can be set to `"deprecated"`. Its [aggregator guidance](https://modelcontextprotocol.io/registry/registry-aggregators) says server metadata is generally immutable except for `status`, and recommends aggregators keep that field current. Mirror the same status in your private registry; see [how to run a private MCP registry](/blog/run-a-private-mcp-registry).

## How do you keep agents working during the migration?

Use one or more of these patterns:

1. **Version shim.** Keep the old server name and tool names, but implement them by calling the new server. Agents keep working while owners migrate prompts.
2. **Tool aliasing at a gateway.** Map old tool names to new ones in the traffic path for a fixed period.
3. **Deprecation notice in the tool description.** Add "Deprecated: use X by <date>" to tool descriptions. Models read descriptions, and developers see them in tool lists.
4. **Structured warnings.** Return a non-fatal warning in results so the calling team sees it in traces.

Avoid leaving a shim forever. Set an end date for it as part of the plan.

## The retirement checklist

1. Assign an owner and a target date.
2. Build the dependency list from logs, registry and device discovery.
3. Confirm the replacement is registered, reviewed and tested with representative agent runs.
4. Mark the server deprecated in the internal registry (and public registry if listed).
5. Notify every owner with the date, replacement and migration notes.
6. Add deprecation text to tool descriptions and enable the shim or alias.
7. Block new agents from connecting to the deprecated server.
8. Run regression evaluations on migrated agents; see [regression testing after a change](/blog/regression-test-ai-agent-after-prompt-change).
9. Track call volume weekly; chase remaining callers.
10. At zero usage or the deadline, revoke OAuth clients, tokens and network routes.
11. Shut down the server and remove local config entries through device management.
12. Archive the registry record and keep its audit history.

The same order applies when retiring agents; see [how to retire an AI agent safely](/blog/how-to-retire-an-ai-agent-safely).

## How Opencontroller does this

Opencontroller keeps a governed registry of agents, versions, tools and MCP servers, so you can see which agents are linked to a server before you retire it. Opencontroller Edge, installed by IT through MDM, extends discovery to local MCP servers on developer devices, where undeclared dependencies often live. "Ask" lets you query the whole agent estate in plain language, for example "which agents use this MCP server?" For the broader process, see the pillar on [how to govern MCP servers](/blog/how-to-govern-mcp-servers) or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Does the MCP specification define how to deprecate a server?**
No. The specification covers the protocol, not server lifecycle. The public MCP Registry offers a `deprecated` status, and the rest is your internal policy.

**Should I rename tools on the replacement server?**
Only if you must. Tool names appear in prompts and skills, so keeping names stable, or aliasing them during migration, avoids silent behaviour changes.

**When should credentials be revoked?**
Last, after usage reaches zero or the deadline passes. Revoking first causes outages and makes it harder to see who still depends on the server.

## Key facts

- The MCP specification does not define server deprecation windows; organisations set their own.
- The public MCP Registry allows a server's status field to be updated to "deprecated" or "deleted"; other metadata is generally immutable.
- The 2026-07-28 MCP revision deprecated Roots, Sampling and Logging with a minimum twelve-month window.
- Find MCP server dependents from server logs, gateway logs, registry entries, device discovery and prompt search, not the registry alone.
- Revoke credentials and network routes last, after usage reaches zero.
- Opencontroller's governed registry links agents to MCP servers; Opencontroller Edge discovers local MCP servers via MDM install; Ask queries the agent estate.
- Opencontroller pricing starts from $250K per deployment per year.

## Related

- [How do you run a private MCP registry for your enterprise?](https://opencontroller.lyzr.com/blog/run-a-private-mcp-registry.md)
- [What should you log for every MCP tool call?](https://opencontroller.lyzr.com/blog/what-to-log-for-every-mcp-tool-call.md)
- [How do you retire an AI agent safely?](https://opencontroller.lyzr.com/blog/how-to-retire-an-ai-agent-safely.md)
- [More on Tools and MCP](https://opencontroller.lyzr.com/blog/cluster/tools-and-mcp)
