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

Open
#1,881 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
28/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp
Domain
api, backend-api-design

Research direction

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.

Written by the indexing model from the issue text.

Description

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.

Dominant language
C#
Stars
4.5k
Forks
814
Avg merge
9d 19h
Merged PRs (30d)
4

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/csharp-sdk

All issues in modelcontextprotocol/csharp-sdk

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.