Bound the initialize request a session retains

## Motivation and Context

A stateful session keeps the `clientInfo` and `capabilities` of the `initialize` request that created it,
for as long as the session lives, and `initialize` is validated for shape only. The session count and
the idle timeout bound how many sessions exist, and `max_request_bytes` bounds one request, but nothing bounded
what each session retained, so the sessions together could retain up to `max_sessions` times `max_request_bytes`
of client-supplied data. The documentation described the session limits as bounding what sessions retain,
which held for their number and not for their data. The TypeScript and Python SDKs keep the initialize data
whole and bound neither.

The body of an `initialize` request in stateful mode is now bounded by a new `max_initialize_request_bytes:` keyword,
64 KiB by default, which leaves room for large `experimental` capabilities while an ordinary `initialize` is under 2 KiB.
A larger body is rejected with HTTP 413 before any session is created, so nothing over the bound is ever retained;
`nil` removes the bound, and stateless mode, which retains nothing, ignores it.

A byte bound alone does not tightly bound the memory a session keeps, because the parsed objects, not the bytes,
are what it keeps: a body made of many small values parses into far more objects than its size suggests.
The `params` of an `initialize` are therefore also limited to 1024 JSON values, counted in a walk that stops at the limit,
and a request over it is rejected the same way; an ordinary `initialize` holds a few dozen. Like `MAX_JSON_NESTING`,
this structural limit applies in stateful mode whatever `max_initialize_request_bytes` is, including `nil`,
so removing the byte bound does not reopen the object count; a keyword can follow if a real client ever needs more.
Together the two bound both the serialized input and the number of parsed values a session can retain,
and the documentation now states that budget instead of the earlier claim.

## How Has This Been Tested?

New tests in `test/mcp/server/transports/streamable_http_transport_test.rb` send an `initialize` over the bound,
one exactly at it and one a byte over, one under `nil`, and one in stateless mode, and check the 413,
that no session exists afterwards, and that a regular request larger than the bound is still governed by `max_request_bytes` alone.
Further tests send `params` over the value bound while under the byte bound, exactly at it and one value over,
a large number of values within it, the same over-bound `params` under `nil`, and in stateless mode,
and check that object keys are counted and that nested shapes are refused.
Against the previous library an `initialize` just under `max_request_bytes` creates a session that keeps it.
One more sends a representative `initialize` with several icons, every capability, and an `experimental` object of many members,
and checks that it is accepted well inside both bounds.

## Breaking Changes

Requests that earlier releases accepted are now refused at the new bounds: an `initialize` request larger than
64 KiB is refused in stateful mode unless `max_initialize_request_bytes:` is raised or set to `nil`, and one whose
`params` hold more than 1024 JSON values is refused in stateful mode.

Author: koic

docs/_server/transports.md

@@ -222,22 +222,36 @@ This mode is suitable for simple tool servers that do not need server-initiated
 
 ### Session Limits
 
-By default, stateful sessions are bounded so an `initialize` flood cannot retain sessions until memory is exhausted:
-they expire after `session_idle_timeout` seconds of inactivity (default 1800, i.e. 30 minutes) and the concurrent
-session count is capped at `max_sessions` (default 10000). A session's idle timer is reset by activity that touches it
-(a GET, or a regular-request POST), and expired sessions are collected by a background reaper roughly once a minute,
-so cleanup lags inactivity by up to that interval. At the cap, the transport first reclaims any already-expired slots
-and then, if still full, rejects a new `initialize` with HTTP 503 (it does not evict an existing session).
+By default, stateful sessions are bounded in three ways: they expire after `session_idle_timeout` seconds of inactivity
+(default 1800, i.e. 30 minutes), the concurrent session count is capped at `max_sessions` (default 10000),
+and the `initialize` request whose `clientInfo` and `capabilities` a session keeps may be at most `max_initialize_request_bytes` (default 64 KiB),
+with at most 1024 JSON values in its `params`; a larger one is rejected with HTTP 413 before any session is created.
+The byte bound can be raised or removed with `nil`, in which case `max_request_bytes` still caps the body; the value bound always applies,
+since a session keeps the parsed data and many small values parse into far more objects than their size suggests.
+Together they bound both the serialized input and the number of parsed values each of the `max_sessions` sessions can retain.
+A session's idle timer is reset by activity that touches it (a GET, or a regular-request POST), and expired sessions are collected by
+a background reaper roughly once a minute, so cleanup lags inactivity by up to that interval. At the cap, the transport first reclaims
+any already-expired slots and then, if still full, rejects a new `initialize` with HTTP 503 (it does not evict an existing session).
 
 ```ruby
 # Tune the limits
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: 900, max_sessions: 5000)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(
+  server,
+  session_idle_timeout: 900,
+  max_sessions: 5000,
+  max_initialize_request_bytes: 16 * 1024,
+)
 
-# Opt out of expiry and/or the cap (not recommended on internet-facing deployments)
-transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, session_idle_timeout: nil, max_sessions: nil)
+# Opt out of expiry and/or the caps (not recommended on internet-facing deployments)
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(
+  server,
+  session_idle_timeout: nil,
+  max_sessions: nil,
+  max_initialize_request_bytes: nil,
+)
 ```
 
