Implementation for SEP-2243 Http Standardization

[mikekistler]

Motivation and Context

Implements SEP-2243 (HTTP Header Standardization) for both client and server Streamable HTTP transports. This enables network infrastructure (load balancers, proxies, gateways) to make routing and filtering decisions based on MCP request metadata without parsing the JSON-RPC body.

Fixes #1541.

Changes

Protocol & Constants

• Add McpHttpHeaders static class with standard header name constants (Mcp-Method, Mcp-Name, Mcp-Param-*, etc.)
• Add DRAFT-2026-v1 as a supported protocol version for header enforcement
• Add McpErrorCode.HeaderMismatch (-32001) for header validation failures

Client-side (ModelContextProtocol.Core)

• StreamableHttpClientSessionTransport emits Mcp-Method, Mcp-Name, and Mcp-Param-* headers on all outgoing POST requests
• McpHeaderEncoder handles value encoding (plain ASCII pass-through, Base64 wrapping with =?base64?...?= sentinel for non-ASCII/control characters/leading-trailing whitespace)
• McpHeaderExtractor (internal) reads x-mcp-header annotations from tool schemas and adds corresponding Mcp-Param-{Name} headers
• Client validates tool schemas from tools/list and rejects tools with invalid x-mcp-header annotations (empty names, invalid characters, case-insensitive duplicates, non-primitive types)

Server-side (ModelContextProtocol.AspNetCore)

• StreamableHttpHandler validates incoming Mcp-Method and Mcp-Name headers match the JSON-RPC body (enforced only for DRAFT-2026-v1+)
• Validates Mcp-Param-* custom headers against tool schema x-mcp-header annotations and body argument values
• Returns 400 Bad Request with HeaderMismatch (-32001) JSON-RPC error on validation failure

Tool Authoring (ModelContextProtocol.Core)

• [McpHeader("Name")] attribute marks tool parameters for header mirroring
• AIFunctionMcpServerTool emits x-mcp-header extension in the tool's JSON schema for annotated parameters
• Validates at registration time: primitive types only, case-insensitive unique names, valid ASCII characters

Protocol Version Gating

Header validation is only enforced when the client's MCP-Protocol-Version header is DRAFT-2026-v1 or later. Clients on older protocol versions are unaffected. The client always sends headers on Streamable HTTP transport regardless of version (additive, non-breaking).

New Public API Surface

ModelContextProtocol.Protocol.McpHttpHeaders (static class)

public static class McpHttpHeaders
{
    // Version gating
    public static readonly string MinVersionForStandardHeaders; // "DRAFT-2026-v1"
    public static bool SupportsStandardHeaders(string? protocolVersion);

    // Standard header name constants
    public const string SessionId = "Mcp-Session-Id";
    public const string ProtocolVersion = "MCP-Protocol-Version";
    public const string LastEventId = "Last-Event-ID";
    public const string Method = "Mcp-Method";
    public const string Name = "Mcp-Name";
    public const string ParamPrefix = "Mcp-Param-";
}

ModelContextProtocol.Protocol.McpHeaderEncoder (static class)

public static class McpHeaderEncoder
{
    // Typed overloads for compile-time safety
    public static string? EncodeValue(string? value);
    public static string EncodeValue(bool value);
    public static string EncodeValue(long value);
    public static string EncodeValue(double value);

    // General-purpose overload (supports all numeric types)
    public static string? EncodeValue(object? value);

    // Decoding (case-insensitive Base64 prefix detection)
    public static string? DecodeValue(string? headerValue);
}

ModelContextProtocol.Server.McpHeaderAttribute (attribute)

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property)]
public sealed class McpHeaderAttribute : Attribute
{
    public McpHeaderAttribute(string name);
    public string Name { get; }
}

ModelContextProtocol.McpErrorCode (enum addition)

public enum McpErrorCode
{
    HeaderMismatch = -32001,  // New
    // ... existing values unchanged
}

How Has This Been Tested?

The PR includes comprehensive tests covering:

