Skip to content

Validate SEP-2243 Mcp-Param headers in the modern server - #1286

Open
Kehrlann wants to merge 2 commits into
mainfrom
dgarnier/x-mcp-header
Open

Kehrlann wants to merge 2 commits into
mainfrom
dgarnier/x-mcp-header

Conversation

@Kehrlann

@Kehrlann Kehrlann commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Closes #1199

  • Tools can mark inputSchema arguments with x-mcp-header, so clients mirror them into Mcp-Param-{Name} headers. Servers MUST reject a request whose headers and body disagree, with 400 / -32020.
  • Since only tools/call use those header, they are not part of the McpRequestHandler interface, and rather are carried through the McpTransportContext.
  • The HTTP transport extracts and decodes Mcp-Param-* headers and puts them in the context. STDIO puts a marker "not mirrored" value instead.
  • Validation happens in ToolsFeature, where we have both the tool definition (including x-mcp-header annotations in the schema) and the values for the tool call.
  • McpHeaderDecoder and McpParamHeaders are public, so other HTTP transports can reuse them.
  • Mcp-Name now uses the same strict decoder.

- Transports need to list a context's entries and combine contexts, for
  instance to add the decoded Mcp-Param-* headers to a context built by
  a user-provided extractor.
- This introduces a way to merge McpTransportContext. To do so, it
  introduces a way to read entries from the contexts, by key-value.
- This change is non-breaking but custom implementations of
  McpTransportContext used in the modern server MUST implement stream().

The implementation is inspired from Reactor's Context.

Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
- Tools can mark inputSchema arguments with x-mcp-header, so clients
  mirror them into Mcp-Param-{Name} headers. Servers MUST reject a
  request whose headers and body disagree, with 400 / -32020.
- Since only tools/call use those header, they are not part of the
  McpRequestHandler interface, and rather are carried through the
  McpTransportContext.
- The HTTP transport extracts and decodes Mcp-Param-* headers and puts
  them in the context. STDIO puts a marker "not mirrored" value instead.
- Validation happens in ToolsFeature, where we have both the tool
  definition (including x-mcp-header annotations in the schema) and the
  values for the tool call.
- McpHeaderDecoder and McpParamHeaders are public, so other HTTP
  transports can reuse them.
- Mcp-Name now uses the same strict decoder.

Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
@Kehrlann
Kehrlann added this pull request to stack #1287 October 26, 2026 17:26
@Kehrlann
Kehrlann requested a review from chemicL October 26, 2026 17:29
@Kehrlann
Kehrlann removed this pull request from stack #1287 October 31, 2026 15:23
@Kehrlann
Kehrlann changed the base branch from dgarnier/merge-mcp-transport-contexts to main October 31, 2026 15:24

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Validate SEP-2243 Mcp-Param-{Name} headers in the modern server

1 participant