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

[ump45nose]

Proposal: Declarative Tool Versioning & Runtime Header/Endpoint Gating

Motivation & Context

Addressing #1557 in conjunction with #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 Version-Based Tool Registration for MCP Server #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.