[Proposal] Declarative tool registration & runtime filtering for version gating (#1557)

Proposal: Declarative Tool Versioning & Runtime Header/Endpoint Gating

Motivation & Context

Addressing https://github.com/modelcontextprotocol/csharp-sdk/issues/1557 in conjunction with https://github.com/modelcontextprotocol/csharp-sdk/issues/1216.

Currently, MCP tools registered in McpServerToolCollection lack built-in version metadata or request-scoped filtering capabilities. Developers needing phased canary/beta rollouts must manually intercept tools/list and mutate ServerOptions.ToolCollection at runtime, which is error-prone and causes concurrency/state-bleed issues across sessions.

Proposed Design Alignment

To bridge the static endpoint scoping (#1216) and runtime header gating (#1557), we propose:

1. [McpServerTool] Metadata Extension:

   • Add optional string? Version or string? Group.
   • Add optional string? RequiredHeader and string? HeaderPattern (or route constraints).

2. Scoped IToolFilter / Request Predicate:

   • Instead of mutating ToolCollection during tools/list, introduce a non-destructive filter hook Func<McpContext, ToolMetadata, bool> in McpServerOptions.
   • When handling tools/list and tools/call, evaluate the active request context against registered predicates.
   • Non-matching tools are excluded from the enumeration and return standard MethodNotFound / -32601 if called directly without the qualifying header.

3. Coexistence with #1216:

   • Static route-mapped toolsets and dynamic header-gated tools share the same underlying filter contract.

This avoids destructive list mutation and cleanly supports progressive opt-in deployments.

AI assistance disclosure: AI was used to discover this opportunity and draft the change or text. The submission was checked against the prepared artifact and recorded verification evidence.

Start by tracing McpServerToolCollection, McpServerOptions, and the handling of tools/list and tools/call. Review the related issues #1557 and #1216 to understand the intended filter contract and how static and request-scoped gating should coexist. Done means version or group metadata and request predicates support non-destructive filtering, direct calls reject unavailable tools, and shared state is not mutated across sessions.