mcp 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237a819736a62982990aafa3889226e94101be576d2a2c917b4ce3f9be8bc5e1
-  data.tar.gz: 12bb5f7d9b6ecc0399cd3d6f591a21dbc2c0f087b7c8b0ffd9d38621d496671d
+  metadata.gz: 19daecce4ccef4ae391f54643fc8fca17360af39e58541404d090dab52858db8
+  data.tar.gz: 75f1cac8a1b8c89b6a6a067b763751f39184e1846de5cfe317b3f8e3886fc5a0
 SHA512:
-  metadata.gz: aed9090f1de375b2fbd54432e7dd5f2b59c50f0a1875594f6319c07fb213047e296579e85ecfc23941df58512b52eae8a4ba34e1b298156306f470b0632180f4
-  data.tar.gz: 179d5d8e4a88985fb1e5e50cc66a9b5b8860abdf3484d935cde65b04d1f9f9295ddec625c037984698e9e5ad5e993091ac082243202132292cde100a8830dabc
+  metadata.gz: c1653c778f8e782c1ed7c4b66c538076fdce5f35fa00af054f1c9d06c1e78335a02e91734cc90d6107f8ae089946d5085d56d6fc2eeb27a11c84cc6e3f663737
+  data.tar.gz: 29cf1b6ee37eed02b83745ce09731db507f64cb95dcb8376ad154525415807db717c8aebd96257c8261eda19b677317a719e8fbd37e0acf3d55e7d8aa1fd8883

data/README.md

@@ -9,7 +9,7 @@ Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
 - Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host
 - Build [MCP clients](https://ruby.sdk.modelcontextprotocol.io/client/) that connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization
 - Speak every standard transport: stdio and Streamable HTTP (including SSE), with a Rails integration
-- Cover the full protocol surface: server-to-client requests, multi round-trip results, notifications, progress, logging, cancellation, completions, and pagination
+- Cover the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions, and pagination
 
 ## Installation
 

data/lib/mcp/client/http.rb

@@ -1118,6 +1118,19 @@ module MCP
               },
             }
           end
+        elsif message["method"] == MCP::Methods::PING && (message["id"].is_a?(String) || message["id"].is_a?(Numeric))
+          # The ping receiver "MUST respond promptly with an empty response" (MCP ping utility),
+          # so an unhandled ping is answered with the empty result rather than Method not found.
+          # A JSON-RPC id is a String or a Number; the reference SDKs reject other shapes at
+          # schema validation, so a ping carrying one falls through to Method not found instead.
+          # The default lives here instead of in `@server_request_handlers`, whose `any?` opens
+          # the GET listening stream on connect: a built-in pong must not change listener behavior.
+          # A handler registered via `on_server_request("ping")` still wins through the branch above.
+          {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            id: message["id"],
+            result: {},
+          }
         else
           {
             jsonrpc: JsonRpcHandler::Version::V2_0,

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # The decision an `authorization_request_validator` is asked to approve: which authorization server this client is about to send the user to,
+      # and with which scopes.
+      #
+      # Handed over as one object rather than as keyword arguments so that later revisions of the MCP authorization specification can add to it
+      # without changing the shape every implementer wrote.
+      #
+      # Only the named readers are the contract. The positional access `Struct` also provides (`request[0]`, `to_a`, `each`) is not,
+      # so the representation can change later.
+      AuthorizationRequest = Struct.new(
+        # `issuer` of the authorization server selected from the MCP server's Protected Resource Metadata.
+        :authorization_server,
+        # The scopes about to be requested, as an Array. Chosen by the MCP server, through the `WWW-Authenticate` challenge or `scopes_supported`.
+        :scopes,
+        # The MCP server URL this client was configured with.
+        :server_url,
+        # The RFC 8707 `resource` the token is being requested for.
+        :resource,
+        keyword_init: true,
+      )
+    end
+  end
+end

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

@@ -60,7 +60,8 @@ module MCP
           private_key: nil,
           signing_algorithm: nil,
           scope: nil,
-          storage: nil
+          storage: nil,
+          authorization_request_validator: nil
         )
           if blank?(client_id)
             raise InvalidCredentialsError, "client_id is required for the client_credentials grant."
@@ -103,6 +104,7 @@ module MCP
           @signing_algorithm = signing_algorithm
           @scope = scope
           @storage = storage || InMemoryStorage.new
+          @authorization_request_validator = authorization_request_validator
           @storage.save_client_information(client_information)
         end
 

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

@@ -35,7 +35,7 @@ module MCP
 
         attr_reader :scope, :storage
 
-        def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil)
+        def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil, authorization_request_validator: nil)
           if blank?(client_id)
             raise InvalidConfigurationError, "client_id is required for the jwt-bearer grant."
           end
