Skip to content

Commit 02905d6

Browse files
authored
Merge pull request #654 from koic/validate_mcp_param_headers_against_the_tool_call_body
Validate `Mcp-Param-*` headers against the tool call body
2 parents 48c0cc9 + 5d54cee commit 02905d6

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)