Skip to content

Commit 5d54cee

Browse files
committed
Validate Mcp-Param-* headers against the tool call body
## Motivation and Context SEP-2243 (MCP 2026-07-28) lets a tool mark parameters with `x-mcp-header` so that clients mirror their values into `Mcp-Param-{Name}` request headers, which intermediaries route on without parsing bodies, and it has the server validate those headers against the body: a routing decision taken on a header the server does not act on is the vulnerability the spec names. The Ruby SDK sent the headers as a client but did not check them as a server, and its conformance server declared no such parameter, so the referee's `http-custom-header-server-validation` scenario reported its checks as untestable. The TypeScript, Python, Go, Rust, C#, and Java SDKs all validate on the server and arm a fixture tool. `StreamableHTTPTransport` now checks a modern `tools/call` before it is dispatched: for each `x-mcp-header` parameter of the called tool, the `Mcp-Param-{Name}` header has to be present exactly when the body carries a mirrorable value for it and has to agree with it once a `=?base64?...?=` sentinel is decoded. A disagreement is refused with HTTP 400 and `-32020` (`HeaderMismatch`), the shape the standard-header checks already use, naming the header and, except in the two encoding refusals, the argument path, but never a value. The codec moves from the client namespace to `MCP::McpParamHeaders`, shared by both sides as in the TypeScript and Python SDKs, and gains the decoding and the comparison. Points settled by the spec, the reference SDKs, or the risk at hand: - Decoding is strict: a sentinel payload with wrong padding, a character outside the alphabet, non-zero trailing bits, or bytes that are not UTF-8 is refused rather than compared, so a sentinel has one spelling for a given value (the SEP-2243 test-case table; the TypeScript and Python decoders refuse the same). - A header without the sentinel that holds a byte outside the field-value set (visible ASCII, space, and tab) is refused as the spec's invalid characters instead of being compared byte for byte with the body. The TypeScript and Python servers do not check this, since a conforming client wraps such a value, but a server must not act on one either way. - A header whose argument is absent or `null` in the body is refused, as the Python SDK does: a conforming client omits such a header, and one sent anyway claims a value the handler never sees. The TypeScript SDK ignores it. - Integer and number parameters compare numerically when the header is a canonical decimal (`42.0` agrees with `42`, the spec's SHOULD), exactly for integers; anything else compares the decoded header with the body value's header rendering byte for byte. Only a numeral of at most 64 bytes is read as a number, which bounds the parsing a header can ask for; a longer one is judged by byte equality alone, so it still agrees with the rendering a client mirrors and with nothing else. - The scanner shared with the client also treats `contentSchema` as a position the `properties` chain cannot pass through, as the Python SDK does, so an annotation there invalidates the tool like one under `items`. - Headers for parameters without a declaration are ignored, as the spec asks of a server that does not recognize them; a tool whose declarations are invalid is not validated, since conforming clients drop it and send nothing for it; an unknown tool is left to the dispatcher's own refusal. The handshake lifecycle has no custom headers to check. - The check runs on the schema the server serves in `tools/list`, before the tool runs, so a refused request never reaches a handler. The conformance server gains `test_x_mcp_header`, a tool with a `region` parameter mirrored into `Mcp-Param-Region`, as the TypeScript and Python fixtures have. With the server leg of the referee selecting every scenario, the scenario's baseline entry is dropped. ## How Has This Been Tested? test/mcp/mcp_param_headers_test.rb and test/mcp/server/transports/streamable_http_mcp_param_test.rb. Before the change, `npx @modelcontextprotocol/conformance@alpha server --scenario http-custom-header-server-validation` reported its four checks as untestable, since no tool declared an `x-mcp-header` parameter; it now passes 10/10. ## Breaking Changes None. `MCP::Client::McpParamHeaders` stays as an alias of `MCP::McpParamHeaders`, so code that referenced the old name keeps working, and requests of the handshake lifecycle are unaffected.
1 parent 2cd02af commit 5d54cee

12 files changed

Lines changed: 1033 additions & 456 deletions

File tree

‎conformance/expected_failures.yml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,6 @@ server:
33
# the referee warns about each of the two; the baseline counts a warning as a failure. The resume on
44
# `Last-Event-ID` is not exercised, since the server does not close the stream mid-call.
55
- server-sse-polling
6-
# SEP-2243 custom headers: the server does not bind `Mcp-Param-*` headers to `x-mcp-header` tool parameters
7-
# (the client side sends them), so the conformance server exposes no such tool and the referee reports
8-
# the scenario's checks as untestable.
9-
- http-custom-header-server-validation
106
# SEP-2663 (io.modelcontextprotocol/tasks): the server does not implement the tasks extension.
117
# `tasks-status-notifications` is intentionally absent: the referee runs no check in it, and a baseline entry
128
# for a scenario with no failing check is flagged stale.

‎conformance/server.rb‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,24 @@ def call(**_args)
325325
end
326326
end
327327

