Skip to content

Commit 5f3a131

Browse files
committed
Require the Mcp-Method header on the modern path
## Motivation and Context The modern Streamable HTTP path validated the SEP-2243 mirror headers only when present: an absent `Mcp-Method` or `Mcp-Name` was silently tolerated. The 2026-07-28 specification requires `Mcp-Method` on every request and `Mcp-Name` on `tools/call`, `resources/read`, and `prompts/get`, and lists a missing required standard header among the validation failures a server MUST reject; the TypeScript SDK enforces presence with `-32020` the same way. Tolerating absence also defeats the headers' purpose silently: they exist so intermediaries can route and inspect requests without parsing bodies. A modern POST without `Mcp-Method`, or a name-bearing modern POST whose body carries a target name without `Mcp-Name`, now answers HTTP 400 with `-32020` naming the missing header, exactly like a mismatch. `Mcp-Name` stays unrequired when the body carries no target name, matching the TypeScript SDK. The bundled `MCP::Client::HTTP` already sends both headers on every modern request, so SDK-to-SDK traffic is unaffected. ## How Has This Been Tested? New tests in `test/mcp/server/transports/streamable_http_transport_test.rb` cover the missing `Mcp-Method` and missing `Mcp-Name` rejections, asserting the `-32020` code and the header name in the message. The `modern_rack_request` helper now mirrors a conforming client by deriving `Mcp-Method` from the body (with `method_header: nil` to omit it), so the existing modern-path tests exercise the requirement on every request. ## Breaking Changes None for conforming clients, which must already send these headers. Hand-rolled modern clients that omitted them are now rejected with `-32020` instead of being served; add the headers, or use the legacy lifecycle, to proceed.
1 parent 2d8210f commit 5f3a131

2 files changed

Lines changed: 73 additions & 16 deletions

File tree

‎lib/mcp/server/transports/streamable_http_transport.rb‎

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -593,23 +593,43 @@ def validate_modern_headers(request, body, header_version)
593593
)
594594
end
595595

596+
# `Mcp-Method` is required on every modern POST and `Mcp-Name` on the name-bearing methods:
597+
# the spec lists a missing required standard header among the validation failures that MUST be rejected,
598+
# and the TypeScript SDK enforces presence the same way. Absence cannot be treated as "nothing to compare":
599+
# the headers exist so intermediaries can route without parsing bodies, and a client that omits them
600+
# defeats that contract silently.
596601
method_header = request.env["HTTP_MCP_METHOD"]
597-
if method_header && method_header != body[:method]
602+
if method_header.to_s.empty?
603+
return header_mismatch_response(
604+
"Mcp-Method header is required on the modern path",
605+
body[:id],
606+
)
607+
end
608+
if method_header != body[:method]
598609
return header_mismatch_response(
599610
"Mcp-Method header value '#{method_header}' does not match body value '#{body[:method]}'",
600611
body[:id],
601612
)
602613
end
603614

604-
name_header = request.env["HTTP_MCP_NAME"]
605-
if name_header && NAME_BEARING_METHODS.include?(body[:method])
615+
if NAME_BEARING_METHODS.include?(body[:method])
606616
body_name = params.is_a?(Hash) ? params[:name] || params[:uri] : nil
607-
decoded_name = decode_header_value(name_header)
608-
if body_name && decoded_name != body_name
609-
return header_mismatch_response(
610-
"Mcp-Name header value '#{decoded_name}' does not match body value '#{body_name}'",
611-
body[:id],
612-
)
617+
name_header = request.env["HTTP_MCP_NAME"]
618+
if body_name
619+
if name_header.to_s.empty?
620+
return header_mismatch_response(
621+
"Mcp-Name header is required for `#{body[:method]}`",
622+
body[:id],
623+
)
624+
end
625+
626+
decoded_name = decode_header_value(name_header)
627+
if decoded_name != body_name
628+
return header_mismatch_response(
629+
"Mcp-Name header value '#{decoded_name}' does not match body value '#{body_name}'",
630+
body[:id],
631+
)
632+
end
613633
end
614634
end
615635