@@ -51,6 +51,7 @@ module MCP
           @assertion_provider = assertion_provider
           @scope = scope
           @storage = storage || InMemoryStorage.new
+          @authorization_request_validator = authorization_request_validator
           @storage.save_client_information(
             "client_id" => client_id,
             "client_secret" => client_secret,

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

@@ -23,6 +23,11 @@ module MCP
         # should leave the refresh token intact.
         class InvalidGrantError < AuthorizationError; end
 
+        # Raised when `authorization_request_validator` returns a falsy value. Separate from its parent
+        # so that a caller can tell a refusal by its own policy from a network, discovery,
+        # or authorization server metadata failure by rescuing a class rather than by matching the message text.
+        class AuthorizationRefusedError < AuthorizationError; end
+
         def initialize(provider:, http_client_factory: nil)
           @provider = provider
           @http_client_factory = http_client_factory || -> { default_http_client }
@@ -63,17 +68,22 @@ module MCP
 
           case provider_authorization_flow
           when :client_credentials
-            return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
+            return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope, server_url: server_url)
           when :jwt_bearer
-            return run_jwt_bearer!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
+            return run_jwt_bearer!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope, server_url: server_url)
           end
 
           ensure_pkce_supported!(as_metadata)
 
-          client_info = ensure_client_registered(as_metadata: as_metadata)
-
           effective_scope = resolve_scope(scope: scope, prm: prm || {})
           effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
+
+          # Asked before registering, not after: a refusal must not leave this client registered at an authorization server
+          # the embedding application has just rejected.
+          authorize_request!(as_metadata: as_metadata, scope: effective_scope, server_url: server_url, resource: resource)
+
+          client_info = ensure_client_registered(as_metadata: as_metadata)
+
           pkce = PKCE.generate
           state = SecureRandom.urlsafe_base64(32)
 
@@ -109,7 +119,7 @@ module MCP
             resource: resource,
           )
 
-          @provider.save_tokens(tokens)
+          save_tokens_issued_by(tokens, as_metadata: as_metadata)
           :authorized
         end
 
@@ -119,17 +129,19 @@ module MCP
         # and no `offline_access` augmentation because the grant does not issue a refresh token (OAuth 2.1 Section 4.3.3).
         # The pre-registered `client_id` / `client_secret` come from the provider's stored `client_information`.
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
-        def run_client_credentials!(as_metadata:, prm:, resource:, scope:)
+        def run_client_credentials!(as_metadata:, prm:, resource:, scope:, server_url:)
           client_info = client_credentials_client_info
           ensure_client_credentials_issuer!(client_info, as_metadata: as_metadata)
 
           form = { "grant_type" => "client_credentials" }
           effective_scope = resolve_scope(scope: scope, prm: prm)
+          authorize_request!(as_metadata: as_metadata, scope: effective_scope, server_url: server_url, resource: resource)
           form["scope"] = effective_scope if effective_scope
           form["resource"] = resource if resource
 
           tokens = post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
-          @provider.save_tokens(tokens)
+          save_tokens_issued_by(tokens, as_metadata: as_metadata)
+
           :authorized
         end
 
@@ -173,12 +185,18 @@ module MCP
         # and security checks as `run!`; like `client_credentials`, there is no PKCE, redirect, or authorization request.
         # The assertion's audience is the issuer identifier that `ensure_issuer_matches!` validated.
         # https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
-        def run_jwt_bearer!(as_metadata:, prm:, resource:, scope:)
+        def run_jwt_bearer!(as_metadata:, prm:, resource:, scope:, server_url:)
           client_info = @provider.client_information
           unless client_info.is_a?(Hash) && client_info_required_value(client_info, "client_id")
             raise AuthorizationError, "Cannot run the jwt-bearer grant: the provider has no stored `client_id`."
           end
 
+          # Asked before the assertion is minted, for the same reason registration waits on the authorization-code grant:
+          # obtaining an ID-JAG sends the identity provider an audience of this authorization server, which must not happen once
+          # the host has refused it.
+          effective_scope = resolve_scope(scope: scope, prm: prm)
+          authorize_request!(as_metadata: as_metadata, scope: effective_scope, server_url: server_url, resource: resource)
+
           assertion = @provider.jwt_bearer_assertion(audience: as_metadata["issuer"], resource: resource)
           if assertion.nil? || assertion.to_s.empty?
             raise AuthorizationError, "The provider's assertion_provider returned no ID-JAG assertion."
@@ -188,12 +206,11 @@ module MCP
             "grant_type" => "urn:ietf:params:oauth:grant-type:jwt-bearer",
             "assertion" => assertion,
           }
