mcp 1.6.1 → 1.8.0

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require_relative "../../result_type"
 require_relative "../../transport"
 
@@ -48,6 +49,20 @@ module MCP
         # pass `max_listen_subscriptions: nil` to opt out.
         DEFAULT_MAX_LISTEN_SUBSCRIPTIONS = 1_000
 
+        # Bound on the bytes of resource URIs one `subscriptions/listen` request may name in `resourceSubscriptions`
+        # (the sum of their byte lengths after duplicates are dropped). The URIs are held for the life of the stream,
+        # so without a bound each stream could retain a request body's worth of URIs and the retained total would be
+        # `max_listen_subscriptions` times `max_request_bytes`. 64 KiB names about a thousand ordinary URIs;
+        # pass `max_resource_subscription_bytes: nil` to opt out. The specification sets no limit, nor do the TypeScript
+        # and Python SDKs; this is the same kind of local safety limit as `max_request_bytes`.
+        DEFAULT_MAX_RESOURCE_SUBSCRIPTION_BYTES = 64 * 1024
+
+        # Bound on the number of distinct resource URIs one `subscriptions/listen` request may name. A byte bound does
+        # not tightly bound the memory a stream keeps, since each retained URI carries a fixed per-object cost however
+        # short it is, so the count is bounded as well. Like `MAX_JSON_NESTING`, it is a structural limit applied
+        # whatever `max_resource_subscription_bytes` is, including `nil`.
+        MAX_RESOURCE_SUBSCRIPTION_URIS = 1_024
+
         # Distinguishes "argument omitted, apply the secure default" from an explicit `nil` (opt out of expiry).
         UNSET_IDLE_TIMEOUT = Object.new.freeze
         private_constant :UNSET_IDLE_TIMEOUT
@@ -67,14 +82,27 @@ module MCP
         # 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
@@ -93,6 +121,18 @@ module MCP
         # 15-second default; pass `listen_keepalive_interval: nil` when an upstream proxy pings the stream.
         DEFAULT_LISTEN_KEEPALIVE_INTERVAL = 15
 
+        # The shortest wait the listen keepalive makes when a stream's deadline is nearer than the interval.
+        LISTEN_DEADLINE_WAIT_FLOOR = 0.01
+
+        # How long an authenticated SSE stream may stay open before it is closed and the client has to present its token again.
+        # Bearer enforcement is per HTTP request, and a stream is one request, so without this an open stream outlives
+        # every later token check. The token's own expiry usually arrives first; the cap is what bounds a stream whose token reports
+        # no expiry at all (`exp` is optional in an RFC 7662 introspection response). Neither the specification nor the reference SDKs
+        # put a ceiling on a stream, so the value comes from this transport instead: it matches `DEFAULT_SESSION_IDLE_TIMEOUT`,
+        # because a handshake session already ends after that long without a request, which would leave a longer cap inert,
+        # and a sessionless `subscriptions/listen` stream has no other bound at all.
+        DEFAULT_MAX_STREAM_LIFETIME = DEFAULT_SESSION_IDLE_TIMEOUT
+
         # Creates a Streamable HTTP transport that can be mounted as a Rack app.
         #
         # @param server [MCP::Server] the server whose requests this transport dispatches.
@@ -122,9 +162,19 @@ module MCP
         #   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.
+        # @param max_resource_subscription_bytes [Integer, nil] bound on the total byte length of the distinct
+        #   resource URIs one `subscriptions/listen` request names in `resourceSubscriptions`; a request over
+        #   the bound is rejected with HTTP 400 and JSON-RPC `-32602`.
+        #   Defaults to `DEFAULT_MAX_RESOURCE_SUBSCRIPTION_BYTES` (64 KiB), and `nil` disables the bound.
         # @param listen_keepalive_interval [Numeric, nil] seconds between SSE keepalive comment frames
         #   on a `subscriptions/listen` stream; the periodic write frees the stream's slot when the peer
         #   has gone away. Defaults to `DEFAULT_LISTEN_KEEPALIVE_INTERVAL` (15); pass `nil` to disable
@@ -138,6 +188,28 @@ module MCP
         # @param server_to_client_request_timeout [Numeric] seconds a server-to-client request waits for its
         #   response before the transport stops waiting and raises `MCP::Server::RequestTimeoutError`.
         #   Defaults to `DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT` (600); individual calls override it with `timeout:`.
+        # @param token_verifier [#verify, nil] enables built-in OAuth 2.1 bearer enforcement: anything responding to
+        #   `verify(token) -> MCP::Server::OAuth::AccessToken | nil` (see `MCP::Server::OAuth::TokenVerifier` for
+        #   the contract and the built-in JWT/introspection implementations). Every POST, GET, and DELETE is verified
+        #   per HTTP request; SSE streams are verified when opened, matching the per-request model of the Python and
+        #   TypeScript SDKs. The verified token reaches handlers as `server_context.auth_info`. Without a verifier
+        #   the transport still honors a token placed in `env["mcp.auth_info"]` by `MCP::Server::OAuth::Middleware`
+        #   or a custom integration.
+        # @param required_scopes [Array<String>] scopes the token must include, all of them; a shortfall is
+        #   rejected with HTTP 403 `insufficient_scope` (step-up). Requires `token_verifier`.
+        # @param resource_metadata [MCP::Server::OAuth::ProtectedResourceMetadata, nil] the RFC 9728 document describing
+        #   this resource; its well-known URL and `scopes_supported` feed the `WWW-Authenticate` challenges.
+        #   The document itself is served above the transport by `MCP::Server::OAuth::ProtectedResourceMetadataMiddleware`.
+        #   Requires `token_verifier`.
+        # @param resource_metadata_url [String, nil] explicit challenge URL when the metadata document is served elsewhere;
+        #   wins over `resource_metadata.well_known_url`. Requires `token_verifier`.
+        # @param scope_matcher [#call, nil] optional `(required_scope, granted_scopes) -> Boolean` for hierarchical scope schemes;
+        #   defaults to exact membership. Requires `token_verifier`.
+        # @param max_stream_lifetime [Numeric, nil] seconds an authenticated SSE stream may stay open before it is closed
+        #   and the client must present its token again, `DEFAULT_MAX_STREAM_LIFETIME` (1800) by default. The token's own
+        #   expiry closes the stream earlier when it comes first; the cap is what bounds a stream whose token reports no
+        #   expiry. `nil` removes the cap, leaving such a stream open until either side disconnects. Streams opened without
+        #   a token are never capped.
         def initialize(
           server,
           stateless: false,
@@ -149,10 +221,18 @@ module MCP
           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,
           serve_subscriptions_listen: true,
-          server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT
+          server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT,
+          token_verifier: nil,
+          required_scopes: [],
+          resource_metadata: nil,
+          resource_metadata_url: nil,
+          scope_matcher: nil,
+          max_stream_lifetime: DEFAULT_MAX_STREAM_LIFETIME
         )
           super(server)
           # Maps `session_id` to `{ get_sse_stream: stream_object, server_session: ServerSession, last_active_at: float_from_monotonic_clock, origin: origin_header }`.
@@ -170,8 +250,9 @@ module MCP
           @pending_responses = {}
 
           # Maps a key the transport mints for each `subscriptions/listen` stream to
