Motivation
When an MCP server evolves in production, tool signatures change — new parameters, different return shapes, renamed fields. Today, updating a tool is a breaking change for all connected clients.
Proposal
Add a version field to tool/resource registration, with automatic version management:
server.registerTool(
{
name: "query",
version: "2.0",
description: "Query the database (v2 — structured output)",
inputSchema: { ... },
},
handler,
);
Behavior
- Server exposes the highest version of each tool by default via
tools/list
- Older versions remain accessible via explicit version qualifier (e.g.
query@1.0)
- A
VersionFilter middleware could allow running a "v1-only" or "v2-only" server from the same codebase
Use cases
- Gradual migration: deploy v2 tools alongside v1 without breaking existing agents
- Multi-tenant: different clients pinned to different API versions
- Rollback: revert to a previous version without redeploying
Prior art
- FastMCP 3.0
@tool(version="1.0") — automatic highest-version exposure
- HTTP API versioning patterns (Accept-Version header, URL prefix)
Scope
Motivation
When an MCP server evolves in production, tool signatures change — new parameters, different return shapes, renamed fields. Today, updating a tool is a breaking change for all connected clients.
Proposal
Add a
versionfield to tool/resource registration, with automatic version management:Behavior
tools/listquery@1.0)VersionFiltermiddleware could allow running a "v1-only" or "v2-only" server from the same codebaseUse cases
Prior art
@tool(version="1.0")— automatic highest-version exposureScope
versionfield onToolRegistrationandResourceRegistrationVersionFiltermiddleware