Fix client to accept any supported server protocol version during negotiation

[mikekistler]

Fixes #1536

When McpClientOptions.ProtocolVersion is explicitly set, the client incorrectly requires the server to respond with that exact version. If the server responds with a different but supported version (e.g., negotiating down from DRAFT-2026-v1 to 2025-11-25), the client throws McpException: Server protocol version mismatch.

Changes

1. Test (AcceptsLowerServerProtocolVersion): Verifies the client accepts a server responding with a lower supported protocol version when the client explicitly requests a higher one.
2. Fix: Change the version validation in McpClientImpl.cs to accept any version in SupportedProtocolVersions, regardless of whether ProtocolVersion was explicitly set. The explicit version is still accepted as a fallback for forward compatibility.

[mikekistler]

This needs fixes. Moving to draft for now.

[Copilot]

Pull request overview

This PR fixes MCP client protocol-version negotiation so an explicitly requested version doesn’t require an exact match from the server, and also introduces Streamable HTTP header standardization support (standard + custom parameter headers) with accompanying conformance and unit tests.

Changes:

• Relax client initialization validation to accept any server protocol version in SupportedProtocolVersions (while still allowing an explicit ProtocolVersion as a forward-compat fallback).
• Add x-mcp-header support for tools (schema extension + client header emission + server-side validation + header encoding helpers).
• Expand conformance coverage (client + server) and add new unit tests for header behavior and protocol downgrade negotiation.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tests/ModelContextProtocol.Tests/Server/McpServerToolTests.cs	Adds unit tests ensuring x-mcp-header schema extensions are produced and validated.
tests/ModelContextProtocol.Tests/Server/McpHeaderAttributeTests.cs	Adds constructor validation tests for McpHeaderAttribute.
tests/ModelContextProtocol.Tests/Client/McpRequestHeadersTests.cs	Adds tests for new HTTP header constants and HeaderMismatch error code value.
tests/ModelContextProtocol.Tests/Client/McpHeaderEncoderTests.cs	Adds tests for header value encoding/decoding rules.
tests/ModelContextProtocol.Tests/Client/McpClientTests.cs	Adds downgrade negotiation test (AcceptsLowerServerProtocolVersion).
tests/ModelContextProtocol.ConformanceServer/Tools/ConformanceTools.cs	Adds a conformance tool annotated with McpHeader for header scenarios.
tests/ModelContextProtocol.ConformanceClient/Program.cs	Adds conformance scenarios and allows protocol version override via env var.
tests/ModelContextProtocol.AspNetCore.Tests/ServerConformanceTests.cs	Adds server conformance scenarios for HTTP header validation.
tests/ModelContextProtocol.AspNetCore.Tests/ClientConformanceTests.cs	Adds client conformance scenarios for HTTP header standardization.
tests/Common/Utils/NodeHelpers.cs	Passes MCP_CONFORMANCE_PROTOCOL_VERSION through to the Node conformance runner.
src/ModelContextProtocol.Core/Server/McpHeaderAttribute.cs	Introduces McpHeaderAttribute and header-name validation logic.
src/ModelContextProtocol.Core/Server/AIFunctionMcpServerTool.cs	Post-processes tool schemas to add x-mcp-header extensions from attributes.
src/ModelContextProtocol.Core/Protocol/McpHttpHeaders.cs	Adds constants for MCP-specific HTTP headers and a feature-gating version constant.
src/ModelContextProtocol.Core/McpSessionHandler.cs	Adds DRAFT-2026-v1 to supported protocol versions.
src/ModelContextProtocol.Core/McpErrorCode.cs	Adds HeaderMismatch = -32001 for Streamable HTTP header validation failures.
src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs	Adds standard/custom MCP request headers to Streamable HTTP requests.
src/ModelContextProtocol.Core/Client/McpHeaderExtractor.cs	Extracts x-mcp-header-annotated args and mirrors them into HTTP headers.
src/ModelContextProtocol.Core/Client/McpHeaderEncoder.cs	Implements encoding/decoding rules for header-safe parameter values.
src/ModelContextProtocol.Core/Client/McpClientImpl.cs	Fixes protocol negotiation validation; caches tools for custom header emission.
src/ModelContextProtocol.Core/Client/McpClient.Methods.cs	Hooks tool discovery to allow caching tool definitions on list.
src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs	Adds server-side validation of standard/custom MCP headers for Streamable HTTP.

[mikekistler]

Not a bug. Closing.