-          # `{ request_id: listen_request_id, stream: stream_object, filter: honored_subscription_filter, active: boolean,
-          # write_mutex: Mutex, keepalive_wakeup: ConditionVariable }` (SEP-2575). The request id is the client's,
+          # `{ request_id: listen_request_id, stream: stream_object, filter: honored_list_changed_flags,
+          # resource_uris: Set_of_honored_resource_uris, active: boolean, write_mutex: Mutex,
+          # keepalive_wakeup: ConditionVariable }` (SEP-2575). The request id is the client's,
           # unique only among that client's own in-flight requests, so it stamps `subscriptionId` but cannot serve as the key:
           # two clients may pick the same one. Whoever removes an entry signals `keepalive_wakeup` under `@mutex`,
           # so the stream's keepalive thread ends with its slot instead of sleeping out its interval.
@@ -212,12 +293,25 @@ module MCP
 
           @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
 
           @max_listen_subscriptions = max_listen_subscriptions
 
+          if !max_resource_subscription_bytes.nil? && !(max_resource_subscription_bytes.is_a?(Integer) && max_resource_subscription_bytes > 0)
+            raise ArgumentError, "max_resource_subscription_bytes must be a positive Integer or nil"
+          end
+
+          @max_resource_subscription_bytes = max_resource_subscription_bytes
+
           if !listen_keepalive_interval.nil? && !(listen_keepalive_interval.is_a?(Numeric) && listen_keepalive_interval > 0)
             raise ArgumentError, "listen_keepalive_interval must be a positive number or nil"
           end
@@ -231,6 +325,32 @@ module MCP
 
           @server_to_client_request_timeout = server_to_client_request_timeout
 
+          if token_verifier
+            @oauth_authenticator = OAuth::Authenticator.new(
+              token_verifier: token_verifier,
+              required_scopes: required_scopes,
+              resource_metadata: resource_metadata,
+              resource_metadata_url: resource_metadata_url,
+              scope_matcher: scope_matcher,
+            )
+          elsif !Array(required_scopes).empty? || resource_metadata || resource_metadata_url || scope_matcher
+            # OAuth options without a verifier would look protected while enforcing nothing.
+            raise ArgumentError,
+              "required_scopes, resource_metadata, resource_metadata_url, and scope_matcher require token_verifier"
+          else
+            @oauth_authenticator = nil
+          end
+
+          unless max_stream_lifetime.nil? || (max_stream_lifetime.is_a?(Numeric) && max_stream_lifetime.positive?)
+            raise ArgumentError, "max_stream_lifetime must be a positive number or nil"
+          end
+
+          @max_stream_lifetime = max_stream_lifetime
+
+          # `close` sets the flag and signals the reaper under `@mutex`, so the reaper leaves its wait at once instead of
+          # being killed in the middle of a reap.
+          @closing = false
+          @reaper_wakeup = ConditionVariable.new
           start_reaper_thread if @session_idle_timeout
         end
 
@@ -239,6 +359,11 @@ module MCP
         REQUIRED_GET_ACCEPT_TYPES = ["text/event-stream"].freeze
         STREAM_WRITE_ERRORS = [IOError, Errno::EPIPE, Errno::ECONNRESET].freeze
         SESSION_REAP_INTERVAL = 60
+        # Seconds `close` waits for a reap in progress to finish closing its streams before it kills the reaper.
+        REAPER_JOIN_TIMEOUT = 5
+        # How long `close` waits in all for the closing results of the open `subscriptions/listen` streams
+        # before closing the streams still open without one.
+        LISTEN_TEARDOWN_TIMEOUT = 5
 
         # Loopback hosts always accepted by DNS rebinding protection. A locally bound MCP server (the canonical pattern) is
         # protected out of the box; non-loopback deployments widen the list via `allowed_hosts:`.
@@ -285,6 +410,11 @@ module MCP
           rebinding_error = validate_dns_rebinding(request)
           return rebinding_error if rebinding_error
 
+          # Bearer enforcement runs after the DNS-rebinding rejection (which must stay the cheapest gate and
+          # never trigger verifier work) and before any body read, so an unauthenticated request costs no parsing.
+          auth_error = authenticate_request(request)
+          return auth_error if auth_error
+
           # Header-primary era routing (SEP-2575). An `MCP-Protocol-Version` header naming a version outside
           # every supported list routes to the sessionless modern path, so an unknown future version receives
           # the spec-mandated `-32022` with the supported list instead of the legacy path's generic invalid-request error.
@@ -332,8 +462,28 @@ module MCP
           end
         end
 
+        # The reaper is asked to stop and joined before it is killed: `reap_expired_sessions` removes expired sessions
+        # under `@mutex` and closes their streams after releasing it, and a kill landing between the two would leave
+        # those streams open with no session left to find them by. Waking the reaper ends its wait at once, and the join
+        # lets a reap already past its removal finish its closes before the rest of the transport is torn down.
+        # The join is bounded, so a stream whose close never returns cannot hold the shutdown, and a reaper that died
+        # with a `StandardError` does not stop the teardown below: `join` re-raises the exception a thread died with,
+        # which is not this method's to raise. A reaper still alive after the wait is killed as before, leaving
+        # the streams of that reap it had not closed yet as they were.
         def close
-          @reaper_thread&.kill
+          reaper = @mutex.synchronize do
+            @closing = true
+            @reaper_wakeup.signal
+            @reaper_thread
+          end
+
+          begin
+            reaper&.join(REAPER_JOIN_TIMEOUT)
+          rescue StandardError
+            # The reaper is gone either way; the exception that ended it is not this method's to report.
+          end
+
+          reaper.kill if reaper&.alive?
           @reaper_thread = nil
 
           teardown_listen_subscriptions
@@ -405,7 +555,7 @@ module MCP
               next
             end
 
-            active_stream(session, related_request_id: related_request_id)
+            active_stream(session, streams_to_close, related_request_id: related_request_id)
           end
 
           close_streams(streams_to_close)
@@ -422,14 +572,16 @@ module MCP
             expired_session_ids = []
 
             collected = @sessions.filter_map do |session_id, session|
-              next unless (stream = session[:get_sse_stream])
+              next unless session[:get_sse_stream]
 
               if session_expired?(session)
                 expired_session_ids << session_id
                 next
               end
 
-              [session_id, stream]
+              stream = active_stream(session, streams_to_close)
+
+              [session_id, stream] if stream
             end
 
             expired_session_ids.each do |session_id|
@@ -460,6 +612,11 @@ module MCP
         # Removes a stream that failed to accept a write. A request-scoped stream is dropped on its own;
         # a session-scoped (GET SSE) failure tears down the whole session. The `@sessions` mutation runs
         # under `@mutex`, and the affected streams are closed outside it.
+        #
+        # Only the GET stream the session still holds takes the session down with it, judged under the same hold of
+        # the lock that removes the session: the failed write may have been picked for a stream that was detached since,
+        # because its token expired and the client reopened, and the stream opened in its place must stay. A failed
+        # stream the session no longer holds was closed by whichever path detached it, so there is nothing left to do.
         def drop_broken_stream(session_id, stream, related_request_id)
           streams_to_close = []
 
@@ -473,7 +630,7 @@ module MCP
               session[:post_request_streams].delete(related_request_id) if registered.equal?(stream)
 
               streams_to_close << stream
-            else
+            elsif session && session[:get_sse_stream].equal?(stream)
               cleanup_and_collect_stream(session_id, streams_to_close)
             end
           end
