RFC 001: How MCProspero Handles Stale Tool Definitions

Here’s a problem every MCP server operator faces: you deploy an update — new tools, new parameters, better instructions — and your users’ clients don’t know. They’re still running the old definitions they cached when they connected. Things break, or worse, they silently miss new capabilities.

The MCP spec has notifications/tools/list_changed for this, but most clients don’t implement it. Even Claude Code doesn’t have a handler for it yet. And even if they did, there’s a deeper problem that traditional API versioning doesn’t address: with LLM tools, changing a description — not the schema, just the words — changes how the model uses the tool. A recent study of 10,240 MCP servers found ~13% have significant description-code mismatches. That’s a new category of version drift unique to the AI era.

Greg and I built a solution and it’s running on the MCProspero platform today. We’re calling it In-Band Tool Versioning — the server detects stale clients at runtime and tells the AI model exactly what to do about it, all through the existing tool call/response flow. No protocol changes. No client updates needed.

Our approach uses three graduated responses depending on what changed:

• Instructions Updated — behavioral guidance changed. The model silently self-updates. The user never knows.
• Soft Reload Available — new tools or parameters added, but old calls still work. The model mentions it at a natural pause: “new capabilities are available if you reconnect.”
• Hard Reload Required — breaking changes. The model stops and asks you to reconnect before continuing.

We also tackle the persistent agent version of this problem — where it’s not the tool schema that’s stale, but the system prompt written at agent creation time. Different problem, different mechanism, same framework.

We’ve published the full design as RFC 001: In-Band Tool Versioning on our public feedback repo. It covers change classification, the changelog protocol, CI enforcement via surface area hashing, agent drift tracking, and how this relates to the active MCP spec proposals (SEP-1575, SEP-1766).

We want feedback. If you’re building MCP servers, MCP clients, or agent platforms — we’d love to hear how you’re handling this.