• Unit tests: McpHeaderEncoderTests — encode/decode round-trips, Base64 edge cases, type conversion, empty/null handling
• Unit tests: McpHeaderAttribute validation and schema generation
• Conformance tests: Sep2243HeaderTests — server-side header validation (method/name mismatch, missing headers, Base64 encoding, version gating, custom parameter headers)
• Integration tests: End-to-end client→server header flow via in-memory transport

Conformance tests are aligned with conformance repo PR #259.

All existing tests continue to pass (~8,000+ across net8.0, net9.0, net10.0, net472).

Breaking Changes

No breaking changes.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[halter73]

Given the new revision of the protocol, shouldn't we be rejecting all client-to-server responses and errors?

Suggested change

	if (!(message is JsonRpcRequest || message is JsonRpcNotification))
	if (message is not JsonRpcRequest or not JsonRpcNotification)
	{
	// Reject if draft protocol version entirely
	}

We should probably just move this down into McpServerImpl, and then we wouldn't need the check in StreamableHttpHandler at all.

[tarekgh]

@halter73

The SEP-2243 doesn't require it; the spec only defines header behavior for requests/notifications.

Moving rejection to McpServerImpl affects all transports (stdio, SSE, etc.), not just HTTP, which potentionaly could break existing behavior?

Client responses are still valid as in MCP, clients can send responses to server-initiated requests (e.g., sampling/createMessage responses). Rejecting them would break that flow?

The suggested code has a bug? message is not JsonRpcRequest or not JsonRpcNotification is always true?

[halter73]

This does seem pretty fragile to me to parse the Params twice. I wonder if we could flow the headers down to McpServerImpl so we could do the header validation there. I would hate it if we ended up looking at a different primitive or a different JSON property due to some subtle difference in parsing at each layer.

[tarekgh]

Flowing the headers down to McpServerImpl will have a trade-off:

• Pro: Single source of truth for params; McpServerImpl uses the same deserialized CallToolRequestParams for both dispatch and validation. No divergence risk.
• Con: Header validation now happens deeper in the pipeline (after session creation, after message routing), so invalid headers get further before being rejected. Error responses go through the JSON-RPC layer rather than being a simple HTTP 400.
• Con: Couples McpServerImpl (in Core, transport-agnostic) to HTTP header concepts. We'll need to abstract the validation behind an interface or delegate to keep Core clean.

I suggest we can discuss this more and address it outside this PR.

[halter73]

I wonder if we should force you to opt into sending the HTTP standardization headers by selecting the DRAFT-2026-v1 ProtocolVersion. This would be similar to what I have in my MRTR prototype at #1458. That adds a new ExperimentalProtocolVersion property to both the server and client options to opt-in to the draft behavior.

HTTP standardization is different from MRTR, because it's not breaking to just send the headers from the client even if you don't opt into the new protocol version, and it's fine for the server to only require them if the client tries to use the new draft protocol.

However, I still think we probably should just gate all the new behavior on opting into the new protocol version though. I think if we do this, that will probably make cross-version compatibility testing easier.

[tarekgh]

I would suggest not using ExperimentalProtocolVersion for now, and revisiting it later.

My reasoning is:

• The headers are purely additive on the client side, so sending extra headers should not break anything.
• Server-side validation can remain lenient by validating only when the headers are present, rather than requiring explicit opt-in.

For old client → new server: with the current implementation, the server only validates MCP headers when the client sends Mcp-Protocol-Version: DRAFT-2026-v1. Older clients that either omit the header or send 2025-11-05 will pass through without validation or rejection, so compatibility should be fine.

For new client → old server: this should also be fine, since older servers will simply ignore headers, they do not recognize.

So, the cross-version compatibility concern already appears to be addressed.

I’m open to discussing this further, but I’d prefer to get #1458 completed first, and then evaluate whether introducing ExperimentalProtocolVersion would provide enough benefit.

[tarekgh]

@halter73 I have updated the CI Node.js from 20 to 22 because package.json pins @modelcontextprotocol/conformance at 0.1.16, which requires fs.globSync (added in Node 22).

Let me know if there is any concern with that.