@@ -531,6 +688,7 @@ module MCP
 
           # Register the pending response and resolve the stream under the lock, but perform
           # the write outside it so a stalled reader cannot block every other session on `@mutex`.
+          streams_to_close = []
           stream = @mutex.synchronize do
             unless (session = @sessions[session_id])
               raise "Session not found: #{session_id}."
@@ -538,9 +696,11 @@ module MCP
 
             @pending_responses[request_id] = { queue: pending_response, session_id: session_id }
 
-            active_stream(session, related_request_id: related_request_id)
+            active_stream(session, streams_to_close, related_request_id: related_request_id)
           end
 
+          close_streams(streams_to_close)
+
           sent = false
           if stream
             begin
@@ -641,10 +801,18 @@ module MCP
 
         private
 
+        # The wait between reaps is a condition variable wait under `@mutex` rather than a sleep, so `close` can end it
+        # by signalling; a spurious wakeup only runs a reap early.
         def start_reaper_thread
           @reaper_thread = Thread.new do
             loop do
-              sleep(SESSION_REAP_INTERVAL)
+              closing = @mutex.synchronize do
+                @reaper_wakeup.wait(@mutex, SESSION_REAP_INTERVAL) unless @closing
+                @closing
+              end
+
+              break if closing
+
               reap_expired_sessions
             rescue StandardError => e
               MCP.configuration.exception_reporter.call(e, error: "Session reaper error")
@@ -743,13 +911,13 @@ module MCP
           # to the dispatcher as unimplemented (404 with `-32601`) - the refusal a host that cannot
           # serve an open SSE stream needs, instead of a `Proc` body it can never call.
           if body[:method] == Methods::SUBSCRIPTIONS_LISTEN && serves_subscriptions_listen?
-            return handle_subscriptions_listen(body)
+            return handle_subscriptions_listen(body, auth_info: request.env[OAuth::ENV_KEY])
           end
 
           session = modern_session
           notifications = @mutex.synchronize { @modern_request_sinks[session.session_id] = [] }
           begin
-            response = @server.handle(body, session: session)
+            response = @server.handle(body, session: session, auth_info: request.env[OAuth::ENV_KEY])
           ensure
             @mutex.synchronize { @modern_request_sinks.delete(session.session_id) }
           end
@@ -841,7 +1009,7 @@ module MCP
         # (= the listen request id) in `_meta`. A graceful teardown (transport `close`) sends a `SubscriptionsListenResult`
         # response; an abrupt disconnect sends nothing. A keepalive comment frame is written every
         # `listen_keepalive_interval` seconds so a dropped connection frees its slot.
-        def handle_subscriptions_listen(body)
+        def handle_subscriptions_listen(body, auth_info: nil)
           request_id = body[:id]
           params = body[:params]
 
@@ -850,6 +1018,14 @@ module MCP
             return invalid_request_response("Invalid Request: subscriptions/listen requires an id")
           end
 
+          # The id is echoed in every message of the stream, so one that cannot be written back as JSON
+          # (a String holding bytes that are not valid UTF-8 parses, but does not generate) is refused here,
+          # while the refusal can still answer with a null id, rather than surfacing as a failed write after
+          # the stream has been registered.
+          unless json_encodable?(request_id)
+            return invalid_request_response("Invalid Request: subscriptions/listen id must be valid UTF-8")
+          end
+
           begin
             if RequestEnvelope.modern?(params)
               RequestEnvelope.parse!(params, request: params)
@@ -876,6 +1052,15 @@ module MCP
             )
           end
 
+          if (problem = resource_subscriptions_problem(filter))
+            return json_rpc_error_response(
+              status: 400,
+              code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+              message: "Invalid params: subscriptions/listen #{problem}",
+              id: request_id,
+            )
+          end
+
           # Best-effort cap check before committing to the SSE response; the registration inside
           # `listen_sse_body` re-checks atomically for the race between two concurrent listens
           # crossing the cap together.
@@ -883,7 +1068,43 @@ module MCP
             return too_many_listen_subscriptions_response(request_id)
           end
 
-          [200, SSE_HEADERS.dup, listen_sse_body(request_id, honored_filter(filter))]
+          honored = honored_filter(filter)
+
+          # The acknowledgement echoes the honored filter, whose resource URIs are client-supplied strings,
+          # so it is encoded before the stream is committed to: a URI that cannot be written as JSON is
+          # refused with a 400 instead of failing the first write after the stream was registered.
+          unless (acknowledgement = listen_acknowledgement_json(request_id, honored))
+            return json_rpc_error_response(
+              status: 400,
+              code: JsonRpcHandler::ErrorCode::INVALID_PARAMS,
+              message: "Invalid params: subscriptions/listen `notifications` must be valid UTF-8",
+              id: request_id,
+            )
+          end
+
+          [200, SSE_HEADERS.dup, listen_sse_body(request_id, honored, acknowledgement, auth_info)]
+        end
+
+        # The `notifications/subscriptions/acknowledged` frame for a listen stream as JSON, or `nil` when
+        # the request id or the honored filter holds a string JSON cannot encode.
+        def listen_acknowledgement_json(request_id, honored)
+          {
+            jsonrpc: "2.0",
+            method: Methods::NOTIFICATIONS_SUBSCRIPTIONS_ACKNOWLEDGED,
+            params: {
+              notifications: honored,
+              _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
+            },
+          }.to_json
+        rescue JSON::GeneratorError
+          nil
+        end
+
+        def json_encodable?(value)
+          value.to_json
+          true
+        rescue JSON::GeneratorError
+          false
         end
 
         def listen_subscriptions_full?
@@ -942,14 +1163,25 @@ module MCP
         # The entry is keyed by an identifier minted here, not by the request id: that id is unique only among
         # the requesting client's own in-flight requests, and two clients that pick the same one must each get
         # their stream, stamped with the id they sent.
-        def listen_sse_body(request_id, honored)
+        def listen_sse_body(request_id, honored, acknowledgement, auth_info = nil)
           ListenStreamBody.new do |stream|
             subscription_key = SecureRandom.uuid
             subscription = nil
+            # The entry keeps the list-changed flags of the honored filter and the URIs as a frozen Set, both built ahead of the registry lock:
+            # delivery looks each notification's URI up in constant time, so neither the matching cost nor the lock hold grows with
+            # the number of URIs a stream named. The entry does not keep the Array the acknowledgement echoes; that one lives only as long as
+            # the host keeps this response body.
+            entry_filter = honored.reject { |name, _value| name == :resourceSubscriptions }
+            resource_uris = Set.new(honored[:resourceSubscriptions] || []).freeze
+
             @mutex.synchronize do
               unless @max_listen_subscriptions && @listen_subscriptions.size >= @max_listen_subscriptions
+                # The expiry of the token that authenticated the listen request is kept with the stream
+                # so the keepalive loop and the delivery path can close the stream once that token expires.
                 subscription = {
-                  request_id: request_id, stream: stream, filter: honored, active: false, write_mutex: Mutex.new, keepalive_wakeup: ConditionVariable.new
+                  request_id: request_id, stream: stream, filter: entry_filter, resource_uris: resource_uris, active: false,
+                  write_mutex: Mutex.new, keepalive_wakeup: ConditionVariable.new,
+                  expires_at: stream_token_expiry(auth_info),
                 }
                 @listen_subscriptions[subscription_key] = subscription
               end