-          effective_scope = resolve_scope(scope: scope, prm: prm)
           form["scope"] = effective_scope if effective_scope
           form["resource"] = resource if resource
 
           tokens = post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
-          @provider.save_tokens(tokens)
+          save_tokens_issued_by(tokens, as_metadata: as_metadata)
           :authorized
         end
 
@@ -242,6 +259,8 @@ module MCP
             server_url: server_url,
           )
 
+          ensure_token_issuer!(as_metadata: as_metadata)
+
           client_info = if have_stored_client_info
             # Pre-registered / DCR-issued `client_information` always wins: if the user picked an explicit identity,
             # do not silently swap it for the CIMD URL even when the AS also advertises CIMD support.
@@ -262,7 +281,7 @@ module MCP
             resource: resource,
           )
 
-          @provider.save_tokens(preserve_refresh_token(new_tokens, refresh_token))
+          save_tokens_issued_by(preserve_refresh_token(new_tokens, refresh_token), as_metadata: as_metadata)
           :refreshed
         end
 
@@ -499,6 +518,43 @@ module MCP
         # the authorization server on two loopback ports), and deployments that never leave a corporate network.
         # Only a server reachable on the public internet is barred from steering the client inward.
         # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+        # Hands the embedding application the authorization server and the scopes that are about to be requested,