-Stateless mode (`stateless: true`) retains no sessions, so neither limit applies to it. The same holds
+Stateless mode (`stateless: true`) retains no sessions, so none of these limits applies to it. The same holds
 for requests of the [modern lifecycle](/server/discover/#the-stateless-modern-lifecycle), which never create a session;
 their long-lived [`subscriptions/listen`](/server/subscriptions/) streams are bounded separately
 by `max_listen_subscriptions:`.

lib/mcp/server/transports/streamable_http_transport.rb

@@ -82,14 +82,27 @@ class InvalidJsonError < StandardError; end
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#timeouts
         DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT = 600
 
-        # Default upper bound on the JSON-RPC request body. `handle_post` reads the whole
-        # body into memory and parses it, so without a cap a single unauthenticated POST
-        # can allocate gigabytes and OOM the worker. 4 MiB comfortably
-        # fits a typical JSON-RPC request (a 4 MiB JSON string decodes to ~3 MiB of base64
-        # payload); raise `max_request_bytes:` for unusually large payloads. Matches the
-        # TypeScript SDK's 4 MB default.
+        # Default upper bound on the JSON-RPC request body. `handle_post` reads the whole body into memory and parses it,
+        # so without a cap a single unauthenticated POST can allocate gigabytes and OOM the worker. 4 MiB comfortably fits
+        # a typical JSON-RPC request (a 4 MiB JSON string decodes to ~3 MiB of base64 payload); raise `max_request_bytes:`
+        # for unusually large payloads. Matches the TypeScript SDK's 4 MB default.
         DEFAULT_MAX_REQUEST_BYTES = 4 * 1024 * 1024
 
+        # Bound on the body of an `initialize` request in stateful mode. Its `clientInfo` and `capabilities` are
+        # kept for the life of the session, so without a bound of its own each session could retain a whole
+        # `max_request_bytes` body and the retained total would be `max_sessions` times that. An ordinary
+        # `initialize` is under 2 KiB; 64 KiB leaves room for large `experimental` capabilities. Pass
+        # `max_initialize_request_bytes: nil` to opt out. The TypeScript and Python SDKs keep the initialize
+        # data whole with no bound of their own; this is the same kind of local safety limit as `max_request_bytes`.
+        DEFAULT_MAX_INITIALIZE_REQUEST_BYTES = 64 * 1024
+
+        # Bound on the number of JSON values (objects, arrays, keys, and scalars) in the `params` of an `initialize`
+        # request in stateful mode. A byte bound alone does not tightly bound the memory a session keeps: a body of
+        # many small values parses into far more objects than its size suggests, so the parsed structure is bounded
+        # as well. Like `MAX_JSON_NESTING`, it is a structural limit applied whatever `max_initialize_request_bytes`
+        # is, including `nil`. An ordinary `initialize` holds a few dozen values.
+        MAX_INITIALIZE_PARAMS_VALUES = 1_024
+
         # Conservative bound on JSON nesting depth, so a deeply nested body cannot exhaust
         # the stack or amplify parse cost (complements the byte cap).
         MAX_JSON_NESTING = 64
@@ -137,6 +150,12 @@ class InvalidJsonError < StandardError; end
         #   ownership is not enforced.
         # @param max_request_bytes [Integer] upper bound in bytes on a POST request body; larger
         #   requests are rejected with HTTP 413. Defaults to 4 MiB.
+        # @param max_initialize_request_bytes [Integer, nil] upper bound in bytes on the body of an `initialize`
+        #   request in stateful mode, whose `clientInfo` and `capabilities` the session keeps; a larger one is
+        #   rejected with HTTP 413 before any session is created. Defaults to `DEFAULT_MAX_INITIALIZE_REQUEST_BYTES`
+        #   (64 KiB), and `nil` disables this bound, leaving `max_request_bytes` as the only cap on the body; `params`
+        #   holding more than `MAX_INITIALIZE_PARAMS_VALUES` JSON values are rejected the same way either way.
+        #   Neither applies in stateless mode, which retains nothing.
         # @param max_listen_subscriptions [Integer, nil] cap on concurrent `subscriptions/listen`
         #   streams; a listen request past the cap is rejected with HTTP 503, and `nil` disables
         #   the cap.
@@ -168,6 +187,7 @@ def initialize(
           dns_rebinding_protection: true,
           session_request_validator: nil,
           max_request_bytes: DEFAULT_MAX_REQUEST_BYTES,
+          max_initialize_request_bytes: DEFAULT_MAX_INITIALIZE_REQUEST_BYTES,
           max_listen_subscriptions: DEFAULT_MAX_LISTEN_SUBSCRIPTIONS,
           max_resource_subscription_bytes: DEFAULT_MAX_RESOURCE_SUBSCRIPTION_BYTES,
           listen_keepalive_interval: DEFAULT_LISTEN_KEEPALIVE_INTERVAL,
@@ -233,6 +253,13 @@ def initialize(
 
           @max_request_bytes = max_request_bytes
 
+          if !max_initialize_request_bytes.nil? && !(max_initialize_request_bytes.is_a?(Integer) && max_initialize_request_bytes > 0)
+            raise ArgumentError, "max_initialize_request_bytes must be a positive Integer or nil"
+          end
+
+          # The bound guards what stateful sessions retain; stateless mode keeps none.
+          @max_initialize_request_bytes = stateless ? nil : max_initialize_request_bytes
+
           if !max_listen_subscriptions.nil? && !(max_listen_subscriptions.is_a?(Integer) && max_listen_subscriptions > 0)
             raise ArgumentError, "max_listen_subscriptions must be a positive Integer or nil"
           end
@@ -1356,6 +1383,16 @@ def handle_post(request, body_string: nil)
           end
 
           if initialize_request?(body)
+            # Checked before a session exists: the body's `clientInfo` and `capabilities` are what the session would keep,
+            # so an oversized `initialize` is refused outright instead of being stored and capped later.
+            if @max_initialize_request_bytes && body_string.bytesize > @max_initialize_request_bytes
+              return initialize_too_large_response(body[:id], "body exceeds #{@max_initialize_request_bytes} bytes")
+            end
+
+            if !@stateless && json_values_exceed?(body[:params], MAX_INITIALIZE_PARAMS_VALUES)
+              return initialize_too_large_response(body[:id], "params exceed #{MAX_INITIALIZE_PARAMS_VALUES} JSON values")
+            end
+
             if !@stateless && session_id
               # An `initialize` request carrying an `Mcp-Session-Id` header is either a duplicate
               # initialization attempt against a live session, or a retry against an unknown/expired
@@ -1584,6 +1621,45 @@ def payload_too_large_response
           )
         end
 
+        def initialize_too_large_response(request_id, reason)
+          json_rpc_error_response(
+            status: 413,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Payload too large: initialize request #{reason}",
+            id: request_id,
+          )
+        end
+
+        # Counts the JSON values in `value` (every object, array, object key, and scalar) and reports whether
+        # they exceed `limit`. The walk is iterative. Every value still queued is at least one more value,
+        # so `count + pending.size` never overstates the total, and a container is refused before its members are
+        # queued if they would take that sum past the limit; the walk therefore stops as soon as the limit is
+        # certain to be passed and never queues more than `limit` values, whatever the shape of the input.
+        def json_values_exceed?(value, limit)
+          count = 0
+          pending = [value]
+
+          until pending.empty?
+            current = pending.pop
+            count += 1
+
+            case current
+            when Hash
+              count += current.size
+              return true if count + pending.size + current.size > limit
+
+              pending.concat(current.values)
+            when Array
+              return true if count + pending.size + current.size > limit
+
+              pending.concat(current)
+            end
+            return true if count + pending.size > limit
+          end
+
+          false
+        end
+
         def parse_request_body(body_string)
           # `max_nesting` bounds parse depth; a too-deep body raises `JSON::NestingError`,
           # a subclass of `JSON::ParserError`, so it is caught below as a parse error.