@@ -958,15 +1190,6 @@ module MCP
             if subscription.nil?
               close_stream_safely(stream)
             else
-              acknowledgement = {
-                jsonrpc: "2.0",
-                method: Methods::NOTIFICATIONS_SUBSCRIPTIONS_ACKNOWLEDGED,
-                params: {
-                  notifications: honored,
-                  _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id },
-                },
-              }
-
               begin
                 acknowledged = subscription[:write_mutex].synchronize do
                   next false if subscription[:closed]
@@ -984,14 +1207,11 @@ module MCP
                   true
                 end
 
-                if acknowledged
-                  start_listen_keepalive_thread(subscription_key, request_id)
-                else
-                  close_stream_safely(stream)
-                end
+                # An acknowledgement skipped because the entry was marked closed leaves the stream to the path that marked
+                # it, the teardown, which closes the stream itself once it holds the write mutex.
+                start_listen_keepalive_thread(subscription_key, request_id) if acknowledged
               rescue *STREAM_WRITE_ERRORS
-                remove_listen_subscription(subscription_key)
-                close_stream_safely(stream)
+                close_removed_listen_stream(subscription) if remove_listen_subscription(subscription_key)
               end
             end
           end
@@ -1015,10 +1235,15 @@ module MCP
               registered = @mutex.synchronize do
                 subscription = @listen_subscriptions[subscription_key]
                 next false unless subscription
+                # Checked ahead of each tick so the stream does not outlive the token that opened it.
+                # Revocation is not re-checked: the reference SDKs verify a stream at open only.
+                next false if token_expiry_passed?(subscription[:expires_at])
 
-                subscription[:keepalive_wakeup].wait(@mutex, @listen_keepalive_interval)
+                # The wait is cut short at the stream's deadline, so the stream ends at that deadline rather than
+                # up to one interval after it, and a deadline that passed during the wait ends the loop before the ping.
+                subscription[:keepalive_wakeup].wait(@mutex, listen_keepalive_wait(subscription[:expires_at]))
 
-                @listen_subscriptions.key?(subscription_key)
+                @listen_subscriptions.key?(subscription_key) && !token_expiry_passed?(subscription[:expires_at])
               end
               break unless registered
 
@@ -1032,11 +1257,9 @@ module MCP
             # removed the entry already, and the report should still name the stream.
             MCP.configuration.exception_reporter.call(e, { subscription_id: request_id })
           ensure
-            stream = @mutex.synchronize do
-              subscription = @listen_subscriptions.delete(subscription_key)
-              subscription && subscription[:stream]
-            end
-            close_stream_safely(stream) if stream
+            # Through the helper, so the entry is marked closed here as it is for every other removal.
+            subscription = remove_listen_subscription(subscription_key)
+            close_removed_listen_stream(subscription) if subscription
           end
         end
 
@@ -1056,6 +1279,40 @@ module MCP
           end
         end
 
+        # The deadline at which a stream authenticated by `auth_info` is closed: whichever comes first of the token's own
+        # expiry and `max_stream_lifetime:` seconds from now. Only the deadline is retained with the stream,
+        # never the `AccessToken` itself, which would park the raw bearer credential in `@sessions` or `@listen_subscriptions`
+        # for the life of the stream. The cap is what bounds a stream whose token reports no expiry (`exp` is optional in
+        # an RFC 7662 introspection response), so "a stream does not outlive its credential" holds even when the credential
+        # never says when it ends. A stream opened without a token is not capped: there is no credential to bound,
+        # and capping it would change a transport used without `token_verifier:`.
+        def stream_token_expiry(auth_info)
+          return unless auth_info
+
+          deadlines = []
+          token_expiry = auth_info.expires_at if auth_info.respond_to?(:expires_at)
+          # A custom verifier that breaks the `AccessToken` contract with an expiry that is not a number must not fail
+          # the stream while it is being set up: the value is ignored and only the cap applies.
+          deadlines << token_expiry if token_expiry.is_a?(Numeric)
+          deadlines << Time.now.to_i + @max_stream_lifetime if @max_stream_lifetime
+
+          deadlines.min
+        end
+
+        # Same rule as `AccessToken#expired?`: no expiry means the token never expires here.
+        def token_expiry_passed?(expires_at)
+          !expires_at.nil? && expires_at <= Time.now.to_i
+        end
+
+        # Seconds the listen keepalive thread waits before its next tick: the interval, or the time left until
+        # the stream's deadline when that comes first. The floor keeps a deadline a few microseconds away from
+        # turning into a zero-length wait.
+        def listen_keepalive_wait(expires_at)
+          return @listen_keepalive_interval if expires_at.nil?
+
+          [[expires_at - Time.now.to_f, LISTEN_DEADLINE_WAIT_FLOOR].max, @listen_keepalive_interval].min
+        end
+
         # Per SEP-2575, the server MUST NOT send notification types the client has not requested,
         # and the acknowledgement only includes types the server actually supports
         # (derived from its declared capabilities).
@@ -1068,12 +1325,36 @@ module MCP
 
           subscriptions = filter[:resourceSubscriptions]
           if capability_flag?(capabilities, :resources, :subscribe) && subscriptions.is_a?(Array) && !subscriptions.empty?
-            honored[:resourceSubscriptions] = subscriptions
+            honored[:resourceSubscriptions] = subscriptions.uniq
           end
 
           honored
         end
 
+        # Checks a listen filter's `resourceSubscriptions` against the schema, which types it as an optional array of strings,
+        # so a member that is present but `null` is refused like any other non-array; against `MAX_RESOURCE_SUBSCRIPTION_URIS`;
+        # and against `max_resource_subscription_bytes`, returning the problem to report or `nil`. Duplicates are dropped before
+        # the bounds are measured, since they are dropped before storage too. The checks run whether or not the server declares
+        # the `subscribe` capability: a request that violates the schema is invalid regardless of what would be honored,
+        # and the bounds are limits on the request itself, like `max_request_bytes`, not on what the server would retain from it.
+        def resource_subscriptions_problem(filter)
+          return unless filter.key?(:resourceSubscriptions)
+
+          subscriptions = filter[:resourceSubscriptions]
+          unless subscriptions.is_a?(Array) && subscriptions.all? { |uri| uri.is_a?(String) }
+            return "`resourceSubscriptions` must be an array of strings"
+          end
+
+          distinct = subscriptions.uniq
+          if distinct.size > MAX_RESOURCE_SUBSCRIPTION_URIS
+            return "`resourceSubscriptions` exceeds #{MAX_RESOURCE_SUBSCRIPTION_URIS} URIs"
+          end
+          return unless @max_resource_subscription_bytes
+          return if distinct.sum(&:bytesize) <= @max_resource_subscription_bytes
+
+          "`resourceSubscriptions` exceeds #{@max_resource_subscription_bytes} bytes"
+        end
+
         # Reads a nested capability flag tolerating both symbol and string keys, since user-supplied capability hashes arrive
         # in either form. The flag that promises delivery (`listChanged` / `subscribe`) decides honoring, the same derivation
         # `Server#discover` uses for its era-aware capability stripping; the mere presence of the primitive's capability is not enough.
@@ -1091,24 +1372,34 @@ module MCP
           field = LISTEN_FILTER_FIELDS[method]
           return if field.nil? && method != Methods::NOTIFICATIONS_RESOURCES_UPDATED
 
