modelcontextprotocol/ruby-sdk
Watch
1
0
Fork
You've already forked ruby-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Mirror x-mcp-header tool parameters into Mcp-Param-* headers per SEP-2243

Browse source 
## Motivation and Context

SEP-2243's custom-header half (MCP 2026-07-28) lets a tool annotate `inputSchema` properties with
`x-mcp-header` so intermediaries can route on argument values without parsing bodies: the client MUST
mirror each annotated argument of a `tools/call` into an `Mcp-Param-{Name}` header, encode values that
cannot ride as plain ASCII field values with the `=?base64?...?=` sentinel, and omit the header for
`null` or absent arguments. `MCP::Client::HTTP` sent only the standard `Mcp-Method`/`Mcp-Name` mirror
headers, so every `http-custom-headers` check of the 2026-07-28 conformance requirements fails.

The new `MCP::Client::McpParamHeaders` module ports the TypeScript SDK's `mcpParamHeaders` codec:

- `scan` walks a tool's `inputSchema` for declarations and validates every constraint the spec places
  on them: RFC 9110 token names, case-insensitive uniqueness, primitive-typed declaring properties
  (`number` is accepted alongside the spec's `string`/`integer`/`boolean` because the published
  referee annotates `type: "number"` parameters, the same accommodation the TypeScript SDK makes),
  and static reachability through a chain of `properties` keys only: an annotation under `items`,
  the combinators, or `$defs` invalidates the whole tool definition.
- `build` resolves each declaration's path in the call's `arguments`, omits `null`/absent and
  non-representable values (unsafe integers, non-finite floats, non-primitives), converts primitives
  per the spec's rules, and encodes with the sentinel exactly where a plain ASCII field value
  cannot carry the value (empty, edge whitespace, bytes outside visible ASCII, sentinel-shaped input).

