mcp 1.2.0 → 1.4.0

data/lib/mcp/client/oauth/bounded_body.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # Bounds an OAuth response body while it arrives, rather than after it has been buffered.
+      # Discovery documents, registration responses, and token responses are all small by definition,
+      # so a body that keeps growing is never something worth holding in memory. Matches the 4 MiB cap of
+      # `MCP::Client::HTTP::MAX_MESSAGE_BYTES` and `MCP::Client::Stdio::MAX_LINE_BYTES`.
+      class BoundedBody
+        MAX_RESPONSE_BYTES = 4 * 1024 * 1024
+
+        # Raised while the body is read. Each caller translates it into its own error type,
+        # so this never reaches an embedder.
+        class TooLargeError < StandardError; end
+
+        # What the OAuth code reads from a response. The Faraday response itself is not passed on,
+        # so a later caller cannot reach the unbounded `response.body` by accident.
+        Response = Struct.new(:status, :body)
+
+        def initialize(max_bytes: MAX_RESPONSE_BYTES)
+          @max_bytes = max_bytes
+          @buffer = +""
+        end
+
+        # Faraday `on_data` streaming callback. The chunks arrive decompressed: the default `Net::HTTP` adapter negotiates
+        # `Accept-Encoding` itself and reads the body through `Net::HTTPResponse#inflater`, so a small compressed body
+        # that expands past the cap is refused partway through the expansion rather than after it. That holds only while
+        # the connection leaves `Accept-Encoding` to the adapter; see `Flow#default_http_client`.
+        def on_data
+          proc do |chunk, _received_bytes, _env|
+            @buffer << chunk
+
+            raise TooLargeError, too_large_message if @buffer.bytesize > @max_bytes
+          end
+        end
+
+        # The status paired with the bounded body. Adapters that ignore `on_data` leave the buffer empty and deliver
+        # the whole body in `response.body`, so that path is measured here instead; the bytes are already allocated by then,
+        # but refusing them still keeps an over-cap document out of `JSON.parse`.
+        def response_for(response)
+          Response.new(response.status, bounded_body(response))
+        end
+
+        private
+
+        def bounded_body(response)
+          return @buffer unless @buffer.empty?
+
+          body = response.body
+          body = body.is_a?(String) ? body : body.to_s
+          raise TooLargeError, too_large_message if body.bytesize > @max_bytes
+
+          body
+        end
+
+        def too_large_message
+          # Not "the authorization server": protected resource metadata comes from the MCP server's own origin,
+          # so this message covers endpoints on both sides of the flow.
+          "Response body from the OAuth endpoint exceeds #{@max_bytes} bytes"
+        end
+      end
+
+      private_constant :BoundedBody
+    end
+  end
+end

data/lib/mcp/client/oauth/flow.rb

@@ -1021,26 +1021,54 @@ module MCP
         end
 
         def http_get(url)
-          http_client.get(url)
+          bounded_request do |on_data|
+            http_client.get(url) do |req|
+              req.options.on_data = on_data
+            end
+          end
         end
 
         def http_post_json(url, body)
-          http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/json"
-            req.headers["Accept"] = "application/json"
-            req.body = JSON.generate(body)
+          bounded_request do |on_data|
+            http_client.post(url) do |req|
+              req.headers["Content-Type"] = "application/json"
+              req.headers["Accept"] = "application/json"
+              req.options.on_data = on_data
+              req.body = JSON.generate(body)
+            end
           end
         end
 
         def http_post_form(url, form, headers: {})
-          http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-            req.headers["Accept"] = "application/json"
-            headers.each { |key, value| req.headers[key] = value }
-            req.body = URI.encode_www_form(form)
+          bounded_request do |on_data|
+            http_client.post(url) do |req|
+              req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+              req.headers["Accept"] = "application/json"
+
+              headers.each do |key, value|
+                req.headers[key] = value
+              end
+
+              req.options.on_data = on_data
+              req.body = URI.encode_www_form(form)
+            end
           end
         end
 
+        # Issues a request with the response body bounded as it arrives, and returns the status paired with
+        # that body. An over-cap response is refused rather than truncated: a partial discovery or token document
+        # cannot be validated, and `fetch_metadata_json` must not fall through to the next candidate URL either,
+        # since the same server would serve the same body.
+        def bounded_request
+          bounded = BoundedBody.new
+
+          response = yield(bounded.on_data)
+
+          bounded.response_for(response)
+        rescue BoundedBody::TooLargeError => e
+          raise AuthorizationError, "#{e.message}."
+        end
+
         def http_client
           @http_client ||= @http_client_factory.call
         end