‎test/mcp/server/transports/streamable_http_transport_test.rb‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5340,6 +5340,31 @@ def string
53405340
assert_equal(-32020, JSON.parse(response[2][0]).dig("error", "code"))
53415341
end
53425342

5343+
test "modern POST without the Mcp-Method header returns 400 with -32020" do
5344+
# The header is required on every modern POST; a missing required standard header is
5345+
# a validation failure, matching the TypeScript SDK's enforcement.
5346+
response = @transport.handle_request(modern_rack_request(
5347+
modern_body("ping", {}),
5348+
method_header: nil,
5349+
))
5350+
5351+
assert_equal 400, response[0]
5352+
body = JSON.parse(response[2][0])
5353+
assert_equal(-32020, body.dig("error", "code"))
5354+
assert_includes body.dig("error", "message"), "Mcp-Method"
5355+
end
5356+
5357+
test "modern POST without the Mcp-Name header on a name-bearing method returns 400 with -32020" do
5358+
response = @transport.handle_request(modern_rack_request(
5359+
modern_body("tools/call", { name: "some_tool", arguments: {} }),
5360+
))
5361+
5362+
assert_equal 400, response[0]
5363+
body = JSON.parse(response[2][0])
5364+
assert_equal(-32020, body.dig("error", "code"))
5365+
assert_includes body.dig("error", "message"), "Mcp-Name"
5366+
end
5367+
53435368
test "modern POST decodes the base64 Mcp-Name sentinel and enforces the match" do
53445369
# `Mcp-Name` mirrors `params.uri` for `resources/read`; a non-ASCII value arrives
53455370
# wrapped in the `=?base64?...?=` sentinel produced by `MCP::Client::HTTP`.
@@ -5410,6 +5435,7 @@ def string
54105435

54115436
response = @transport.handle_request(modern_rack_request(
54125437
modern_body("tools/call", { name: "guarded_tool", arguments: {} }),
5438+
headers: { "HTTP_MCP_NAME" => "guarded_tool" },
54135439
))
54145440

54155441
assert_equal 400, response[0]
@@ -5600,13 +5626,24 @@ def create_rack_request_without_accept(method, path, headers, body = nil)
56005626
end
56015627

56025628
# Builds a POST request routed to the modern path via the `MCP-Protocol-Version` header.
5603-
def modern_rack_request(body, version: "2026-07-28", headers: {})
5604-
create_rack_request(
5605-
"POST",
5606-
"/",
5607-
{ "CONTENT_TYPE" => "application/json", "HTTP_MCP_PROTOCOL_VERSION" => version }.merge(headers),
5608-
body,
5609-
)
5629+
# Mirrors what a conforming modern client sends: `Mcp-Method` is required on every modern POST,
5630+
# so it defaults to the body's method. Pass `method_header: nil` to omit it
5631+
# (for tests of the requirement itself) or a String to send a specific value.
5632+
def modern_rack_request(body, version: "2026-07-28", headers: {}, method_header: :from_body)
5633+
derived_method = if method_header == :from_body
5634+
begin
5635+
parsed = JSON.parse(body)
5636+
parsed["method"] if parsed.is_a?(Hash)
5637+
rescue JSON::ParserError
5638+
nil
5639+
end
5640+
else
5641+
method_header
5642+
end
5643+
5644+
base_headers = { "CONTENT_TYPE" => "application/json", "HTTP_MCP_PROTOCOL_VERSION" => version }
5645+
base_headers["HTTP_MCP_METHOD"] = derived_method if derived_method
5646+
create_rack_request("POST", "/", base_headers.merge(headers), body)
56105647
end
56115648

56125649
# Builds a JSON-RPC body carrying the SEP-2575 modern `_meta` envelope.

0 commit comments

Comments
 (0)