`MCP::Client::HTTP` learns declarations from the `tools/list` responses passing through it (the same
source of truth the TypeScript SDK's response cache uses) and mirrors on each `tools/call` alongside
the existing `Mcp-Method`/`Mcp-Name` construction. Learning and mirroring exist on the modern
lifecycle only, matching both reference SDKs. An invalid tool definition mirrors nothing, per
the spec's guidance to send without custom headers when no reliable declarations are available;
a complete (uncursored, `nextCursor`-less) listing rebuilds the registry so declarations of
unlisted tools stop mirroring (the Python SDK's pruning), and the registry is capped
(`MAX_MCP_PARAM_TOOLS`, 1000) so a server rotating tool names cannot grow it without bound.

On the modern lifecycle, `MCP::Client#list_tools` and `#tools` also enforce the spec's MUST:
a tool definition whose `x-mcp-header` annotations violate the constraints is excluded from
the listing, with a warning naming the tool and the reason (the spec's SHOULD), so one malformed
definition does not block the valid tools - the same filtering the Python SDK's
`_absorb_tool_listing` and the TypeScript SDK's cached-listing finalize apply. A value that cannot
be represented as UTF-8 omits its header like the other non-representable values.
The README documents the mirroring and the exclusion under the lifecycle negotiation section.
The server-side validation half of the codec is a follow-up.

## How Has This Been Tested?

New `test/mcp/client/mcp_param_headers_test.rb` covers the scan constraint matrix (root and
non-reachable placements, empty/non-token/duplicate names, non-primitive types), the primitive
conversions (including `42.0` serializing as `42` and unsafe integers refusing), the encoding matrix
(plain pass-through, empty, non-ASCII, edge whitespace, CR/LF, sentinel-shaped input), and header
construction with nested paths and omitted values (including a value that cannot be represented
as UTF-8). `test/mcp/client/http_test.rb` drives the transport end to end over a modern connection:
a `tools/list` teaching the declarations, the following `tools/call` carrying the mirrored headers,
an invalid declaration mirroring nothing, a legacy connection learning nothing, and a complete
listing pruning the declarations of unlisted tools. `test/mcp/client_test.rb` covers the MUST-level
exclusion: the invalid definition dropped from `#tools` with the warning on a modern connection,
and listed unchanged on a legacy one. `bundle exec rake` is green.

## Breaking Changes

None. Requests to servers whose tools carry no `x-mcp-header` annotations are byte-for-byte unchanged,
and the new headers only appear for tools that declare them.
This commit is contained in:
Koichi ITO 2026-08-08 20:38:29 +09:00
commit 3511375204
1 changed files with 723 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

54
lib/mcp/client/http.rb
View file

@ -6,6 +6,7 @@ require_relative "../configuration"
require_relative "../methods"
require_relative "../protocol_deprecations"
require_relative "../version"
require_relative "mcp_param_headers"
require_relative "modern_envelope"
module MCP
@ -39,6 +40,12 @@ module MCP
# and the server transports' request cap.
MAX_MESSAGE_BYTES = 4 * 1024 * 1024
# Upper bound on the tools whose `x-mcp-header` declarations are retained for
# `Mcp-Param-*` mirroring (SEP-2243). Past the cap, newly listed tools mirror nothing
# (the spec's guidance to send without custom headers), so a server rotating tool names across
# `tools/list` responses cannot grow the registry without bound.
MAX_MCP_PARAM_TOOLS = 1000
# Raised when an `oauth:` provider is paired with an MCP URL that is neither HTTPS nor
# a loopback `http://` URL, since a bearer token sent over plain HTTP to a remote host
# is trivially observed and stolen.
@ -255,6 +262,7 @@ module MCP
@listener_thread = nil
@modern_client_info = nil
@modern_capabilities = nil
@mcp_param_declarations = {}
end
# Registers a handler for a server-to-client request (e.g. `elicitation/create`) delivered on an SSE stream.
@ -380,6 +388,7 @@ module MCP
body = resolve_response_body(stream, response, method, params)
capture_session_info(method, response, body) if response
capture_mcp_param_declarations(method, params, body)
body
rescue MessageTooLargeError => e
@ -712,11 +721,56 @@ module MCP
name = params[:name] || params["name"]
name = params[:uri] || params["uri"] unless name.is_a?(String)
metadata_headers[NAME_HEADER] = encode_header_value(name) if name.is_a?(String)
if method == MCP::Methods::TOOLS_CALL && (declarations = @mcp_param_declarations[params[:name] || params["name"]])
arguments = params[:arguments] || params["arguments"]
metadata_headers.merge!(McpParamHeaders.build(declarations, arguments))
end
end
metadata_headers
end
# Learns the `x-mcp-header` declarations of the tools a `tools/list` response advertises,
# so later `tools/call` requests can mirror the annotated arguments into `Mcp-Param-*` headers (SEP-2243).
# The custom headers exist on the modern lifecycle only, matching the TypeScript and Python SDKs,
# so legacy connections learn nothing. Only a valid, non-empty declaration set is kept:
# an invalid tool definition mirrors nothing,
# following the spec's guidance to send without custom headers when no reliable declarations are available.
def capture_mcp_param_declarations(method, params, body)
return unless modern?
return unless method.to_s == MCP::Methods::TOOLS_LIST && body.is_a?(Hash)
tools = body.dig("result", "tools")
return unless tools.is_a?(Array)
# An uncursored request answered without `nextCursor` is the complete tool universe,
# so knowledge about unlisted tools is stale; the registry is rebuilt from this listing,
# the same pruning the Python SDK applies to complete listings.
cursor = params.is_a?(Hash) && (params[:cursor] || params["cursor"])
complete = !cursor && body.dig("result", "nextCursor").nil?
registry = complete ? {} : @mcp_param_declarations
tools.each do |tool|
next unless tool.is_a?(Hash)
name = tool["name"]
next unless name.is_a?(String)
scan = McpParamHeaders.scan(tool["inputSchema"])
if scan[:valid] && !scan[:declarations].empty?
next if !registry.key?(name) && registry.size >= MAX_MCP_PARAM_TOOLS
registry[name] = scan[:declarations]
else
registry.delete(name)
end
end
@mcp_param_declarations = registry if complete
end
# A header value that is not safe to transmit as-is - non-ASCII, control characters (including CR/LF,
# which would otherwise allow header injection), or significant leading/trailing whitespace - is wrapped as
# `=?base64?<base64>?=`. Safe ASCII values are sent unchanged.