-          # The matching snapshot is taken under `@mutex`, but stream writes happen outside it:
-          # a slow or stalled subscriber must not block the transport, matching the legacy delivery paths.
-          matched = @mutex.synchronize do
-            @listen_subscriptions.filter_map do |subscription_key, subscription|
-              # An inactive entry has not finished writing its acknowledgement yet;
-              # delivering to it would put a notification ahead of the acknowledgement.
-              next unless subscription[:active]
+          # Only the snapshot of active entries is taken under `@mutex`, one pass over the entries as before;
+          # the matching and the stream writes happen outside it, so neither the number of URIs the streams named
+          # nor a slow or stalled subscriber can hold the transport's lock, matching the legacy delivery paths.
+          # An inactive entry has not finished writing its acknowledgement yet;
+          # delivering to it would put a notification ahead of the acknowledgement.
+          # An active entry whose token deadline has passed is closed here instead of delivered to, so the deadline
+          # holds on a transport whose keepalive is disabled as well. An expired entry still inactive is skipped
+          # like any inactive one and caught by the next delivery once its acknowledgement is written.
+          expired_keys = []
+          candidates = @mutex.synchronize do
+            @listen_subscriptions.select do |key, subscription|
+              next false unless subscription[:active]
+              next true unless token_expiry_passed?(subscription[:expires_at])
+
+              expired_keys << key
+              false
+            end
+          end
 
-              hit = if field
-                subscription[:filter][field]
-              else
-                uris = subscription[:filter][:resourceSubscriptions]
-                uri = params.is_a?(Hash) ? params[:uri] || params["uri"] : nil
-                uris.is_a?(Array) && uris.include?(uri)
-              end
+          expired_keys.each do |key|
+            subscription = remove_listen_subscription(key)
 
-              [subscription_key, subscription] if hit
-            end
+            close_removed_listen_stream(subscription) if subscription
+          end
+
+          uri = params.is_a?(Hash) ? params[:uri] || params["uri"] : nil
+          matched = candidates.select do |_key, subscription|
+            field ? subscription[:filter][field] : subscription[:resource_uris].include?(uri)
           end
 
           matched.each do |subscription_key, subscription|
@@ -1131,8 +1422,9 @@ module MCP
                 e,
                 { subscription_id: subscription[:request_id], error: "Failed to send notification" },
               )
-              remove_listen_subscription(subscription_key)
-              close_stream_safely(subscription[:stream])
+              # Closed only when the removal is this path's own, as every other removal path does: the keepalive loop,
+              # a token expiry, or the teardown that removed the entry first closes the stream itself.
+              close_removed_listen_stream(subscription) if remove_listen_subscription(subscription_key)
             end
           end
         end
@@ -1140,15 +1432,36 @@ module MCP
         def remove_listen_subscription(subscription_key)
           @mutex.synchronize do
             subscription = @listen_subscriptions.delete(subscription_key)
-            subscription[:keepalive_wakeup].signal if subscription
+            if subscription
+              # Marked closed as teardown does, so a delivery or keepalive that took the entry before the removal skips it under
+              # the write mutex instead of writing to a stream being closed. The flag is set without taking the write mutex,
+              # which must never be taken inside `@mutex`: a write that checks the flag from here on skips, and one already
+              # past its check lands before the stream closes, since `close_removed_listen_stream` waits for the write mutex.
+              subscription[:closed] = true
+              subscription[:keepalive_wakeup].signal
+            end
 
             subscription
           end
         end
 
+        # Closes a subscription's stream while excluding concurrent writes. The write mutex, taken here outside
+        # `@mutex`, makes the close wait for a write already past its `closed` check, so that write completes or fails
+        # before the stream is closed, and a write that takes the mutex afterwards sees `closed` and skips. Teardown
+        # gets the same ordering by setting `closed` under the write mutex itself.
+        def close_removed_listen_stream(subscription)
+          subscription[:write_mutex].synchronize { close_stream_safely(subscription[:stream]) }
+        end
+
         # Graceful teardown (SEP-2575): each open listen stream receives its `SubscriptionsListenResult` response
-        # before the stream closes.
-        def teardown_listen_subscriptions
+        # before the stream closes. The results are written on a helper thread that is waited for at most `timeout`
+        # seconds in all, because a peer that stopped reading stalls the write of its result, or a delivery already
+        # holding the stream's write mutex, for as long as its socket buffers stay full. Once the time is up, every stream
+        # still open is closed from here: closing a Ruby IO ends a write stalled on it with an `IOError` the helper rescues,
+        # while a stream object of another kind may keep the helper blocked, which no longer holds `close`. Either way
+        # the stream goes without its result, like one whose acknowledgement was never written. The helper is left
+        # to finish on its own rather than killed, so a write mutex is never dropped in the middle of a write.
+        def teardown_listen_subscriptions(timeout: LISTEN_TEARDOWN_TIMEOUT)
           removed = @mutex.synchronize do
             subscriptions = @listen_subscriptions.dup
             @listen_subscriptions.clear
@@ -1159,35 +1472,72 @@ module MCP
 
             subscriptions
           end
+          return if removed.empty?
 
-          removed.each_value do |subscription|
-            # Marking the entry closed and writing the result under the stream's write mutex orders
-            # this against in-flight deliveries and against the acknowledgement write: each one either lands
-            # before the result or observes `closed` and skips, keeping the graceful result the stream's final message.
-            subscription[:write_mutex].synchronize do
-              subscription[:closed] = true
+          # Whichever side takes an entry out of `pending` closes its stream: the helper after the write, or `close` once
+          # the time is up. Claiming before closing keeps a stream from being closed by both in either order.
+          pending = removed.dup
+          pending_mutex = Mutex.new
+          writer = Thread.new do
+            removed.each do |subscription_key, subscription|
+              write_listen_closing_result(subscription)
+              close_stream_safely(subscription[:stream]) if pending_mutex.synchronize { pending.delete(subscription_key) }
+            end
+          end
 
-              # A stream whose acknowledgement was never written gets no result either: SEP-2575 makes
-              # the acknowledgement the first message, so the stream closes abruptly and the client re-sends.
-              next unless subscription[:active]
+          begin
+            writer.join(timeout)
+          rescue StandardError
+            # A helper that died with an exception has stopped writing; the streams it did not finish are closed below.
+          end
 
-              begin
-                send_to_stream(subscription[:stream], {
-                  jsonrpc: "2.0",
-                  id: subscription[:request_id],
-                  result: {
-                    # `SubscriptionsListenResult` is served at the transport layer and never
-                    # passes through the dispatch path, so the REQUIRED 2026-07-28 `resultType` is
-                    # stamped at its construction site.
-                    resultType: ResultType::COMPLETE,
-                    _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => subscription[:request_id] },
-                  },
-                })
-              rescue *STREAM_WRITE_ERRORS
-                nil
-              end
+          left = pending_mutex.synchronize do
+            subscriptions = pending.values
+            pending.clear
+            subscriptions
+          end
+          left.each { |subscription| close_stream_safely(subscription[:stream]) }
+        end
+
+        # Marking the entry closed and writing the result under the stream's write mutex orders
+        # this against in-flight deliveries and against the acknowledgement write: each one either lands
+        # before the result or observes `closed` and skips, keeping the graceful result the stream's final message.
+        # The stream is left open for the caller to close.
+        def write_listen_closing_result(subscription)
+          subscription[:write_mutex].synchronize do
+            subscription[:closed] = true
+
+            # A stream whose acknowledgement was never written gets no result either: SEP-2575 makes
+            # the acknowledgement the first message, so the stream closes abruptly and the client re-sends.
+            next unless subscription[:active]
+
+            begin
+              send_to_stream(subscription[:stream], {
+                jsonrpc: "2.0",
+                id: subscription[:request_id],
+                result: {
+                  # `SubscriptionsListenResult` is served at the transport layer and never
+                  # passes through the dispatch path, so the REQUIRED 2026-07-28 `resultType` is
+                  # stamped at its construction site.
+                  resultType: ResultType::COMPLETE,
+                  _meta: { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => subscription[:request_id] },
+                },
+              })
+            rescue *STREAM_WRITE_ERRORS
+              nil
             end