@@ -1050,8 +1078,14 @@ module MCP
         # that transparently followed a `3xx` would let a server reach a host the checks just refused.
         # A caller passing `http_client_factory:` takes on that responsibility: add redirect following here
         # and the guards above only cover the first hop.
+        #
+        # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
+        # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
+        # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
+        # after the check.
         def default_http_client
           require "faraday"
+
           Faraday.new do |faraday|
             faraday.headers["Accept"] = "application/json"
           end

data/lib/mcp/client/oauth/id_jag_token_exchange.rb

@@ -34,10 +34,13 @@ module MCP
           def request(token_endpoint:, id_token:, client_id:, audience:, resource:, http_client: nil)
             http_client ||= default_http_client
 
+            bounded = BoundedBody.new
+
             response = begin
-              http_client.post(token_endpoint) do |req|
+              raw_response = http_client.post(token_endpoint) do |req|
                 req.headers["Content-Type"] = "application/x-www-form-urlencoded"
                 req.headers["Accept"] = "application/json"
+                req.options.on_data = bounded.on_data
                 req.body = URI.encode_www_form(
                   "grant_type" => GRANT_TYPE,
                   "subject_token" => id_token,
@@ -48,6 +51,10 @@ module MCP
                   "client_id" => client_id,
                 )
               end
+
+              bounded.response_for(raw_response)
+            rescue BoundedBody::TooLargeError => e
+              raise ExchangeError, "#{e.message}."
             rescue Faraday::Error => e
               raise ExchangeError, "Token exchange request to #{token_endpoint} failed: #{e.class}: #{e.message}."
             end
@@ -88,8 +95,12 @@ module MCP
             assertion
           end
 
+          # `Accept-Encoding` is deliberately left unset, for the same reason as `Flow#default_http_client`:
+          # claiming that header turns Net::HTTP's `decode_content` off and would move `BoundedBody`'s cap
+          # onto compressed bytes.
           def default_http_client
             require "faraday"
+
             Faraday.new do |faraday|
               faraday.headers["Accept"] = "application/json"
             end

data/lib/mcp/client/oauth.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "oauth/bounded_body"
 require_relative "oauth/discovery"
 require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"

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

@@ -129,6 +129,12 @@ module MCP
         #   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
         #   when an upstream proxy already keeps the stream alive.
+        # @param serve_subscriptions_listen [Boolean] whether `subscriptions/listen` opens a stream.
+        #   A host that buffers responses and cannot serve an open SSE stream (e.g. the Rails controller pattern,
+        #   which builds a fresh transport per request and renders the body) passes `false`:
+        #   the method then answers 404 with JSON-RPC `-32601` like any unimplemented method,
+        #   and `Server#discover` stops advertising the `listChanged`/`subscribe` capability flags,
+        #   keeping the advertisement and the actual behavior in agreement. Defaults to `true`.
         # @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:`.
@@ -145,6 +151,7 @@ module MCP
           max_request_bytes: DEFAULT_MAX_REQUEST_BYTES,
           max_listen_subscriptions: DEFAULT_MAX_LISTEN_SUBSCRIPTIONS,
           listen_keepalive_interval: DEFAULT_LISTEN_KEEPALIVE_INTERVAL,
+          serve_subscriptions_listen: true,
           server_to_client_request_timeout: DEFAULT_SERVER_TO_CLIENT_REQUEST_TIMEOUT
         )
           super(server)
@@ -162,7 +169,8 @@ module MCP
           @allowed_origins = Array(allowed_origins).map(&:downcase).freeze
           @pending_responses = {}
 
-          # Maps a `subscriptions/listen` request id to `{ stream: stream_object, filter: honored_subscription_filter }` (SEP-2575).
+          # Maps a `subscriptions/listen` request id to
+          # `{ stream: stream_object, filter: honored_subscription_filter, active: boolean, write_mutex: Mutex }` (SEP-2575).
           # In-process only; a multi-worker deployment needs an external event bus to fan notifications out across processes,
           # which is a follow-up.
           @listen_subscriptions = {}
@@ -211,6 +219,7 @@ module MCP
           end
 
           @listen_keepalive_interval = listen_keepalive_interval
+          @serve_subscriptions_listen = serve_subscriptions_listen
 
           unless server_to_client_request_timeout.is_a?(Numeric) && server_to_client_request_timeout.positive?
             raise ArgumentError, "server_to_client_request_timeout must be a positive number"
@@ -260,10 +269,12 @@ module MCP
           handle_request(Rack::Request.new(env))
         end
 
-        # The `subscriptions/listen` notification stream (SEP-2575) is served on the modern path,
-        # so `Server#discover` may advertise `listChanged`/`subscribe` capability flags.
+        # Whether this transport serves the `subscriptions/listen` notification stream (SEP-2575).
+        # Gates both the route (a refusing transport answers the method as unimplemented) and
+        # the `listChanged`/`subscribe` capability flags `Server#discover` advertises,
+        # so the two always agree. Set via the `serve_subscriptions_listen:` constructor keyword.
         def serves_subscriptions_listen?
