How do you change an MCP server without breaking the agents already using it?

An MCP tool has no version field, so you change a server by adding first, announcing in the tool's own description, and removing last. The agent calling your tool never reads a changelog; it reads the list the server returns today and the description of each entry.

Writing a tool description and choosing the catalog are covered elsewhere. This article starts later, when a tool that agents already call has to change.

What the protocol gives you, and what it doesn't

Relevant parts of the MCP specification (revision 2026-07-28, read on November 9, 2026):

• A tool definition carries a name, an optional title, a description, optional icons, an inputSchema, an optional outputSchema and annotations. No version field.
• Servers that declare the tools capability may declare listChanged, meaning they will emit a notification when the tool list changes. Clients receive it if they opened a subscriptions/listen stream asking for it.
• The tool list may change over time and may vary with the authorization presented on a request.
• tools/list supports caching: a response can carry a time-to-live. A client may therefore keep serving an old list for a while.
• Calling a name the server no longer knows returns a protocol error, "unknown tool", which the specification says models are less likely to recover from than a tool execution error.

Three consequences. The version lives in your conventions. Not every client sees a change at the same moment. And a removal is the worst failure mode, because the agent is told nothing it can use.

Four kinds of change, four levels of risk

Adding a tool is safe. Nobody calls it yet. Its description will decide whether anyone does.

Adding an optional parameter is almost always safe. Callers that ignore it keep working. Give it a default that preserves the old behavior.

Narrowing or widening what a tool returns is where silent breakage lives. An agent that read "returns open issues" in its context keeps relying on that sentence even after the tool also returns closed ones. The call succeeds, the answer is wrong. This is the class that no error will ever reveal, and the one to treat as breaking.

Renaming a tool, changing what a parameter means, or deleting a tool breaks calls outright or changes them without telling anyone.

The rule that follows: a change is breaking if an agent that did everything right yesterday gets a different answer today. The test is behavioral, not syntactic. Consumers of a regular API ask the same question about breaking changes in an API; here the consumer is a model and the contract is partly prose.

A rename, traced over four dates

Illustrative scenario: a server exposes search_docs, and the team wants to call it find_answers because the tool now returns answers, not pages. Nothing here is a real customer.

Day 0, add. find_answers joins the list. search_docs stays, unchanged. Two tools do the same job; that is intended. Agents that have the old name in their instructions keep working.

Day 1, warn in the description. The description of search_docs now begins: "Replaced by find_answers. Still works until day 30. Prefer find_answers." Why in the description? Because it is the only text the model reliably reads when it chooses. A message in a release note reaches the humans who maintain the agent, not the agent.

Day 14, watch. Look at the call log: who still calls search_docs? A server cannot know why, but it can tell which tool, how often, and with which credential. Credentials map to people you can write to. Without that log, you are removing blind.

Day 30, remove. Only when the old name is quiet, or when the stated date has passed and the people calling it were warned. After this date, a call to search_docs gets an unknown-tool error.

Notice what the sequence avoids: no moment where the list is smaller than what agents expect before they've been told. That is the whole discipline, in one sentence: expand, announce, contract.

Three habits that make the sequence work

Keep the order of the list stable. The specification asks servers to return tools in a deterministic order when nothing has changed, which lets clients cache and keeps prompts reusable. A reshuffle with each deploy turns a no-op into an apparent change.

Name things for the long term. Tool names should be unique within a server, and the specification suggests letters, digits, underscore, hyphen and dot. A name like get_docs_v2 makes the version part of the name, which works, but now you carry two names forever. Use it only when the old behavior truly has to survive.

Log by credential. If each agent or client presents its own revocable credential, you can say "this credential still calls the old name." That turns removal from a guess into an email.

Testing the change before you ship it

A change to a tool is a change to the answers it produces. Replay a fixed sheet of questions before and after, as in the evaluation trial for product teams, and compare. A differing answer is not necessarily a bug; an unannounced difference is.

The objection: "we control the agents, we'll just update them"

Often true inside one team, and then the problem is small. It stops being true when an agent belongs to someone else: a support platform, a client, a contractor, an editor with its own cache. You rarely control the instructions that mention your tool names. Announce in the description anyway; it costs a sentence.

The mirror objection: "all this ceremony for a tool list?"

If three agents you own call the server, skip most of it. Rename, redeploy, fix the instructions. The sequence earns its cost when you can't enumerate your callers, or when a wrong answer is expensive. For a server that answers questions about a product, the second case arrives sooner than expected: a stale answer looks exactly like a correct one.

What DeployIt does here

DeployIt reads the real code (resynced on every push) and the git history, commits and diffs, through its own MCP servers, and checks the code before it asserts anything. Read-only, revocable at any time. The server is in early access / design partner program, and we do not describe its catalog's versioning policy here: ask for it in the program. What we can say is the principle the article defends: the answers should follow the code, so a change in the product shows up in the answer without anyone rewriting a page. See the MCP server and the living help center.

Frequently asked questions

Should I put a version number in the tool name? Only if two behaviors must coexist for a long time. Otherwise prefer add, announce, remove, and keep the name stable.

Is there a way to tell agents about a change automatically? The list-changed notification tells a listening client that the list moved. It does not say why. The description is where the reason goes.

How long should the overlap last? Long enough to see the old name go quiet in your log, and to reach whoever still calls it. The right number is the one your log supports, not a standard.

Key takeaways

No version field: the convention is yours. Add, announce in the description, watch, remove last. A change is breaking when yesterday's correct call returns a different answer today.

DeployIt is free during early access; paid plans arrive in January 2027. The MCP server is in early access / design partner program, and the program is open.