Document recommended tool versioning and naming patterns for MCP servers (post SEP-986 / SEP-1575) #1915

Summary

With #986 (standardized tool-name format) and #1575 (tool versioning) now shaping the MCP ecosystem, it would be helpful to add clear, language-agnostic guidance for how servers should combine:

• Tool name (the canonical identifier).
• Tool version (SemVer metadata).
• Server behaviour when multiple versions of a tool are available.

Right now, the specification and docs describe the data model for tools and the wire format, but do not provide much guidance on patterns for versioning tools over time.

Motivation

As MCP servers evolve beyond small demos into multi-team, multi-client systems, server authors are asking questions such as:

• Should I encode the version in the name (e.g. get_info_v1) or keep a stable name and use the version field?
• How many versions of a given tool should I keep "live" at the same time?
• What should a server do when a client has no tool_requirements, but multiple versions exist?
• How do I avoid blowing up the tool surface for hosts and agents while still supporting older clients?

SEP-986 and SEP-1575 together provide most of the mechanics, but server authors still need higher-level guidance so they can adopt consistent patterns.

Proposal

I would like to propose adding a small "Tool Versioning & Naming Patterns" section under the docs, for example in:

• MCP Architecture: Design Philosophy & Engineering Principles, or
• MCP Best Practices: Architecture & Implementation Guide.

The section could cover:

1. Stable tool names

   • Tool name is a stable identifier that should not change across versions.
   • Names follow the canonical format from SEP-986 (e.g., simple identifier, consistent casing).
   • Examples: get_weather, get_invoice, list_projects, etc.

2. Semantic versions via version metadata

   • Tool version follows SemVer 2.0.0.
   • Backwards-incompatible changes ⇒ major version bump (1.x → 2.0.0).
   • Backwards-compatible additions ⇒ minor version bump.
   • Bugfixes ⇒ patch version bump.

3. Server behaviour with multiple versions

   • Servers MAY support multiple versions of the same tool (name, version) simultaneously.
   • When multiple versions exist:
     • One version SHOULD be treated as the default for clients that do not specify tool_requirements (typically the latest non-pre-release).
     • Servers MUST NOT change the behaviour of an existing (name, version) pair without bumping the version.
   • Servers SHOULD define a clear deprecation policy (e.g. keep N major versions or keep versions for X months).

4. Guidance on encoding versions in names

   • Clarify that encoding versions into name (e.g. get_info_v1, get_info_v2) is allowed by the format but is not the recommended pattern when the version field and tool_requirements are available.
   • Highlight drawbacks:
     • Harder client configuration (must chase name changes).
     • Less reuse of tool_requirements semantics.
     • Larger visible tool surface in host UIs.

5. Client-side usage

   • Recommend that:
     • Clients/hosts whitelist tools by name ("these are the tools this agent can use").
     • Version pinning is done via tool_requirements, not by hardcoding versioned names.
   • Provide a short example of tool_requirements for a multi-tool server.

6. Cross-language examples

   • Include one short example each in TypeScript, Python, and possibly Java, showing:
     • A server exposing get_info in versions 1.0.0 and 2.0.0.
     • How clients specify tool_requirements.
     • How hosts can still present a single “Get Info” tool in UI while using version metadata.

Alternatives / Open Questions

• Should the spec say anything about how long servers should keep older versions live, or is that out of scope and purely operational?
• Is there a need for an optional, structured “deprecation” annotation (e.g. annotations.deprecatedSince, annotations.replacement) for tools or tool versions?
• To what extent should the docs discourage the name_v1 / name_v2 pattern vs. simply documenting trade-offs?

How I can help

I am happy to:

• Draft an initial version of the “Tool Versioning & Naming Patterns” section for review.
• Provide concrete examples in Python (using the official Python SDK / FastMCP) and TypeScript.
• Iterate on the docs based on maintainer feedback, and align them with the final SEP-1575 behaviour and the 2025-11-25 spec revision.