328+
class TestXMcpHeader < MCP::Tool
329+
tool_name "test_x_mcp_header"
330+
description "A tool whose region argument is mirrored into the Mcp-Param-Region header (SEP-2243)"
331+
input_schema(
332+
properties: {
333+
region: { type: "string", description: "Mirrored into the Mcp-Param-Region header", "x-mcp-header": "Region" },
334+
},
335+
)
336+
337+
class << self
338+
# Arms the `http-custom-header-server-validation` server scenario, which the referee skips when no tool declares
339+
# an `x-mcp-header` parameter, as the TypeScript and Python fixtures do.
340+
def call(region: "<none>", **_args)
341+
MCP::Tool::Response.new([MCP::Content::Text.new("region=#{region}").to_h])
342+
end
343+
end
344+
end
345+
328346
class TestMissingCapability < MCP::Tool
329347
tool_name "test_missing_capability"
330348
description "A tool that requires the sampling client capability (SEP-2575)"
@@ -924,6 +942,7 @@ def build_server
924942
Tools::TestElicitationSep1034Defaults,
925943
Tools::TestElicitationSep1330Enums,
926944
Tools::TestReconnection,
945+
Tools::TestXMcpHeader,
927946
Tools::TestMissingCapability,
928947
Tools::TestInputRequiredResultElicitation,
929948
Tools::TestInputRequiredResultSampling,

‎docs/_server/tools.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,48 @@ Annotations can be set either through the class definition using the `annotation
153153
{: .note }
154154
> This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.
155155
156+
## Custom Headers from Tool Parameters
157+
158+
On the [modern lifecycle](/server/discover/#the-stateless-modern-lifecycle) (MCP 2026-07-28, SEP-2243), a tool can designate parameters
159+
whose values the client mirrors into `Mcp-Param-{Name}` request headers, so intermediaries can route or apply policy on them
160+
without parsing bodies. Declare the header name with an `x-mcp-header` annotation on the parameter's property:
161+
162+
```ruby
163+
class RegionalTool < MCP::Tool
164+
description "Runs in the region the request names"
165+
input_schema(
166+
properties: {
167+
region: { type: "string", "x-mcp-header": "Region" },
168+
},
169+
required: ["region"]
170+
)
171+
172+
class << self
173+
def call(region:, server_context:)
174+
MCP::Tool::Response.new([{ type: "text", text: "Running in #{region}" }])
175+
end
176+
end
177+
end
178+
```
179+
180+
The annotation must be a non-empty HTTP token, unique among the tool's annotations regardless of case,
181+
and sit on a `string`, `integer`, or `boolean` property reachable from the schema root through `properties` keys only
182+
(a `number` property is accepted as well, for compatibility with the conformance referee's fixtures, although the specification does not permit it).
183+
Prefer `-` to `_` inside the name: proxies such as nginx drop header fields whose names hold an underscore by default,
184+
and the request is then refused for its missing header.
185+
Conforming clients drop a tool whose annotations break these rules and send no headers for it, and the transport validates nothing for such a tool.
186+
187+
`StreamableHTTPTransport` enforces the server side before the tool runs: on a `tools/call` of the modern lifecycle,
188+
the `Mcp-Param-{Name}` header of each declared parameter must be present exactly when the body carries a value the client mirrors for it
189+
(a string, a boolean, a finite float, or an integer within the safe JavaScript range; a value with no header rendering, such as an object, is left to argument validation)
190+
and must agree with that value once a `=?base64?...?=` sentinel is decoded. A missing or disagreeing header,
191+
a header whose argument is absent or `null` in the body, a header holding a byte outside the field-value set (visible ASCII, space, and tab)
192+
without the sentinel, and a sentinel whose payload is not canonical Base64 or not UTF-8
193+
are refused with HTTP 400 and JSON-RPC error `-32020` (`HeaderMismatch`) naming the header and, except in the two encoding refusals, the argument, never their values.
194+
Integer and number parameters compare numerically when the header is a canonical decimal of at most 64 bytes, so a header of `42.0` agrees with a body value of `42`;
195+
the comparison reads plain decimals only, so a number another SDK's client mirrors in exponent form is refused unless it repeats this SDK's own rendering byte for byte.
196+
Headers for parameters without an annotation are ignored, and the handshake lifecycle (2025-11-25 and earlier) has no such headers.
197+
156198
## Tool Output Schemas
157199

158200
Tools can optionally define an `output_schema` to specify the expected structure of their results. This works similarly to how `input_schema` is defined and can be used in three ways.

‎lib/mcp.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ module MCP
1717
autoload :Elicitation, "mcp/elicitation"
1818
autoload :ErrorCodes, "mcp/error_codes"
1919
autoload :Icon, "mcp/icon"
20+
autoload :McpParamHeaders, "mcp/mcp_param_headers"
2021
autoload :Prompt, "mcp/prompt"
2122
autoload :RequestEnvelope, "mcp/request_envelope"
2223
autoload :Resource, "mcp/resource"

‎lib/mcp/client.rb‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
# frozen_string_literal: true
22

33
require_relative "client/elicitation"
4-
require_relative "client/mcp_param_headers"
54
require_relative "client/modern_envelope"
65
require_relative "client/oauth"
76
require_relative "client/stdio"
@@ -20,6 +19,11 @@ class Client
2019
# every response would otherwise be followed indefinitely, growing the retained pages with it.
2120
MAX_PAGES = 1_000
2221

22+
# The custom-header codec lived under this name until the server transport came to share it;
23+
# the name stays for code that referenced it.
24+
# @api private
25+
McpParamHeaders = MCP::McpParamHeaders
26+
2327
class ServerError < StandardError
2428
attr_reader :code, :data
2529

‎lib/mcp/client/http.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
require_relative "../methods"
77
require_relative "../protocol_deprecations"
88
require_relative "../version"
9-
require_relative "mcp_param_headers"
9+
require_relative "../mcp_param_headers"
1010
require_relative "modern_envelope"
1111

1212
module MCP

‎lib/mcp/client/mcp_param_headers.rb‎

Lines changed: 0 additions & 242 deletions
This file was deleted.

0 commit comments

Comments
 (0)