-          true
+          @serve_subscriptions_listen
         end
 
         def handle_request(request)
@@ -450,8 +461,13 @@ module MCP
 
           @mutex.synchronize do
             session = @sessions[session_id]
-            if related_request_id && session&.dig(:post_request_streams, related_request_id)
-              session[:post_request_streams].delete(related_request_id)
+            if related_request_id
+              # Unregister only our own stream: removing on the id alone would drop whichever stream currently holds it,
+              # which is not necessarily the one that failed. The failed stream is closed either way, and a request-scoped
+              # failure never reaches the session teardown below.
+              registered = session&.dig(:post_request_streams, related_request_id)
+              session[:post_request_streams].delete(related_request_id) if registered.equal?(stream)
+
               streams_to_close << stream
             else
               cleanup_and_collect_stream(session_id, streams_to_close)
@@ -718,8 +734,13 @@ module MCP
           return mismatch_error if mismatch_error
 
           # `subscriptions/listen` is a long-lived notification stream served at the transport layer;
-          # it never dispatches through `Server#handle`.
-          return handle_subscriptions_listen(body) if body[:method] == Methods::SUBSCRIPTIONS_LISTEN
+          # it never dispatches through `Server#handle`. A transport constructed with
+          # `serve_subscriptions_listen: false` skips the interception, so the method falls through
+          # 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)
+          end
 
           session = modern_session
           notifications = @mutex.synchronize { @modern_request_sinks[session.session_id] = [] }
@@ -876,17 +897,47 @@ module MCP
           )
         end
 
-        # The proc registers the stream and returns, leaving the response open like
+        # The Rack streaming body of a `subscriptions/listen` response. It responds to `call`
+        # and deliberately not to `each`, so Rack keeps classifying it as a streaming body;
+        # `first` exists only to turn the buffered-host mistake (e.g. `render(json: body.first)`
+        # in the Rails controller pattern) from a bare `NoMethodError` into guidance naming the fix.
+        class ListenStreamBody
+          def initialize(&block)
+            @block = block
+          end
+
+          def call(stream)
+            @block.call(stream)
+          end
+
+          def first
+            raise <<~MESSAGE
+              subscriptions/listen returned a streaming SSE body, which cannot be buffered into a JSON response. \
+              A host that cannot hold an SSE response open should construct the transport with `serve_subscriptions_listen: false`, \
+              so the method is answered as unimplemented instead.
+              See the Rails (controller) section at https://ruby.sdk.modelcontextprotocol.io/server/transports/ for the hosting patterns.
+            MESSAGE
+          end
+        end
+        private_constant :ListenStreamBody
+
+        # The body registers the stream and returns, leaving the response open like
         # the legacy GET stream (`create_sse_body`).
+        #
+        # Registration and activation are split on purpose: the entry is inserted inactive
+        # (reserving the id and the cap slot atomically), the acknowledgement is written outside the lock,
+        # and only then does the entry become eligible for delivery. A concurrent notification between
+        # the insert and the acknowledgement write skips the inactive entry,
+        # enforcing the SEP-2575 rule that no notification precedes the acknowledgement.
         def listen_sse_body(request_id, honored)
-          proc do |stream|
+          ListenStreamBody.new do |stream|
             rejected = false
             @mutex.synchronize do
               if @listen_subscriptions.key?(request_id) ||
                   (@max_listen_subscriptions && @listen_subscriptions.size >= @max_listen_subscriptions)
                 rejected = true
               else
-                @listen_subscriptions[request_id] = { stream: stream, filter: honored }
+                @listen_subscriptions[request_id] = { stream: stream, filter: honored, active: false, write_mutex: Mutex.new }
               end
             end
 
@@ -904,6 +955,7 @@ module MCP
 
               begin
                 send_to_stream(stream, acknowledgement)
+                activate_listen_subscription(request_id)
                 start_listen_keepalive_thread(request_id)
               rescue *STREAM_WRITE_ERRORS
                 remove_listen_subscription(request_id)
@@ -913,6 +965,15 @@ module MCP
           end
         end
 
+        # Marks a listen subscription eligible for delivery once its acknowledgement write has completed.
+        # The entry may already be gone when the transport closed concurrently.
+        def activate_listen_subscription(request_id)
+          @mutex.synchronize do
+            subscription = @listen_subscriptions[request_id]
+            subscription[:active] = true if subscription
+          end
+        end
+
         # Periodically writes an SSE keepalive comment frame to a listen stream so a silently dropped
         # connection is detected and its slot freed, rather than held until the next fan-out write.
         # Mirrors the legacy GET stream's `start_keepalive_thread`; a comment frame (not a data frame)
