mcp 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 402b424bd7e0cf6abce69f6613b929d63a259d8d71fbc479378a0de40e2b6bde
-  data.tar.gz: b4fa00e094ab14bf0adf36165cb6cda2e0747cb369fff727227bad16edbd4090
+  metadata.gz: 19daecce4ccef4ae391f54643fc8fca17360af39e58541404d090dab52858db8
+  data.tar.gz: 75f1cac8a1b8c89b6a6a067b763751f39184e1846de5cfe317b3f8e3886fc5a0
 SHA512:
-  metadata.gz: 50741bdb178837e7f87458c91f1b5c0d678139f4949099321d093c0c9936542e6c01b7666b393c5009ad88c78aacac2aa32c28ab5c6c2cdb871bbb09326b9a96
-  data.tar.gz: 75f6bce397dd2034e6315ed33ad9bf908656e5e4ecb53f625d40053d38a7b7373561d87a13798551517cb338798083dabe8e46d4cf4218c76fbcd99536bdf35c
+  metadata.gz: c1653c778f8e782c1ed7c4b66c538076fdce5f35fa00af054f1c9d06c1e78335a02e91734cc90d6107f8ae089946d5085d56d6fc2eeb27a11c84cc6e3f663737
+  data.tar.gz: 29cf1b6ee37eed02b83745ce09731db507f64cb95dcb8376ad154525415807db717c8aebd96257c8261eda19b677317a719e8fbd37e0acf3d55e7d8aa1fd8883

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.4.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.4.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