-            close_stream_safely(subscription[:stream])
+          end
+        rescue StandardError => e
+          # Reported rather than raised: on the helper thread an error would end the teardown of every stream after this one,
+          # and `close` is past waiting for it by the time a stalled write fails. A reporter that raises is dropped for
+          # the same reason.
+          begin
+            MCP.configuration.exception_reporter.call(
+              e,
+              { subscription_id: subscription[:request_id], error: "Failed to close listen stream" },
+            )
+          rescue StandardError
+            nil
           end
         end
 
@@ -1296,13 +1646,31 @@ module MCP
           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
               # one. In the live case, reject with `-32600` so the original session is not abandoned.
               # In the unknown/expired case, return 404 so the client retries from scratch instead
               # of silently inheriting a fresh session under the old ID.
-              return already_initialized_response(body[:id]) if session_active?(session_id)
+              # The live case is told only to the principal the session is bound to: for any other token the answer
+              # is the 404 an unknown session gets, as on every other route, so a guessed session id is not confirmed
+              # to exist by an `initialize` either.
+              if session_active?(session_id)
+                session = @mutex.synchronize { @sessions[session_id] }
+                return session_not_found_response unless session && session_principal_matches?(session, request)
+
+                return already_initialized_response(body[:id])
+              end
 
               return session_not_found_response
             end
@@ -1312,8 +1680,10 @@ module MCP
             # Ownership gate for every request against an existing session, applied uniformly to notifications, client responses,
             # and regular requests. This covers write paths beyond tool calls - notably `notifications/cancelled`, which would
             # otherwise let a stolen session ID cancel a victim's in-flight request. `initialize` is exempt (it establishes the session).
-            if !@stateless && session_id && !validate_session_request(request, session_id)
-              return forbidden_response
+            if !@stateless && session_id
+              rejection = session_request_rejection(request, session_id)
+
+              return rejection if rejection
             end
 
             if notification?(body)
@@ -1322,14 +1692,14 @@ module MCP
               # branches; without it a custom notification handler could run without a live session.
               return session_not_found_response if !@stateless && !session_active?(session_id)
 
-              dispatch_notification(body_string, session_id)
+              dispatch_notification(body_string, session_id, auth_info: request.env[OAuth::ENV_KEY])
               handle_accepted
             elsif response?(body)
               return session_not_found_response if !@stateless && !session_exists?(session_id)
 
               handle_response(body, session_id: session_id)
             else
-              handle_regular_request(body_string, session_id, related_request_id: body[:id])
+              handle_regular_request(body_string, session_id, related_request_id: body[:id], auth_info: request.env[OAuth::ENV_KEY])
             end
           end
         rescue StandardError => e
@@ -1353,16 +1723,20 @@ module MCP
 
           return missing_session_id_response unless session_id
 
+          # The ownership gate runs before the session is touched, so a rejected request cannot refresh the idle timer of a session it does not own.
+          # The visible outcome is unchanged: an unknown session passes the gate and fails the lookup, and an expired one fails it, both with the same 404.
+          rejection = session_request_rejection(request, session_id)
+          return rejection if rejection
+
           error_response = validate_and_touch_session(session_id)
           return error_response if error_response
-          return forbidden_response unless validate_session_request(request, session_id)
 
           protocol_version_error = validate_protocol_version_header(request)
           return protocol_version_error if protocol_version_error
 
-          return session_already_connected_response if get_session_stream(session_id)
+          return session_already_connected_response if live_get_stream?(session_id)
 
-          setup_sse_stream(session_id)
+          setup_sse_stream(session_id, request.env[OAuth::ENV_KEY])
         end
 
         def handle_delete(request)
@@ -1378,16 +1752,22 @@ module MCP
 
           return missing_session_id_response unless (session_id = extract_session_id(request))
           return session_not_found_response unless session_exists?(session_id)
-          return forbidden_response unless validate_session_request(request, session_id)
+          rejection = session_request_rejection(request, session_id)
+          return rejection if rejection
 
           protocol_version_error = validate_protocol_version_header(request)
           return protocol_version_error if protocol_version_error
 
-          cleanup_session(session_id)
+          # The session may be gone by now, removed by the reaper or by the owner's own DELETE since the checks above:
+          # a request that terminated nothing answers like one naming an unknown session, so a removal it did not cause
+          # confirms nothing about the session having existed.
+          return session_not_found_response unless cleanup_session(session_id)
 
           success_response
         end
 
+        # Removes the session, closes its streams outside the lock, and returns the removed session, or nil when
+        # there was none to remove.
         def cleanup_session(session_id)
           session = @mutex.synchronize do
             cleanup_session_unsafe(session_id)
@@ -1397,6 +1777,8 @@ module MCP
             close_stream_safely(session[:get_sse_stream])
             close_post_request_streams(session)
           end
+
+          session
         end
 
         # Removes a session from `@sessions` and returns it. Does not close the stream.
@@ -1442,23 +1824,48 @@ module MCP
 
         # Session-ownership gate for requests against an existing session (the spec's session-binding guidance).
         # The session ID alone is unguessable but not proof of ownership, so a stolen ID must not silently grant access.
-        # Two layers, both returning `false` to trigger a 403:
+        # Three layers, each answering with the rejection response it returns. The built-in layers run before
+        # the custom validator so a permissive `session_request_validator` cannot bypass them, and the principal
+        # binding runs first of all, so that another principal gets the 404 whatever else its request carries:
         #
+        # - Built-in principal binding (active when bearer authentication is in play): a session initialized under
+        #   one token identity refuses requests verified as a different one. The answer is the same 404 an unknown session gets,
+        #   so a guessed session ID is not confirmed to exist; it carries no `WWW-Authenticate` challenge either,
+        #   because the token itself is valid and re-authorization would not help.
         # - Built-in Origin consistency (defense in depth, not authentication): if the session recorded an `Origin`
-        #   at `initialize` and this request carries a different one, reject. Both must be present to compare,
+        #   at `initialize` and this request carries a different one, reject with 403. Both must be present to compare,
         #   so non-browser clients that send no `Origin` are unaffected.
-        # - The application-supplied `session_request_validator`, which can enforce true ownership when it has
-        #   an authenticated principal.
-        def validate_session_request(request, session_id)
+        # - The application-supplied `session_request_validator`, which can enforce ownership policy beyond the built-in layers;
+        #   a falsy return rejects with 403.
+        #
+        # Returns nil when the request may proceed.
+        def session_request_rejection(request, session_id)
           session = @mutex.synchronize { @sessions[session_id] }
