Skip to content

feat: Component versioning for tools and resources #2

@superWorldSavior

Description

@superWorldSavior

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

  • version field on ToolRegistration and ResourceRegistration
  • Version resolution logic in tool/resource lookup
  • VersionFilter middleware
  • Documentation + examples
  • Tests

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions