Skip to content

Commit f39b1bf

Browse files
committed
Align modern envelope validation with the finalized spec
## Motivation and Context Two deviations from the finalized 2026-07-28 specification in the SEP-2575 envelope validation, both introduced against the frozen SEP text and overtaken by post-final spec changes: 1. `clientInfo` was treated as required. Spec PR modelcontextprotocol/modelcontextprotocol#3002 made it optional (clients SHOULD include it unless configured not to), and the TypeScript and Python SDKs validate only the `protocolVersion` + `clientCapabilities` pair. A conformant client configured not to identify itself was rejected. 2. A missing or mistyped envelope answered `-32600` Invalid Request. The spec maps missing required envelope fields to `-32602` Invalid params, and both reference SDKs answer with `-32602` naming the offending keys. Fixing these also corrects the era classification to match the reference SDKs: a request claims the modern lifecycle when `_meta` carries `io.modelcontextprotocol/protocolVersion` (the TypeScript envelope claim and the Python `_has_modern_envelope` are both single-key checks), and a claimed-but-incomplete envelope is now validated and rejected with `-32602` naming the missing keys instead of silently flowing through the legacy path. Legacy `_meta` usage without the claim key (`progressToken`, trace context) is classified exactly as before. Unchanged on purpose: the era-lock violations keep their codes (`-32600` for a modern envelope on a legacy-locked session, `-32022` for `initialize` on a modern-locked one), matching the Python SDK. ## How Has This Been Tested? `test/mcp/request_envelope_test.rb` now covers: classification by the claim key alone, a claimed-but-incomplete envelope staying modern, parsing without the optional `clientInfo` (reader returns `nil`), `-32602` with the offending key names for a missing `clientCapabilities` and for mistyped required and optional fields. `test/mcp/server_test.rb` covers the dispatch-level behavior: a claimed but incomplete envelope answers `-32602` naming the missing key, an envelope without `clientInfo` is served with `server_context.client_info` reading `nil`, and a claim-less request on a modern-locked session answers `-32602` naming the required keys. The stdio and Streamable HTTP transport tests assert the new code on their envelope-requirement paths. ## Breaking Changes None for conforming clients. Requests that were already rejected change error code (`-32600` to `-32602`, HTTP status 400 unchanged), and requests carrying the `protocolVersion` claim key with an incomplete envelope are now rejected as the spec mandates instead of being served as legacy requests. Envelopes without `clientInfo`, previously rejected, now succeed.
1 parent b2f8070 commit f39b1bf

6 files changed

Lines changed: 109 additions & 31 deletions

File tree

‎lib/mcp/request_envelope.rb‎

Lines changed: 29 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
module MCP
44
# The per-request `_meta` envelope of the stateless "modern" lifecycle (MCP 2026-07-28, SEP-2575).
5-
# The modern lifecycle has no `initialize` handshake: every request identifies its protocol version,
6-
# client, and client capabilities through reserved `_meta` keys, and the server validates
7-
# each request independently. Servers MUST NOT infer capabilities from prior requests,
8-
# which is why the envelope is a per-request value object rather than session state.
5+
# The modern lifecycle has no `initialize` handshake: every request identifies its protocol version
6+
# and client capabilities through reserved `_meta` keys (plus an optional client identity),
7+
# and the server validates each request independently. Servers MUST NOT infer capabilities from
8+
# prior requests, which is why the envelope is a per-request value object rather than session state.
99
#
1010
# https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
1111
class RequestEnvelope
@@ -22,26 +22,31 @@ class RequestEnvelope
2222
# finalized (spec PR modelcontextprotocol/modelcontextprotocol#3002). A server MAY omit it.
2323
SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo"
2424

25+
# `clientInfo` is deliberately absent: it became optional after the SEP was finalized
26+
# (spec PR modelcontextprotocol/modelcontextprotocol#3002), so servers MUST accept
27+
# envelopes without it. The TypeScript and Python SDKs validate the same required pair.
2528
REQUIRED_META_KEYS = [
2629
PROTOCOL_VERSION_META_KEY,
27-
CLIENT_INFO_META_KEY,
2830
CLIENT_CAPABILITIES_META_KEY,
2931
].freeze
3032

3133
class << self
32-
# A request is classified as modern only when the full REQUIRED triple is present,
33-
# matching the TypeScript SDK's `RequestMetaEnvelopeSchema` and the Python SDK's `_has_modern_envelope`.
34-
# A partial triple is treated as legacy so existing `_meta` usage (`progressToken`, trace context) keeps
35-
# flowing through the legacy path.
34+
# A request claims the modern lifecycle when its `_meta` carries `io.modelcontextprotocol/protocolVersion`,
35+
# matching the TypeScript SDK's envelope claim and the Python SDK's `_has_modern_envelope`.
36+
# Classification is deliberately looser than validation: a claimed-but-malformed envelope is
37+
# rejected by {parse!} with `-32602` instead of silently flowing through the legacy path,
38+
# while `_meta` without the claim key (`progressToken`, trace context) stays legacy.
3639
def modern?(params)
3740
meta = extract_meta(params)
3841
return false unless meta.is_a?(Hash)
3942

40-
REQUIRED_META_KEYS.all? { |key| !read(meta, key).nil? }
43+
!read(meta, PROTOCOL_VERSION_META_KEY).nil?
4144
end
4245

43-
# Parses and validates the envelope. `request` is only used to enrich the raised error;
44-
# callers dispatching notifications can omit it.
46+
# Parses and validates the envelope: `protocolVersion` and `clientCapabilities` are required,
47+
# `clientInfo` is optional. A missing or mistyped field is Invalid params (`-32602`) naming
48+
# the offending keys, the code and shape the spec mandates and the reference SDKs emit.
49+
# `request` is only used to enrich the raised error; callers dispatching notifications can omit it.
4550
def parse!(params, request: nil)
4651
meta = extract_meta(params)
4752
meta = {} unless meta.is_a?(Hash)
@@ -50,11 +55,17 @@ def parse!(params, request: nil)
5055
client_info = read(meta, CLIENT_INFO_META_KEY)
5156
client_capabilities = read(meta, CLIENT_CAPABILITIES_META_KEY)
5257

53-
unless protocol_version.is_a?(String) && client_info.is_a?(Hash) && client_capabilities.is_a?(Hash)
58+
invalid_keys = []
59+
invalid_keys << PROTOCOL_VERSION_META_KEY unless protocol_version.is_a?(String)
60+
invalid_keys << CLIENT_CAPABILITIES_META_KEY unless client_capabilities.is_a?(Hash)
61+
invalid_keys << CLIENT_INFO_META_KEY unless client_info.nil? || client_info.is_a?(Hash)
62+
63+
unless invalid_keys.empty?
5464
raise Server::RequestHandlerError.new(
55-
"Invalid Request: modern requests require `#{REQUIRED_META_KEYS.join("`, `")}` in `_meta`",
65+
"Invalid params: missing or invalid `#{invalid_keys.join("`, `")}` in `_meta`",
5666
request,
57-
error_type: :invalid_request,
67+
error_type: :invalid_params,
68+
error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
5869
)
5970
end
6071

@@ -87,9 +98,11 @@ def read(meta, key)
8798
end
8899
end
89100

101+
# `client_info` is `nil` when the client chose not to identify itself, which is legal:
102+
# it is self-reported data and MUST NOT drive behavior or security decisions anyway.
90103
attr_reader :protocol_version, :client_info, :client_capabilities, :log_level
91104

92-
def initialize(protocol_version:, client_info:, client_capabilities:, log_level: nil)
105+
def initialize(protocol_version:, client_capabilities:, client_info: nil, log_level: nil)
93106
@protocol_version = protocol_version
94107
@client_info = client_info
95108
@client_capabilities = client_capabilities

‎lib/mcp/server.rb‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -689,10 +689,14 @@ def lift_request_envelope(params, method:, session:)
689689

690690
RequestEnvelope.parse!(params, request: params)
691691
elsif era == :modern
692+
# A claim-less request on a modern session is a malformed envelope, not a malformed request:
693+
# the spec maps missing required envelope fields to Invalid params (`-32602`),
694+
# and the reference SDKs answer it naming the missing keys.
692695
raise RequestHandlerError.new(
693-
"Invalid Request: modern sessions require the SEP-2575 `_meta` envelope",
696+
"Invalid params: missing or invalid `#{RequestEnvelope::REQUIRED_META_KEYS.join("`, `")}` in `_meta`",
694697
params,
695-
error_type: :invalid_request,
698+
error_type: :invalid_params,
699+
error_code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
696700
)
697701
end
698702
end

‎test/mcp/request_envelope_test.rb‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,9 @@ class RequestEnvelopeTest < ActiveSupport::TestCase
1212
assert_equal "io.modelcontextprotocol/logLevel", RequestEnvelope::LOG_LEVEL_META_KEY
1313
end
1414

15-
test ".modern? returns true when the full required triple is present" do
15+
test ".modern? returns true when the protocolVersion claim key is present" do
1616
assert RequestEnvelope.modern?(modern_params)
17+
assert RequestEnvelope.modern?({ _meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" } })
1718
end
1819

1920
test ".modern? returns true for string keys" do
@@ -28,11 +29,13 @@ class RequestEnvelopeTest < ActiveSupport::TestCase
2829
assert RequestEnvelope.modern?(params)
2930
end
3031

31-
test ".modern? returns false for a partial triple" do
32+
test ".modern? stays true for a claimed but incomplete envelope" do
33+
# A claimed envelope must be validated by `parse!` (`-32602`), never silently served as legacy,
34+
# matching the TypeScript and Python classifiers.
3235
params = modern_params
3336
params[:_meta].delete(:"io.modelcontextprotocol/clientCapabilities")
3437

35-
refute RequestEnvelope.modern?(params)
38+
assert RequestEnvelope.modern?(params)
3639
end
3740

3841
test ".modern? returns false for legacy _meta entries such as progressToken" do
@@ -75,26 +78,55 @@ class RequestEnvelopeTest < ActiveSupport::TestCase
7578
assert_equal "2025-11-25", error.error_data[:requested]
7679
end
7780

78-
test ".parse! raises an invalid request error when the triple is incomplete" do
81+
test ".parse! accepts an envelope without the optional clientInfo" do
82+
# `clientInfo` became optional after the SEP was finalized (spec PR #3002);
83+
# a conformant client configured not to identify itself must not be rejected.
7984
params = modern_params
8085
params[:_meta].delete(:"io.modelcontextprotocol/clientInfo")
8186

87+
envelope = RequestEnvelope.parse!(params)
88+
89+
assert_nil envelope.client_info
90+
assert_equal "2026-07-28", envelope.protocol_version
91+
assert_equal({ elicitation: {} }, envelope.client_capabilities)
92+
end
93+
94+
test ".parse! raises Invalid params naming the missing key when clientCapabilities is absent" do
95+
params = modern_params
96+
params[:_meta].delete(:"io.modelcontextprotocol/clientCapabilities")
97+
8298
error = assert_raises(Server::RequestHandlerError) do
8399
RequestEnvelope.parse!(params)
84100
end
85101

86-
assert_equal :invalid_request, error.error_type
102+
assert_equal :invalid_params, error.error_type
103+
assert_equal JsonRpcHandler::ErrorCode::INVALID_PARAMS, error.error_code
104+
assert_includes error.message, "io.modelcontextprotocol/clientCapabilities"
105+
refute_includes error.message, "io.modelcontextprotocol/protocolVersion"
87106
end
88107

89-
test ".parse! raises an invalid request error when a triple member has the wrong type" do
108+
test ".parse! raises Invalid params when a required field has the wrong type" do
90109
params = modern_params
91110
params[:_meta][:"io.modelcontextprotocol/clientCapabilities"] = "not-a-hash"
92111

93112
error = assert_raises(Server::RequestHandlerError) do
94113
RequestEnvelope.parse!(params)
95114
end
96115

97-
assert_equal :invalid_request, error.error_type
116+
assert_equal :invalid_params, error.error_type
117+
assert_equal JsonRpcHandler::ErrorCode::INVALID_PARAMS, error.error_code
118+
end
119+
120+
test ".parse! raises Invalid params when the optional clientInfo has the wrong type" do
121+
params = modern_params
122+
params[:_meta][:"io.modelcontextprotocol/clientInfo"] = "not-a-hash"
123+
124+
error = assert_raises(Server::RequestHandlerError) do
125+
RequestEnvelope.parse!(params)
126+
end
127+
128+
assert_equal :invalid_params, error.error_type
129+
assert_includes error.message, "io.modelcontextprotocol/clientInfo"
98130
end
99131

100132
private

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -617,7 +617,7 @@ class StdioTransportTest < ActiveSupport::TestCase
617617
])
618618

