mcp 1.7.0 → 1.8.1

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

@@ -121,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.
@@ -176,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,
@@ -192,7 +226,13 @@ module MCP
           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 }`.
@@ -285,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
 
@@ -293,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:`.
@@ -335,10 +406,21 @@ module MCP
           @serve_subscriptions_listen
         end
 
+        # Stateless mode has no session streams to deliver notifications on (`send_notification` reports non-delivery),
+        # so `Server#init` advertises no `listChanged`/`subscribe` flags there.
+        def delivers_notifications?
+          !@stateless
+        end
+
         def handle_request(request)
           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.
@@ -386,8 +468,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
@@ -459,7 +561,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)
@@ -476,14 +578,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|
@@ -514,6 +618,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 = []
 
@@ -527,7 +636,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
@@ -585,6 +694,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}."
@@ -592,9 +702,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
@@ -695,10 +807,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")
@@ -797,13 +917,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
@@ -895,7 +1015,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]
 
@@ -906,7 +1026,7 @@ module MCP
 
           # 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
+          # while the refusal can still answer without an 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")
@@ -968,7 +1088,7 @@ module MCP
             )
           end
 
-          [200, SSE_HEADERS.dup, listen_sse_body(request_id, honored, acknowledgement)]
+          [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
@@ -1049,7 +1169,7 @@ 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, acknowledgement)
+        def listen_sse_body(request_id, honored, acknowledgement, auth_info = nil)
           ListenStreamBody.new do |stream|
             subscription_key = SecureRandom.uuid
             subscription = nil
@@ -1062,9 +1182,12 @@ module MCP
 
             @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: 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
@@ -1090,14 +1213,11 @@ module MCP
                   true
                 end
 
-                if acknowledged
-                  start_listen_keepalive_thread(subscription_key, request_id)
-                else
-                  close_removed_listen_stream(subscription)
-                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_removed_listen_stream(subscription)
+                close_removed_listen_stream(subscription) if remove_listen_subscription(subscription_key)
               end
             end
           end
@@ -1121,10 +1241,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
 
@@ -1160,6 +1285,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).
@@ -1224,7 +1383,25 @@ module MCP
           # 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.
-          candidates = @mutex.synchronize { @listen_subscriptions.select { |_key, subscription| subscription[:active] } }
+          # 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
+
+          expired_keys.each do |key|
+            subscription = remove_listen_subscription(key)
+
+            close_removed_listen_stream(subscription) if subscription
+          end
 
           uri = params.is_a?(Hash) ? params[:uri] || params["uri"] : nil
           matched = candidates.select do |_key, subscription|
@@ -1251,8 +1428,9 @@ module MCP
                 e,
                 { subscription_id: subscription[:request_id], error: "Failed to send notification" },
               )
-              remove_listen_subscription(subscription_key)
-              close_removed_listen_stream(subscription)
+              # 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
@@ -1282,8 +1460,14 @@ module MCP
         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
@@ -1294,35 +1478,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
 
@@ -1447,7 +1668,15 @@ module MCP
               # 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
@@ -1457,8 +1686,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)
@@ -1467,14 +1698,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
@@ -1498,16 +1729,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)
@@ -1523,16 +1758,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)
@@ -1542,6 +1783,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.
@@ -1587,23 +1830,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)
@@ -1619,10 +1887,10 @@ module MCP
           nil
         end
 
+        # Empty list members (`application/json,,text/event-stream`), which RFC 9110 section 5.6.1.2 has
+        # a recipient parse and ignore, are skipped.
         def parse_accept_header(header)
-          header.split(",").map do |part|
-            part.split(";").first.strip.downcase
-          end
+          header.split(",").map { |part| part.split(";").first.to_s.strip.downcase }.reject(&:empty?)
         end
 
         def validate_content_type(request)
@@ -1712,7 +1980,8 @@ module MCP
           # `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.
           JSON.parse(body_string, symbolize_names: true, max_nesting: MAX_JSON_NESTING)
-        rescue JSON::ParserError, TypeError
+        # `symbolize_names` raises `EncodingError`, not `JSON::ParserError`, for a key that is not valid UTF-8.
+        rescue JSON::ParserError, TypeError, EncodingError
           raise InvalidJsonError
         end
 
@@ -1766,20 +2035,26 @@ module MCP
           )
         end
 
+        # The body leaves the `id` member out when there is no request id to echo, as the MCP schema allows
+        # only a string or an integer there.
         def json_rpc_error_response(status:, code:, message:, data: nil, id: nil)
           error = { code: code, message: message }
           error[:data] = data if data
-          body = { jsonrpc: "2.0", id: id, error: error }
+          body = { jsonrpc: "2.0" }
+          body[:id] = id unless id.nil?
+          body[:error] = error
           [status, { "content-type" => "application/json" }, [body.to_json]]
         end
 
+        # A notification carries no id member at all; a message with `"id": null` is a malformed request,
+        # which the server answers with Invalid Request instead of running it unanswered.
         def notification?(body)
-          !body[:id] && !!body[:method]
+          !body.key?(:id) && !!body[:method]
         end
 
         # 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
@@ -1790,7 +2065,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
@@ -1819,6 +2094,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
@@ -1844,9 +2120,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
@@ -1855,13 +2137,13 @@ 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,
-          # but JSON-RPC emits no response for an id-less request, so `response` is nil.
-          # Returning `[200, ..., [nil]]` would place nil in the Rack body (which the web server cannot serialize),
-          # and the session would be retained since it is marked initialized. Discard the orphaned session
+          # an id (framed as a notification) reaches here. `Server#init` does not run for it, as for
+          # any request method without an id, so `response` is nil and the session created above
+          # is never initialized. Returning `[200, ..., [nil]]` would place nil in the Rack body (which
+          # the web server cannot serialize), and the session would linger uninitialized. Discard it
           # and ack with 202, mirroring the nil-response handling in a regular request.
           if response.nil?
             cleanup_session(session_id) if session_id
@@ -1898,7 +2180,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
@@ -1922,9 +2204,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,
@@ -1938,7 +2220,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]
@@ -1953,7 +2235,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
@@ -1983,20 +2265,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
 
@@ -2027,8 +2314,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)
@@ -2067,6 +2372,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
@@ -2164,15 +2490,12 @@ module MCP
         end
 
         def invalid_request_response(message, request_id: nil)
-          body = {
-            jsonrpc: "2.0",
+          json_rpc_error_response(
+            status: 400,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: message,
             id: request_id,
-            error: {
-              code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
-              message: message,
-            },
-          }
-          [400, { "content-type" => "application/json" }, [body.to_json]]
+          )
         end
 
         def session_already_connected_response
@@ -2193,59 +2516,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