Summary

This PR introduces SEP-2053: Server Variants, which proposes a server-level variant mechanism enabling MCP servers to expose multiple variants simultaneously. Each variant includes a unique identifier, human-readable description, and key-value hints that intelligent clients can use to select an appropriate variant for their context.

The primary motivation is cross-agent tool reusability - enabling the same MCP tools to serve fundamentally different agent architectures (coding assistants, research agents, task automation agents, conversational agents, etc.) or models (claude, gpt, gemini etc) with optimized surface areas tailored to each use case.

Motivation and Context

Problem: Server capabilities in MCP are currently monolithic - a single capability definition must serve all clients equally, regardless of which LLM is interpreting them, the client's use case, capabilities, or context constraints.

Solution: Server variants allow servers to expose parallel configurations (e.g., claude-optimized, gpt-optimized, compact, coding-assistant, automation-agent) that clients can intelligently select based on their context.

Why is this needed?

• Different LLMs benefit from different tool descriptions and schemas
• Different agent types (coding assistant vs automation agent) need different tool surface areas
• Current one-size-fits-all approach forces suboptimal tool definitions
• Without variants, tool authors must build separate servers for each use case, fragmenting the ecosystem

How Has This Been Tested?

This is a specification proposal (SEP) with:

• Comprehensive examples in the SEP document
• Detailed client and server behavior specifications
• Backward compatibility analysis
• Reference to established patterns (ModelPreferences from MCP sampling)

Real-world validation will come from prototype implementations once the SEP is accepted.

Breaking Changes

None - This is fully backward compatible:

• Existing servers without variants continue to work unchanged
• Existing clients ignore variant fields if present
• Variant selection is optional and happens via _meta on a per-request basis
• Default behavior (no variant specified) uses server's recommended default

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally (N/A - specification only)
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Design Principles:

• Parallel Variants: Servers can expose multiple variants simultaneously
• Intelligent Selection: Clients auto-select using structured metadata
• Per-Request Flexibility: Variant selection via _meta (stateless)
• LLM-Friendly: Descriptions and hints structured for LLM reasoning
• Server-Wide Scope: Applies to all capabilities (tools, resources, prompts, subscriptions)
• Graceful Deprecation: Clear mechanism with migration guidance

Packaging: Currently specified as an MCP extension to minimize core schema churn.

Related Issues:

• Addresses concerns from Issue Feature Request: Model-Aware Content Adaptation for MCP #469 (agent-aware content adaptation)
• Related community discussions on tool optimization and capability negotiation

SEP Status: Draft, seeking sponsor