@@ -994,6 +1055,10 @@ module MCP
           # a slow or stalled subscriber must not block the transport, matching the legacy delivery paths.
           matched = @mutex.synchronize do
             @listen_subscriptions.filter_map do |request_id, 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]
+
               hit = if field
                 subscription[:filter][field]
               else
@@ -1002,24 +1067,32 @@ module MCP
                 uris.is_a?(Array) && uris.include?(uri)
               end
 
-              [request_id, subscription[:stream]] if hit
+              [request_id, subscription] if hit
             end
           end
 
-          matched.each do |request_id, stream|
+          matched.each do |request_id, subscription|
             meta = { RequestEnvelope::SUBSCRIPTION_ID_META_KEY.to_sym => request_id }
             notification_params = (params || {}).merge(_meta: meta)
             notification = { jsonrpc: "2.0", method: method, params: notification_params }
 
             begin
-              send_to_stream(stream, notification)
+              # The per-stream write mutex orders this write against a concurrent graceful teardown:
+              # once teardown has marked the entry closed and written its `SubscriptionsListenResult`,
+              # a delivery that snapshotted the entry before the registry was cleared skips it instead
+              # of writing after the final message.
+              subscription[:write_mutex].synchronize do
+                next if subscription[:closed]
+
+                send_to_stream(subscription[:stream], notification)
+              end
             rescue *STREAM_WRITE_ERRORS => e
               MCP.configuration.exception_reporter.call(
                 e,
                 { subscription_id: request_id, error: "Failed to send notification" },
               )
               remove_listen_subscription(request_id)
-              close_stream_safely(stream)
+              close_stream_safely(subscription[:stream])
             end
           end
         end
@@ -1038,20 +1111,27 @@ module MCP
           end
 
           removed.each do |request_id, subscription|
-            begin
-              send_to_stream(subscription[:stream], {
-                jsonrpc: "2.0",
-                id: 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 => request_id },
-                },
-              })
-            rescue *STREAM_WRITE_ERRORS
-              nil
+            # Marking the entry closed and writing the result under the stream's write mutex orders
+            # this against in-flight deliveries: 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
+
+              begin
+                send_to_stream(subscription[:stream], {
+                  jsonrpc: "2.0",
+                  id: 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 => request_id },
+                  },
+                })
+              rescue *STREAM_WRITE_ERRORS
+                nil
+              end
             end
             close_stream_safely(subscription[:stream])
           end
@@ -1595,6 +1675,14 @@ module MCP
             end
           end
 
+          # `Server` refuses a duplicate id as well, but only once the request reaches it. The SSE branch below
+          # registers this request's stream under that id first, so without this check the colliding request
+          # would take over the routing entry for the moment it takes to be rejected, and its `ensure` would then
+          # clear the entry the original request still needs.
+          if related_request_id && server_session&.in_flight?(related_request_id)
+            return request_id_conflict_response
+          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)
           else
@@ -1618,7 +1706,11 @@ module MCP
               session = @sessions[session_id]
               if session && related_request_id
                 session[:post_request_streams] ||= {}
-                session[:post_request_streams][related_request_id] = stream
+
+                # Claim the id only while it is free. `handle_regular_request` already refused the colliding request,
+                # so reaching an occupied slot means a race got past that check; leaving the first stream in place keeps
+                # its messages going where they belong.
+                session[:post_request_streams][related_request_id] ||= stream
               end
             end
 
@@ -1630,7 +1722,11 @@ module MCP
               if related_request_id
                 @mutex.synchronize do
                   session = @sessions[session_id]
-                  session[:post_request_streams]&.delete(related_request_id) if session
+                  # Only retire our own registration: a request that never claimed the id, or one whose claim has
+                  # already been replaced, must not unregister the stream that owns it.
+                  registered = session&.dig(:post_request_streams, related_request_id)
+
+                  session[:post_request_streams].delete(related_request_id) if registered.equal?(stream)
                 end
               end
 
@@ -1849,6 +1945,16 @@ module MCP
           )
         end
 
+        # The POST counterpart of the GET conflict above. A request id already in flight cannot be given
+        # a stream of its own, because the id is what routes request-scoped messages back.
+        def request_id_conflict_response
+          json_rpc_error_response(
+            status: 409,
+            code: JsonRpcHandler::ErrorCode::INVALID_REQUEST,
+            message: "Conflict: Request id is already in flight for this session",
+          )
+        end
+
         def setup_sse_stream(session_id)
           body = create_sse_body(session_id)