-          return true unless session
+          return unless session
+          return session_not_found_response unless session_principal_matches?(session, request)
 
           session_origin = session[:origin]
           request_origin = request.env["HTTP_ORIGIN"]
-          return false if session_origin && request_origin && session_origin != request_origin
-          return @session_request_validator.call(request, session_id) if @session_request_validator
+          return forbidden_response if session_origin && request_origin && session_origin != request_origin
 
-          true
+          if @session_request_validator && !@session_request_validator.call(request, session_id)
+            return forbidden_response
+          end
+
+          nil
+        end
+
+        # A session bound to a principal at `initialize` only accepts requests verified as the same `issuer`, `subject`,
+        # and `client_id` triple (client-credentials tokens without a `sub` bind on `client_id` alone; nil members compare equal).
+        # The issuer takes part so a subject and client id pair repeated across identity providers behind a custom verifier
+        # does not collide. A token whose subject and client id are both nil records no binding, because there is no identity to compare.
+        def session_principal_matches?(session, request)
+          return true if session[:auth_subject].nil? && session[:auth_client_id].nil?
+
+          token = request.env[OAuth::ENV_KEY]
+          return false if token.nil?
+
+          token.issuer == session[:auth_issuer] && token.subject == session[:auth_subject] && token.client_id == session[:auth_client_id]
         end
 
         def validate_accept_header(request, required_types)
@@ -1524,6 +1931,45 @@ module MCP
           )
         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.
@@ -1595,7 +2041,7 @@ module MCP
 
         # Dispatches a client-originated notification (e.g. `notifications/cancelled`,
         # `notifications/initialized`) through the server so it can update session state.
-        def dispatch_notification(body_string, session_id)
+        def dispatch_notification(body_string, session_id, auth_info: nil)
           server_session = nil
           if @stateless
             server_session = ephemeral_session
@@ -1606,7 +2052,7 @@ module MCP
             end
           end
 
-          dispatch_handle_json(body_string, server_session)
+          dispatch_handle_json(body_string, server_session, auth_info: auth_info)
         rescue => e
           MCP.configuration.exception_reporter.call(e, { error: "Failed to dispatch notification" })
         end
@@ -1635,6 +2081,7 @@ module MCP
 
         def handle_initialization(request, body_string, body)
           session_id = nil
+          auth_info = request.env[OAuth::ENV_KEY]
 
           if @stateless
             server_session = ephemeral_session
@@ -1660,9 +2107,15 @@ module MCP
                 get_sse_stream: nil,
                 server_session: server_session,
                 last_active_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
-                # Captured for the built-in Origin-consistency defense in `validate_session_request`.
+                # Captured for the built-in Origin-consistency defense in `session_request_rejection`.
                 # Not authentication.
                 origin: request.env["HTTP_ORIGIN"],
+                # Principal binding per the spec's session-binding guidance: the session is bound to the token identity that initialized it,
+                # and `session_request_rejection` rejects later requests presenting a token for a different principal. All three fields are nil
+                # when the request was not bearer-authenticated, which disables the check.
+                auth_issuer: auth_info&.issuer,
+                auth_subject: auth_info&.subject,
+                auth_client_id: auth_info&.client_id,
               }
               true
             end
@@ -1671,7 +2124,7 @@ module MCP
             return too_many_sessions_response unless inserted
           end
 
-          response = server_session.handle_json(body_string)
+          response = server_session.handle_json(body_string, auth_info: auth_info)
 
           # `initialize_request?` matches on the method alone, so an `initialize` sent without
           # an id (framed as a notification) reaches here. `Server#init` marks the session initialized,
@@ -1714,7 +2167,7 @@ module MCP
           )
         end
 
-        def handle_regular_request(body_string, session_id, related_request_id: nil)
+        def handle_regular_request(body_string, session_id, related_request_id: nil, auth_info: nil)
           server_session = nil
 
           if @stateless
@@ -1738,9 +2191,9 @@ module MCP
           end
 
           if session_id && !@stateless && !@enable_json_response
-            handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id)
+            handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: related_request_id, auth_info: auth_info)
           else
-            response = dispatch_handle_json(body_string, server_session)
+            response = dispatch_handle_json(body_string, server_session, auth_info: auth_info)
 
             # `Server#handle_json` returns `nil` when cancellation has suppressed the JSON-RPC response per spec.
             # Mirror the notification path and ack with 202 instead of returning a 200 with a `nil` Rack body,
@@ -1754,7 +2207,7 @@ module MCP
         # Returns the POST response as an SSE stream so the server can send
         # JSON-RPC requests and notifications during request processing.
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server
-        def handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: nil)
+        def handle_request_with_sse_response(body_string, session_id, server_session, related_request_id: nil, auth_info: nil)
           body = proc do |stream|
             @mutex.synchronize do
               session = @sessions[session_id]
@@ -1769,7 +2222,7 @@ module MCP
             end
 
             begin
-              response = dispatch_handle_json(body_string, server_session)
+              response = dispatch_handle_json(body_string, server_session, auth_info: auth_info)
 
               send_to_stream(stream, response) if response
             ensure
@@ -1799,20 +2252,25 @@ module MCP
         # When `related_request_id` is given, returns only the POST response
         # stream for that request (no fallback to GET SSE). This prevents
         # request-scoped messages from leaking to the wrong stream.
-        # When `related_request_id` is nil, returns the GET SSE stream.
-        def active_stream(session, related_request_id: nil)
-          if related_request_id
-            session.dig(:post_request_streams, related_request_id)
-          else
-            session[:get_sse_stream]
-          end
+        # When `related_request_id` is nil, returns the GET SSE stream, or nil once the token that opened it
+        # has expired: that stream is detached from the session and added to `streams_to_close` instead, so its
+        # deadline holds at the next write and not only at the keepalive tick. Called under `@mutex`; the caller
+        # closes the collected streams outside it.
+        def active_stream(session, streams_to_close, related_request_id: nil)
+          return session.dig(:post_request_streams, related_request_id) if related_request_id
+
+          stream = session[:get_sse_stream]
+          return stream unless stream && token_expiry_passed?(session[:get_sse_stream_expires_at])
+
+          streams_to_close << detach_get_stream(session)
+          nil
         end
 
-        def dispatch_handle_json(body_string, server_session)
+        def dispatch_handle_json(body_string, server_session, auth_info: nil)
           if server_session
-            server_session.handle_json(body_string)
+            server_session.handle_json(body_string, auth_info: auth_info)
           else
-            @server.handle_json(body_string)
+            @server.handle_json(body_string, auth_info: auth_info)
           end
         end
 
@@ -1843,8 +2301,26 @@ module MCP
           response
         end
 
-        def get_session_stream(session_id)
-          @mutex.synchronize { @sessions[session_id]&.fetch(:get_sse_stream, nil) }
+        # Whether the session holds a GET stream whose deadline has not passed. A stream whose token expired may still
+        # be attached between its last delivery and its next keepalive tick; it is detached and closed here, so a client
+        # reopening the stream with a fresh token is not turned away until one of those noticed.
+        def live_get_stream?(session_id)
+          detached = nil
+          live = @mutex.synchronize do
+            session = @sessions[session_id]
+            stream = session && session[:get_sse_stream]
+            if stream.nil?
+              false
+            elsif token_expiry_passed?(session[:get_sse_stream_expires_at])
+              detached = detach_get_stream(session)
+              false
+            else
+              true
+            end
+          end
+
+          close_stream_safely(detached) if detached
+          live
         end
 
         def session_exists?(session_id)