619619
refute responses[0].key?(:error)
620-
assert_equal JsonRpcHandler::ErrorCode::INVALID_REQUEST, responses[1].dig(:error, :code)
620+
assert_equal JsonRpcHandler::ErrorCode::INVALID_PARAMS, responses[1].dig(:error, :code)
621621
end
622622

623623
test "#send_request raises on a modern-locked session" do

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5425,7 +5425,7 @@ def string
54255425
))
54265426

54275427
assert_equal 400, response[0]
5428-
assert_equal(-32600, JSON.parse(response[2][0]).dig("error", "code"))
5428+
assert_equal(-32602, JSON.parse(response[2][0]).dig("error", "code"))
54295429
end
54305430

54315431
test "modern POST maps a missing client capability to 400 with -32021" do

‎test/mcp/server_test.rb‎

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,30 @@ class ServerTest < ActiveSupport::TestCase
295295
assert_equal "2027-01-01", response.dig(:error, :data, :requested)
296296
end
297297

298-
test "#handle treats a partial modern triple as a legacy request" do
298+
test "#handle rejects a claimed but incomplete envelope with -32602 naming the missing key" do
299+
# A request carrying the `protocolVersion` claim key must be validated, never silently served as legacy:
300+
# the spec maps missing required envelope fields to Invalid params, and the TypeScript and Python classifiers
301+
# answer the same way.
302+
server = Server.new(name: "modern_test", tools: [])
303+
server.define_tool(name: "modern_tool") { Tool::Response.new([{ type: "text", text: "ok" }]) }
304+
305+
response = server.handle({
306+
jsonrpc: "2.0",
307+
method: "tools/call",
308+
id: 1,
309+
params: {
310+
name: "modern_tool",
311+
arguments: {},
312+
_meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" },
313+
},
314+
})
315+
316+
assert_equal JsonRpcHandler::ErrorCode::INVALID_PARAMS, response.dig(:error, :code)
317+
assert_includes response.dig(:error, :message), "io.modelcontextprotocol/clientCapabilities"
318+
end
319+
320+
test "#handle serves an envelope without the optional clientInfo" do
321+
# `clientInfo` became optional after the SEP was finalized (spec PR #3002).
299322
server = Server.new(name: "modern_test", tools: [])
300323
received_context = nil
301324
server.define_tool(name: "modern_tool") do |server_context:|
@@ -310,12 +333,17 @@ class ServerTest < ActiveSupport::TestCase
310333
params: {
311334
name: "modern_tool",
312335
arguments: {},
313-
_meta: { "io.modelcontextprotocol/protocolVersion": "2026-07-28" },
336+
_meta: {
337+
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
338+
"io.modelcontextprotocol/clientCapabilities": { elicitation: {} },
339+
},
314340
},
315341
})
316342

317343
refute_nil response[:result]
318-
refute_predicate received_context, :modern?
344+
assert_predicate received_context, :modern?
345+
assert_nil received_context.client_info
346+
assert_equal({ elicitation: {} }, received_context.client_capabilities)
319347
end
320348

321349
test "#handle requires the envelope for requests on a modern-locked session" do
@@ -328,7 +356,8 @@ class ServerTest < ActiveSupport::TestCase
328356
session: session,
329357
)
330358

331-
assert_equal JsonRpcHandler::ErrorCode::INVALID_REQUEST, response.dig(:error, :code)
359+
assert_equal JsonRpcHandler::ErrorCode::INVALID_PARAMS, response.dig(:error, :code)
360+
assert_includes response.dig(:error, :message), "io.modelcontextprotocol/protocolVersion"
332361
end
333362

334363
test "#handle rejects initialize on a modern-locked session with -32022" do

0 commit comments

Comments
 (0)