+        # and abandons the flow when it refuses them.
+        #
+        # Both values are chosen by the MCP server: it names its own authorization server in Protected
+        # Resource Metadata and states the scopes in `scopes_supported` or the `WWW-Authenticate` challenge.
+        # Neither the specification nor any MCP SDK binds that choice to the server's own identity,
+        # and validating that a token was issued for the intended audience is a responsibility the specification
+        # places on MCP servers rather than on clients.
+        # A host that knows which providers its user deals with can apply that knowledge here.
+        #
+        # The scopes are passed on unchanged whatever the host decides, because the specification requires
+        # a client to treat the challenged scopes as authoritative for the operation; the choice offered is
+        # to proceed or to stop, not to quietly ask for less. A provider without the hook proceeds as before.
+        #
+        # Only asked when a new grant is being requested. A refresh is not a new grant, and the host already answered
+        # this question for that authorization server, so `refresh!` enforces `ensure_token_issuer!` instead:
+        # an authorization server that has changed since the tokens were issued sends the flow back through here,
+        # where the host sees the new one and decides again.
+        def authorize_request!(as_metadata:, scope:, server_url:, resource:)
+          return unless @provider.respond_to?(:authorization_request_validator)
+          return unless (validator = @provider.authorization_request_validator)
+
+          request = AuthorizationRequest.new(
+            authorization_server: as_metadata["issuer"],
+            scopes: scope.to_s.split,
+            server_url: server_url,
+            resource: resource,
+          ).freeze
+
+          return if validator.call(request)
+
+          raise AuthorizationRefusedError, <<~MESSAGE
+            The authorization request was refused by `authorization_request_validator` \
+            (authorization server #{request.authorization_server.inspect}, scopes #{request.scopes.inspect}).
+          MESSAGE
+        end
+
         def ensure_routable_destination!(url, label:, server_url:)
           return unless private_network_url?(url)
           return if private_network_url?(server_url)
@@ -669,6 +725,39 @@ module MCP
         # the error and falls back to the full flow, which discards the stale registration and re-registers.
         # Credentials without an `"issuer"` binding predate this check and are allowed through;
         # CIMD `client_id`s are portable.
+        # Records which authorization server minted these tokens, alongside the tokens themselves.
+        # SEP-2352 already binds *client credentials* to their issuer; this binds the *tokens*, which that
+        # SEP leaves unbound.
+        # Stored in the token hash so it travels through any `storage` a caller supplied, without widening
+        # the storage interface that custom implementations have to satisfy.
+        def save_tokens_issued_by(tokens, as_metadata:)
+          issuer = as_metadata["issuer"]
+          tokens = tokens.merge("issuer" => issuer) if tokens.is_a?(Hash) && issuer
+
+          @provider.save_tokens(tokens)
+        end
+
+        # Refuses to present a refresh token to an authorization server other than the one that issued it.
+        # `refresh!` rediscovers the authorization server from Protected Resource Metadata every time,
+        # so the server named for a session can differ from the one the stored tokens came from.
+        # Unlike `ensure_refreshable_client_information!` this holds whatever the client identity is,
+        # including a Client ID Metadata Document URL, which is portable across authorization servers precisely
+        # so that re-registration is unnecessary.
+        #
+        # Tokens stored before this shipped carry no issuer and are left alone, matching how SEP-2352 treats
+        # client information without one; the binding takes effect from their next authorization.
+        # The caller answers a refusal by running the full authorization flow, which is where the embedding application
+        # is asked about the new authorization server.
+        def ensure_token_issuer!(as_metadata:)
+          stored_issuer = read_token("issuer")
+          return if stored_issuer.nil? || stored_issuer == as_metadata["issuer"]
+
+          raise AuthorizationError, <<~MESSAGE
+            Cannot refresh: the stored tokens were issued by a different authorization server (stored issuer #{stored_issuer.inspect}, \
+            current #{as_metadata["issuer"].inspect}); re-authorization is required.
+          MESSAGE
+        end
+
         def ensure_refreshable_client_information!(client_info, as_metadata:)
           stored_issuer = client_info_required_value(client_info, "issuer")
           return if stored_issuer.nil?

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

@@ -86,7 +86,8 @@ module MCP
           callback_handler:,
           scope: nil,
           storage: nil,
-          client_id_metadata_document_url: nil
+          client_id_metadata_document_url: nil,
+          authorization_request_validator: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -115,6 +116,7 @@ module MCP
           @scope = scope
           @storage = storage || InMemoryStorage.new
           @client_id_metadata_document_url = client_id_metadata_document_url
+          @authorization_request_validator = authorization_request_validator
         end
 
         # Identifies the OAuth flow this provider drives.

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

@@ -14,6 +14,13 @@ module MCP
       # `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`
       # (see `InMemoryStorage`).
       module StorageBackedProvider
+        # Optional `->(request) { true | false }` hook, called with an `AuthorizationRequest`.
+        # An MCP server names its own authorization server and the scopes to ask for, so this is where
+        # an embedding application sees both before the request is made and can decline to proceed.
+        # `nil` (the default) authorizes whatever the server asked for, which is the behavior every
+        # MCP SDK has today.
+        attr_reader :authorization_request_validator
+
         def access_token
           tokens&.dig("access_token") || tokens&.dig(:access_token)
         end

data/lib/mcp/client/oauth.rb

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

data/lib/mcp/client/stdio.rb

@@ -436,6 +436,18 @@ module MCP
 
           parsed = JSON.parse(line.strip)
 
+          # A frame carrying `method` is a request or notification, never the awaited response,
+          # whatever its id says: JSON-RPC id spaces are per sender, so a server-chosen ping id
+          # may legitimately collide with the awaited one. Pings are answered;
+          # other server-to-client requests over stdio stay unsupported as documented,
+          # and notifications carry no id.
+          if parsed.is_a?(Hash) && parsed.key?("method")
+            # A JSON-RPC id is a String or a Number; the reference SDKs reject other shapes at
+            # schema validation, so a ping carrying one is skipped rather than echoed back.
+            answer_ping(parsed) if parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"])
+            next
+          end
+
           # A JSON-RPC message is an object; skip a non-object frame (array or scalar)
           # the same way as a frame without an id.
           next unless parsed.is_a?(Hash) && parsed.key?("id")
@@ -451,6 +463,22 @@ module MCP
         )
       end
 
+      # The ping receiver "MUST respond promptly with an empty response". Answered inline from
+      # the read loop, so a keepalive cannot stall unanswered while a response is awaited;
+      # between requests nothing reads stdout, and a queued ping is answered on the next read.
+      def answer_ping(parsed)
+        @write_mutex.synchronize do
+          write_message({ jsonrpc: JsonRpcHandler::Version::V2_0, id: parsed["id"], result: {} })
+        end
+      rescue RequestHandlerError
+        # Best effort: a pong cannot be delivered over a broken stdin, and the failure must not
+        # surface as an error of the unrelated request whose response the loop is reading.
+      end
+
+      def json_rpc_id?(id)
+        id.is_a?(String) || id.is_a?(Numeric)
+      end
+
       def ensure_running!
         return if @wait_thread.alive?
 

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)
@@ -723,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] = [] }
@@ -881,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
 
@@ -909,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)
@@ -918,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)
@@ -999,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
@@ -1007,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
@@ -1043,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

data/lib/mcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MCP
-  VERSION = "1.3.0"
+  VERSION = "1.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -46,6 +46,7 @@ files:
 - lib/mcp/client/mcp_param_headers.rb
 - lib/mcp/client/modern_envelope.rb
 - lib/mcp/client/oauth.rb
+- lib/mcp/client/oauth/authorization_request.rb
 - lib/mcp/client/oauth/bounded_body.rb
 - lib/mcp/client/oauth/client_credentials_provider.rb
 - lib/mcp/client/oauth/cross_app_access_provider.rb
@@ -107,7 +108,7 @@ licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.3.0
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.5.0
   homepage_uri: https://ruby.sdk.modelcontextprotocol.io
   source_code_uri: https://github.com/modelcontextprotocol/ruby-sdk
   bug_tracker_uri: https://github.com/modelcontextprotocol/ruby-sdk/issues