@@ -1883,6 +2359,27 @@ module MCP
           active
         end
 
+        # Built-in OAuth 2.1 bearer enforcement (active when `token_verifier:` is configured).
+        # Returns nil on success, storing the verified `AccessToken` in `env["mcp.auth_info"]` where the dispatch paths
+        # and `session_request_rejection` read it; returns the RFC 6750 challenge response on failure. OPTIONS is exempt:
+        # CORS preflights never carry credentials, and rejecting them here would fail CORS closed for browser clients
+        # while the transport still answers the preflight itself with 405 (an upstream CORS middleware normally intercepts it).
+        def authenticate_request(request)
+          return if @oauth_authenticator.nil?
+          return if request.env["REQUEST_METHOD"] == "OPTIONS"
+
+          request.env[OAuth::ENV_KEY] = @oauth_authenticator.authenticate(request.env)
+          nil
+        rescue OAuth::Error => e
+          @oauth_authenticator.challenge_response(e)
+        rescue => e
+          # A misbehaving verifier (e.g. an unreachable JWKS or introspection endpoint) is an internal failure:
+          # report it and answer 500 without a challenge, so the client does not discard a perfectly good token.
+          MCP.configuration.exception_reporter.call(e, { transport: self.class.name })
+
+          [500, { "content-type" => "application/json" }, [{ error: "server_error" }.to_json]]
+        end
+
         # Per MCP 2025-11-25, servers MUST validate the `Origin` header and SHOULD bind only to localhost
         # to prevent DNS rebinding attacks against locally bound MCP servers. Protection is on by default;
         # pass `dns_rebinding_protection: false` to disable it (e.g. when an upstream proxy or middleware already
@@ -2009,59 +2506,114 @@ module MCP
           )
         end
 
-        def setup_sse_stream(session_id)
-          body = create_sse_body(session_id)
+        def setup_sse_stream(session_id, auth_info = nil)
+          body = create_sse_body(session_id, auth_info)
 
           [200, SSE_HEADERS.dup, body]
         end
 
-        def create_sse_body(session_id)
+        def create_sse_body(session_id, auth_info = nil)
           proc do |stream|
-            stored = store_stream_for_session(session_id, stream)
-            start_keepalive_thread(session_id) if stored
+            stored = store_stream_for_session(session_id, stream, auth_info)
+            start_keepalive_thread(session_id, stream) if stored
           end
         end
 
-        def store_stream_for_session(session_id, stream)
-          @mutex.synchronize do
+        # The expiry of the token that authenticated the GET is kept with the stream so the keepalive loop and
+        # the delivery paths can close the stream once that token expires.
+        def store_stream_for_session(session_id, stream, auth_info = nil)
+          stored = @mutex.synchronize do
             session = @sessions[session_id]
-            if session && !session[:get_sse_stream]
-              session[:get_sse_stream] = stream
-            else
-              # Either session was removed, or another request already established a stream.
-              stream.close
-              # `stream.close` may return a truthy value depending on the stream class.
-              # Explicitly return nil to guarantee a falsy return for callers.
-              nil
-            end
+            next false unless session && !session[:get_sse_stream]
+
+            session[:get_sse_stream] = stream
+            session[:get_sse_stream_expires_at] = stream_token_expiry(auth_info)
+            true
           end
+
+          # The expiry is nil for a stream opened without a token, and callers read a falsy return as "not stored",
+          # so the stream itself is the return value.
+          return stream if stored
+
+          # Either the session was removed, or another request already established a stream. The refused stream is
+          # closed outside the lock like every other stream this transport closes, so a close that blocks on the peer
+          # cannot hold every other session on `@mutex`.
+          close_stream_safely(stream)
+          nil
         end
 
-        def start_keepalive_thread(session_id)
+        # The thread acts on the stream it was started for and on no other: the session may have detached that
+        # stream at a delivery once its token expired and the client may have opened a new one since, which gets
+        # a keepalive thread of its own. The loop therefore ends as soon as the session no longer holds this stream,
+        # and a loop that did not run to its end (a failed ping, or any other abnormal exit) drops the stream through
+        # `drop_broken_stream`, which tears the session down only while it still holds that stream, as before.
+        def start_keepalive_thread(session_id, stream)
           Thread.new do
-            while session_active_with_stream?(session_id)
+            ended = false
+
+            while session_holds_stream?(session_id, stream)
+              # Checked ahead of each tick so the stream does not outlive the token that opened it.
+              # Revocation is not re-checked: the reference SDKs verify a stream at open only.
+              # An expired token ends the stream alone: every other request of the session is verified on its own,
+              # and the client may reopen the stream with a fresh token.
+              if get_stream_token_expired?(session_id)
+                close_get_stream(session_id, stream)
+                break
+              end
+
               sleep(30)
-              send_keepalive_ping(session_id)
+
+              send_keepalive_ping(session_id, stream)
             end
+
+            ended = true
           rescue StandardError => e
             MCP.configuration.exception_reporter.call(e, { session_id: session_id })
           ensure
-            cleanup_session(session_id)
+            drop_broken_stream(session_id, stream, nil) unless ended
           end
         end
 
-        def session_active_with_stream?(session_id)
-          @mutex.synchronize { @sessions.key?(session_id) && @sessions[session_id][:get_sse_stream] }
+        def session_holds_stream?(session_id, stream)
+          @mutex.synchronize do
+            session = @sessions[session_id]
+            !session.nil? && session[:get_sse_stream].equal?(stream)
+          end
         end
 
-        def send_keepalive_ping(session_id)
-          # Resolve the stream under the lock, then write outside it so a stalled reader
-          # cannot block every other session on `@mutex`.
-          stream = @mutex.synchronize do
+        def get_stream_token_expired?(session_id)
+          expires_at = @mutex.synchronize do
+            session = @sessions[session_id]
+            session && session[:get_sse_stream_expires_at]
+          end
+
+          token_expiry_passed?(expires_at)
+        end
+
+        # Detaches and closes the session's GET stream when it is still `stream`, leaving the session in place.
+        def close_get_stream(session_id, stream)
+          detached = @mutex.synchronize do
             session = @sessions[session_id]
-            session && session[:get_sse_stream]
+            next unless session && session[:get_sse_stream].equal?(stream)
+
+            detach_get_stream(session)
           end
-          return unless stream
+
+          close_stream_safely(detached) if detached
+        end
+
+        # Removes the GET stream and its deadline from `session` under `@mutex` and returns the stream for closing
+        # outside the lock.
+        def detach_get_stream(session)
+          session.delete(:get_sse_stream_expires_at)
+          session.delete(:get_sse_stream)
+        end
+
+        # Pings `stream` only while the session still holds it, checked under the lock and written outside it so
+        # a stalled reader cannot block every other session on `@mutex`: a thread whose stream was detached during
+        # its sleep must not write to the one the client opened since, which has a keepalive thread of its own.
+        def send_keepalive_ping(session_id, stream)
+          return unless session_holds_stream?(session_id, stream)
 
           send_ping_to_stream(stream)
         rescue *STREAM_WRITE_ERRORS => e