Add RegisterTools API to McpClient for pre-populating tool cache

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

[tarekgh]

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes#1577

Changes

API Additions on McpClient

• AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
• RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
• ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

• Known tools are added to the same _toolCache used by ListToolsAsync
• A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
• ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
• Fast path: when no known tools exist, _toolCache.Clear() is called directly
• All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
• Re-registering a tool with the same name overwrites the previous definition (last write wins)
• If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
• LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

• AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
• ListToolsAsync -> AddKnownTools: both coexist in cache
• AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
• RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

• Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
• XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

• Register then list — server tools repopulated correctly
• Multiple ListToolsAsync cycles with registered tools
• List then register ordering
• Register -> list -> register again
• Same name as server tool (server overwrites definition, pinned status preserved)
• Invalid x-mcp-header schema rejection (all-or-nothing)
• Duplicate registration (last write wins)
• Null argument validation (AddKnownTools, RemoveKnownTools)
• No-header-annotation tools still accepted
• Register then CallToolAsync without ListToolsAsync (cache lookup works)
• RemoveKnownTools — removed tool no longer survives ListToolsAsync
• RemoveKnownTools — non-existent name is no-op
• RemoveKnownTools — partial remove, other tools survive
• ClearKnownTools — removes all, server tools unaffected
• ClearKnownTools — empty is no-op
• ClearKnownTools then AddKnownTools — works correctly
• Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
• Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

• Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
• No headers sent without register or list
• Known tool headers survive ListToolsAsync cache clear
• RemoveKnownTools -> no headers sent after removal
• Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
• Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

[tarekgh]

#1553

[halter73]

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

[tarekgh]

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.