mcp 1.7.0 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87f6233cbd083a14b47183b21558ee995c06953ef5bb8d9ea568eca8e69103de
-  data.tar.gz: 11697a1b6e71297211fac5ecf411ac381a064e66274ac9c9a9640087284859ad
+  metadata.gz: 255e316335616783063d8a7374f385ff10b99c9ddef24571734e19b6ec6f5f93
+  data.tar.gz: 07021e227f5b1be05fd2c1e4dc88e0d563bc963b6f1190f998aa632ed6871031
 SHA512:
-  metadata.gz: ec9899cc307eb88706aded076b0e7be9bb2bdbf2fbf52c3d8f8f7a7ebe05dbb1da802ebfc8ea9bc1d5ecc18c361a2249488815c60175650203815a084aad9833
-  data.tar.gz: c43d95b541108f64ac594567e44f3de9e103f4f52c2c122ef0f0d90dcaa52b391b419c536cf4653c784299324a71c23c9bb7da9a7c4f9f69db87c2ab1d730871
+  metadata.gz: 3d496817c30ae59b7f99704fead73cc9dfe5d926a87455a5c51fcc766bdf299d943ce86c0d43ca859d870a488df191cc0a4bdeba302b95d8ebcf084730743a68
+  data.tar.gz: 6291785257c054baf3570fb9baef4ecb1db006c920608ad69239460e2494610fa9133341bdf903a4c127f7ab40146f2bf9eecb34266621cba172a08ef52812f0

data/README.md

@@ -6,7 +6,7 @@ Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.
 
 ## Features
 
-- Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host
+- Build [MCP servers](https://ruby.sdk.modelcontextprotocol.io/server/) that expose tools, prompts, and resources to any MCP host, with OAuth 2.1 resource-server protection
 - 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 requests, notifications, progress, logging, cancellation, completions, and pagination

data/lib/json_rpc_handler.rb

@@ -55,14 +55,19 @@ module JsonRpcHandler
 
   def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
     begin
-      request = JSON.parse(request_json, symbolize_names: true)
+      begin
+        request = JSON.parse(request_json, symbolize_names: true)
+      rescue JSON::ParserError, EncodingError
+        # `symbolize_names` raises `EncodingError` for a key that is not valid UTF-8, a parse error as well.
+        # Rescued around the parse only, so an error raised while handling keeps its own classification.
+        return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+          code: ErrorCode::PARSE_ERROR,
+          message: "Parse error",
+          data: "Invalid JSON",
+        }).to_json
+      end
+
       response = handle(request, id_validation_pattern: id_validation_pattern, &method_finder)
-    rescue JSON::ParserError
-      response = error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
-        code: ErrorCode::PARSE_ERROR,
-        message: "Parse error",
-        data: "Invalid JSON",
-      })
     rescue StandardError
       # Last-resort guard so an unexpected handling error returns a JSON-RPC error
       # instead of escaping to the transport loop.
@@ -90,17 +95,25 @@ module JsonRpcHandler
 
     error = if !valid_version?(request[:jsonrpc])
       "JSON-RPC version must be 2.0"
+    elsif request.key?(:id) && id.nil?
+      # JSON-RPC 2.0 allows a null id; MCP rules it out: a request carries a string or an integer id,
+      # and a notification carries no id member at all. Refused rather than run as a notification,
+      # since a sender that wrote an id meant to be answered.
+      "Request ID must not be null"
     elsif !valid_id?(id, id_validation_pattern)
-      "Request ID must match validation pattern, or be an integer or null"
+      if id_validation_pattern
+        "Request ID must be a string matching the validation pattern, or an integer"
+      else
+        "Request ID must be a string or an integer"
+      end
     elsif !valid_method_name?(request[:method])
       'Method name must be a string and not start with "rpc."'
     end
 
     # Per JSON-RPC 2.0 (Response object, `id`), the error response must carry
-    # the same id as the request when the id could be detected; null is only
-    # for requests whose id could not be determined. `error_response` nils out
-    # ids that fail validation, and the `:unknown_id` sentinel keeps a response
-    # (with a null id) being emitted when the request carried no id at all.
+    # the same id as the request when the id could be detected. `error_response`
+    # leaves the id out for ids that fail validation, and the `:unknown_id` sentinel
+    # keeps a response (without an id) being emitted when the request carried no id at all.
     return error_response(id: id.nil? ? :unknown_id : id, id_validation_pattern: id_validation_pattern, error: {
       code: ErrorCode::INVALID_REQUEST,
       message: "Invalid Request",
@@ -176,7 +189,9 @@ module JsonRpcHandler
 
   def valid_id?(id, pattern = nil)
     return true if id.nil? || id.is_a?(Integer)
-    return false unless id.is_a?(String)
+    # A string that is not valid in its encoding cannot be written into the response,
+    # and matching a pattern against it raises, so it is refused before the method runs.
+    return false unless id.is_a?(String) && id.valid_encoding?
 
     pattern ? id.match?(pattern) : true
   end
@@ -197,11 +212,15 @@ module JsonRpcHandler
     } unless id.nil?
   end
 
+  # An error response for a request whose id could not be read carries no `id` member: JSON-RPC 2.0 puts
+  # a null there, but the MCP schema allows only a string or an integer, and the Streamable HTTP transport
+  # specification describes such a body as an error response that has no id.
   def error_response(id:, id_validation_pattern:, error:)
-    {
-      jsonrpc: Version::V2_0,
-      id: valid_id?(id, id_validation_pattern) ? id : nil,
-      error: error.compact,
-    } unless id.nil?
+    return if id.nil?
+
+    response = { jsonrpc: Version::V2_0 }
+    response[:id] = id if valid_id?(id, id_validation_pattern)
+    response[:error] = error.compact
+    response
   end
 end

data/lib/mcp/client/http.rb

@@ -120,7 +120,7 @@ module MCP
       # the incrementally parsed JSON-RPC response, the last received SSE event id (for `Last-Event-ID`),
       # and the server's `retry:` reconnection delay. Non-SSE bodies accumulate in `buffer` for the JSON path.
       class SSEStream
-        attr_reader :buffer, :response, :last_event_id, :retry_ms
+        attr_reader :buffer, :response, :response_headers, :last_event_id, :retry_ms
         attr_accessor :abortable
 
         def initialize(abortable:, max_message_bytes: MAX_MESSAGE_BYTES, on_request: nil)
@@ -132,6 +132,7 @@ module MCP
           @response = nil
           @last_event_id = nil
           @retry_ms = nil
+          @response_headers = nil
         end
 
         # Whether the server sent a SEP-1699 priming event (any event carrying an id),
@@ -146,9 +147,10 @@ module MCP
         # abort the stream so an over-limit tail cannot mask a response that already arrived.
         def on_data
           proc do |chunk, _received_bytes, env|
+            @response_headers ||= env.response_headers if env
             if event_stream?(env)
               feed(chunk)
-              raise StreamAbort if @abortable && @response
+              raise StreamAbort if @abortable && @response && !error_status?(env)
 
               if parser_buffered_bytes > @max_message_bytes
                 raise MessageTooLargeError, "Server SSE event exceeds #{@max_message_bytes} bytes without completing"
@@ -163,6 +165,16 @@ module MCP
           end
         end
 
+        # An error status must reach Faraday's `raise_error` middleware (which drives the
+        # OAuth and step-up retries in `send_request`), so the stream is read to EOF instead
+        # of aborting when the server answered with one. This is the behavior every
+        # method had before the abort shortcut. It is the only case that still needs
+        # the finished response object.
+        def error_status?(env)
+          status = env.status if env.respond_to?(:status)
+          status.is_a?(Integer) && status >= 400
+        end
+
         # A fresh parser for a new HTTP connection (reconnection GET),
         # so a partial line from the previous stream cannot corrupt the next one.
         def reset_parser!
@@ -202,9 +214,10 @@ module MCP
 
             if parsed.key?("result") || parsed.key?("error")
               @response ||= parsed
-            elsif parsed["method"] && parsed.key?("id")
-              # A server-to-client request (e.g. `elicitation/create`) delivered
-              # on the stream while the original request is still pending.
+            elsif parsed["method"] && parsed.key?("id") && JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+              # A server-to-client request (e.g. `elicitation/create`) delivered on the stream while
+              # the original request is still pending. One that is not JSON-RPC 2.0 is dropped unanswered,
+              # as the TypeScript client drops it at schema validation.
               @on_request&.call(parsed)
             end
           end
@@ -399,6 +412,7 @@ module MCP
           )
         end
 
+        request_id = request[:id] || request["id"]
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
         oauth_retried = false
@@ -406,10 +420,13 @@ module MCP
 
         begin
           # The response is consumed incrementally so that an SSE stream the server holds open
-          # (or closes early per SEP-1699) can be handled; `initialize` streams are read to EOF
-          # so the response object (and its `Mcp-Session-Id` header) is always available for capture.
+          # (or closes early per SEP-1699) can be handled. Every request, `initialize` included,
+          # aborts once its response event arrives: `SSEStream` has already captured the response
+          # headers from the streaming `env` by then, so `Mcp-Session-Id` survives the abort.
+          # When `env` is unavailable (Faraday < 2.5 or an adapter without `on_data` support)
+          # nothing aborts and the stream is still read to EOF, as before.
           stream = SSEStream.new(
-            abortable: method.to_s != MCP::Methods::INITIALIZE,
+            abortable: true,
             max_message_bytes: @max_message_bytes,
             on_request: ->(message) { dispatch_server_request(message) },
           )
@@ -417,16 +434,22 @@ module MCP
           yield if block_given?
 
           response = begin
-            client.post("", request, session_headers.merge(request_metadata_headers(method, params))) do |req|
-              req.options.on_data = stream.on_data
+            redacting_authorization_header do
+              client.post("", request, session_headers.merge(request_metadata_headers(method, params))) do |req|
+                req.options.on_data = stream.on_data
+              end
             end
           rescue StreamAbort
             nil
           end
 
-          body = resolve_response_body(stream, response, method, params)
+          body = resolve_response_body(stream, response, request_id, method, params)
+
+          # Every way a response arrives (JSON body, SSE event, resumed stream) ends here. Checked before
+          # anything is learned from the body, and only for a request: a notification awaits no response.
+          reject_invalid_response!(body, method, params) if request_id
 
-          capture_session_info(method, response, body) if response
+          capture_session_info(method, response ? response.headers : stream.response_headers, body)
           capture_mcp_param_declarations(method, params, body)
 
           body
@@ -522,7 +545,7 @@ module MCP
       def send_notification(notification:)
         method = notification[:method] || notification["method"]
 
-        client.post("", notification, session_headers)
+        redacting_authorization_header { client.post("", notification, session_headers) }
         nil
       rescue Faraday::Error => e
         raise RequestHandlerError.new(
@@ -550,7 +573,7 @@ module MCP
         end
 
         begin
-          client.delete("", nil, session_headers)
+          redacting_authorization_header { client.delete("", nil, session_headers) }
         rescue Faraday::ClientError => e
           raise unless [404, 405].include?(e.response&.dig(:status))
         ensure
@@ -955,11 +978,11 @@ module MCP
         !(tokens["refresh_token"] || tokens[:refresh_token]).to_s.empty?
       end
 
-      def capture_session_info(method, response, body)
+      def capture_session_info(method, headers, body)
         return unless method.to_s == Methods::INITIALIZE
 
         # Faraday normalizes header names to lowercase.
-        session_id = response.headers[SESSION_ID_HEADER.downcase]
+        session_id = headers[SESSION_ID_HEADER.downcase]
         @session_id ||= session_id unless session_id.to_s.empty?
         @protocol_version ||= body.is_a?(Hash) ? body.dig("result", "protocolVersion") : nil
       end
@@ -1045,6 +1068,51 @@ module MCP
         [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0.001].max
       end
 
+      # Runs a request on the transport's connection and, when Faraday raises, replaces the value of the `Authorization` header
+      # in the request headers the exception retains before it leaves the transport.
+      # Faraday's `raise_error` middleware keeps a reference to `env.request_headers` in `Faraday::Error#response`
+      # under `:request`, so the exception that becomes `RequestHandlerError#original_error` (and its `cause`) would otherwise print
+      # the bearer token through `inspect`, which is what error reporters and log lines do with it. The request is complete by
+      # the time the exception surfaces, and every request builds its own headers from the connection's defaults,
+      # so the rewrite reaches neither those defaults nor a later request.
+      def redacting_authorization_header
+        yield
+      rescue Faraday::Error => e
+        redact_authorization_header!(e)
+        raise
+      end
+
+      # `raise_error` retains the request as a Hash under `:request`; a JSON middleware the customizer added raises
+      # `Faraday::ParsingError` with the `Faraday::Response` itself, whose `env` holds the request headers.
+      def redact_authorization_header!(error)
+        response = error.response
+
+        if response.is_a?(Hash)
+          request = response[:request]
+          redact_authorization_header_in!(request, :headers) if request.is_a?(Hash)
+        elsif response.respond_to?(:env) && response.env.respond_to?(:request_headers)
+          redact_authorization_header_in!(response.env, :request_headers)
+        end
+      end
+
+      # The headers are a `Faraday::Utils::Headers`, which spells the name `Authorization` whatever the caller wrote,
+      # unless a customizer middleware replaced them with a plain Hash or froze them: the name is matched regardless
+      # of case so such a Hash is covered too, and a frozen object is swapped for a copy, so the redaction never
+      # raises in place of the error it is redacting.
+      def redact_authorization_header_in!(holder, key)
+        headers = holder[key]
+        return unless headers.is_a?(Hash)
+
+        names = headers.each_key.select { |name| name.to_s.casecmp?("authorization") }
+        return if names.empty?
+
+        headers = holder[key] = headers.dup if headers.frozen?
+
+        names.each do |name|
+          headers[name] = "[redacted]"
+        end
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError
@@ -1054,8 +1122,11 @@ module MCP
       end
 
       # Determines the logical JSON-RPC body of the exchange after the POST stream finished
-      # (or was aborted because the response already arrived).
-      def resolve_response_body(stream, response, method, params)
+      # (or was aborted because the response already arrived). A notification (no `request_id`) awaits
+      # no response, so any success status acknowledges it, as it does for the TypeScript and Python clients,
+      # which check the content type of a response only for a request; the spec has the server answer
+      # a notification with 202, but a server answering with another 2xx is accepted as well.
+      def resolve_response_body(stream, response, request_id, method, params)
         return stream.response if stream.response
 
         # 202 Accepted is the server's ACK for a JSON-RPC notification or response; no body is expected.
@@ -1073,6 +1144,9 @@ module MCP
             return stream.response if stream.response
           end
 
+          # A stream that ends without a response has acknowledged a notification; there is nothing to resume for.
+          return if request_id.nil? && response.success?
+
           # SEP-1699: a graceful close after a priming event (an event with an id) but before
           # the response means "reconnect via GET to resume".
           return await_response_after_disconnect(stream, method, params) if stream.primed?
@@ -1089,6 +1163,8 @@ module MCP
           # added by the Faraday customizer may have parsed it already.
           response.body.is_a?(String) ? parse_json_buffer(response.body, method, params) : response.body
         else
+          return if request_id.nil? && response.success?
+
           raise RequestHandlerError.new(
             "Unsupported Content-Type: #{content_type.inspect}. Expected application/json or text/event-stream.",
             { method: method, params: params },
@@ -1157,7 +1233,7 @@ module MCP
       end
 
       def send_client_response(response)
-        client.post("", response, session_headers)
+        redacting_authorization_header { client.post("", response, session_headers) }
       end
 
       def parse_json_buffer(buffer, method, params)
@@ -1172,6 +1248,20 @@ module MCP
         )
       end
 
+      # A response is a JSON object whose `jsonrpc` is exactly "2.0". No body at all (202, or an empty 200)
+      # is not a message and is left to the caller as before; a JSON `null` body parses to the same `nil`.
+      # The received value is left out of the message because it can be any JSON value.
+      def reject_invalid_response!(body, method, params)
+        return if body.nil?
+        return if body.is_a?(Hash) && JsonRpcHandler.valid_version?(body["jsonrpc"])
+
+        raise RequestHandlerError.new(
+          'Server response is not a valid JSON-RPC 2.0 message: "jsonrpc" must be "2.0"',
+          { method: method, params: params },
+          error_type: :parse_error,
+        )
+      end
+
       # SEP-1699 resumability: the server closed the SSE stream after a priming event
       # without delivering the response. Treat the graceful close like a network failure:
       # wait the `retry:` interval the server asked for (default 1000ms), then reconnect with
@@ -1206,12 +1296,14 @@ module MCP
           read_timeout = remaining_reconnection_budget(deadline)
 
           reconnect_response = begin
-            client.get("") do |req|
-              req.headers.update(session_headers)
-              req.headers["Accept"] = SSE_ACCEPT_HEADER
-              req.headers[LAST_EVENT_ID_HEADER] = stream.last_event_id if stream.last_event_id
-              req.options.read_timeout = read_timeout
-              req.options.on_data = stream.on_data
+            redacting_authorization_header do
+              client.get("") do |req|
+                req.headers.update(session_headers)
+                req.headers["Accept"] = SSE_ACCEPT_HEADER
+                req.headers[LAST_EVENT_ID_HEADER] = stream.last_event_id if stream.last_event_id
+                req.options.read_timeout = read_timeout
+                req.options.on_data = stream.on_data
+              end
             end
           rescue StreamAbort
             # The awaited response arrived on the reconnected stream.

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

@@ -19,6 +19,9 @@ module MCP
         METADATA_DIAGNOSTIC_MAX_LENGTH = 128
         METADATA_URL_MAX_LENGTH = 2048
 
+        # RFC 6749 scope-token: visible ASCII except space, double quote, and backslash.
+        SCOPE_TOKEN_FORMAT = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/.freeze
+
         # Token request parameters the flow sets itself. Its values win over a provider's `token_request_params`,
         # so a provider naming one of these is refused rather than left believing its value was sent.
         RESERVED_TOKEN_REQUEST_PARAMS = [
@@ -264,12 +267,14 @@ module MCP
 
           ensure_pkce_supported!(as_metadata)
 
-          effective_scope = resolve_scope(scope: scope, prm: prm)
+          effective_scope = resolve_scope(scope: scope, prm: prm, select_prm_scope: true)
           effective_scope = normalize_offline_access_scope(effective_scope, as_metadata: as_metadata)
+          endpoint_uri, endpoint_params = authorization_endpoint_parameters(as_metadata: as_metadata)
+          request_scope = authorization_request_scope(scope: effective_scope, endpoint_params: endpoint_params)
 
           # 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)
+          # the embedding application has just rejected. Use the scopes that will actually reach the browser URL.
+          authorize_request!(as_metadata: as_metadata, scope: request_scope, server_url: server_url, resource: resource)
 
           client_info = ensure_client_registered(as_metadata: as_metadata)
 
@@ -277,7 +282,8 @@ module MCP
           state = SecureRandom.urlsafe_base64(32)
 
           authorization_url = build_authorization_url(
-            as_metadata: as_metadata,
+            endpoint_uri: endpoint_uri,
+            endpoint_params: endpoint_params,
             client_id: client_info_required_value(client_info, "client_id"),
             scope: effective_scope,
             state: state,
@@ -850,16 +856,16 @@ module MCP
         # 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.
+        # The MCP server names its authorization server in Protected Resource Metadata and states scopes
+        # in `scopes_supported` or the `WWW-Authenticate` challenge. Authorization-code policy also sees
+        # any prefilled endpoint scope that will survive URL assembly.
         # 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.
+        # Challenged scopes are authoritative for the operation and bypass the PRM scope selector.
+        # The validator can accept or refuse them, not quietly request fewer scopes.
         #
         # 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:
@@ -1302,17 +1308,18 @@ module MCP
           AuthorizationError.new(message, error: error, error_description: description)
         end
 
-        # Per MCP 2025-11-25 Authorization and the TS/Python SDKs, scope resolution
-        # prefers the `WWW-Authenticate` challenge first, then `scopes_supported`
-        # from the Protected Resource Metadata, and falls back to a provider-supplied
-        # scope only if both are absent. The provider-supplied scope must not pre-empt
-        # a server-advertised one.
-        def resolve_scope(scope:, prm:)
+        # MCP scope selection prefers the challenge, then PRM `scopes_supported`, then the provider's fallback.
+        # Authorization-code clients may narrow only the PRM default, before `offline_access` augmentation.
+        def resolve_scope(scope:, prm:, select_prm_scope: false)
           return scope if scope && !scope.empty?
 
           # `prm` is nil on the legacy path, where nothing advertises scopes.
           supported = prm && prm["scopes_supported"]
-          return supported.join(" ") if supported.is_a?(Array) && !supported.empty?
+          if supported.is_a?(Array) && !supported.empty?
+            return select_prm_scopes(supported) if select_prm_scope
+
+            return supported.join(" ")
+          end
 
           return @provider.scope if @provider.scope && !@provider.scope.empty?
 
@@ -1334,7 +1341,8 @@ module MCP
         #   the authorization request even though the AS will not honour it. Stripping here keeps the SDK's
         #   own request consistent with the AS's advertisement.
         #
-        # Returns `nil` when the result is empty so `build_authorization_url` omits the `scope` parameter entirely.
+        # Returns `nil` when empty so the URL builder adds no flow-owned scope parameter; a prefilled scope
+        # can still survive and is checked by the authorization-request validator.
         # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207
         def normalize_offline_access_scope(scope, as_metadata:)
           scopes = scope.to_s.split
@@ -1354,6 +1362,28 @@ module MCP
           supported.is_a?(Array) && supported.include?("offline_access")
         end
 
+        # Selects a subset of the PRM default without changing challenges, provider fallback, or refresh policy.
+        def select_prm_scopes(scopes)
+          selector = @provider.scope_selector if @provider.respond_to?(:scope_selector)
+          return scopes.join(" ") unless selector
+
+          unless scopes.all? { |token| token.is_a?(String) && SCOPE_TOKEN_FORMAT.match?(token) }
+            raise AuthorizationError, "Protected Resource Metadata `scopes_supported` contains invalid OAuth scope tokens."
+          end
+
+          candidates = scopes.map { |token| token.dup.freeze }.freeze
+          candidate_index = candidates.to_h { |token| [token, true] }
+          selected = selector.call(candidates)
+          valid = selected.is_a?(Array) && selected.all? do |token|
+            token.is_a?(String) && SCOPE_TOKEN_FORMAT.match?(token) && candidate_index.key?(token)
+          end
+          unless valid
+            raise ArgumentError, "scope_selector must return an Array containing only scopes from PRM scopes_supported."
+          end
+
+          selected.empty? ? nil : selected.join(" ")
+        end
+
         def wants_refresh_token?
           metadata = @provider.client_metadata
           grant_types = metadata[:grant_types] || metadata["grant_types"]
@@ -1398,7 +1428,7 @@ module MCP
           @provider.client_id_metadata_document_url
         end
 
-        def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
+        def authorization_endpoint_parameters(as_metadata:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint
             raise AuthorizationError,
@@ -1412,6 +1442,23 @@ module MCP
               "Authorization server metadata `authorization_endpoint` is not a valid URI: #{e.message}."
           end
 
+          [uri, URI.decode_www_form(uri.query.to_s)]
+        end
+
+        # A flow scope replaces every endpoint scope; otherwise a single prefilled value survives.
+        # Decode once before policy approval and reuse those parameters when building the URL.
+        def authorization_request_scope(scope:, endpoint_params:)
+          return scope if scope
+
+          endpoint_scopes = endpoint_params.filter_map { |name, value| value if name == "scope" }
+          if endpoint_scopes.length > 1
+            raise AuthorizationError, "Authorization endpoint contains repeated `scope` parameters."
+          end
+
+          endpoint_scopes.first
+        end
+
+        def build_authorization_url(endpoint_uri:, endpoint_params:, client_id:, scope:, state:, code_challenge:, resource:)
           # A parameter the flow sets replaces any of the same name the endpoint URL already carries.
           # RFC 6749 Section 3.1 forbids sending a parameter twice, and which of two values a server would honor is
           # its own choice; on the legacy path the endpoint URL is served by the MCP server, whose query must not speak
@@ -1433,10 +1480,10 @@ module MCP
           own_params << ["resource", resource] if resource
           dropped_names = own_params.map(&:first) + ["request", "request_uri"]
 
-          params = URI.decode_www_form(uri.query.to_s).reject { |name, _value| dropped_names.include?(name) }
-          uri.query = URI.encode_www_form(params + own_params)
+          params = endpoint_params.reject { |name, _value| dropped_names.include?(name) }
+          endpoint_uri.query = URI.encode_www_form(params + own_params)
 
-          uri
+          endpoint_uri
         end
 
         def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:, redirect_uri: @provider.redirect_uri)

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

@@ -37,6 +37,10 @@ module MCP
       #   `run!` saves it, when `callback_handler` is omitted. Defaults to `DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` does not specify one.
+      # - `scope_selector` - Callable receiving a read-only Array of PRM `scopes_supported` tokens when
+      #   those defaults are selected without a challenged scope. Return an Array containing a subset;
+      #   `[]` requests none of the PRM defaults. Challenged scopes and provider fallback bypass it.
+      #   The existing `offline_access` policy runs afterward; endpoint query parameters are unchanged.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`. Persisted `client_information` is stamped with
@@ -108,6 +112,7 @@ module MCP
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
+          :scope_selector,
           :storage,
           :redirect_handler,
           :callback_handler,
@@ -120,6 +125,7 @@ module MCP
           redirect_handler:,
           callback_handler: nil,
           scope: nil,
+          scope_selector: nil,
           storage: nil,
           client_id_metadata_document_url: nil,
           authorization_request_validator: nil,
@@ -147,6 +153,10 @@ module MCP
                 "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
           end
 
+          unless scope_selector.nil? || scope_selector.respond_to?(:call)
+            raise ArgumentError, "scope_selector must respond to call (got #{scope_selector.class})."
+          end
+
           http_client_customizer = validated_http_client_customizer(http_client_customizer)
 
           unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
@@ -170,6 +180,7 @@ module MCP
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
+          @scope_selector = scope_selector
           @storage = storage
           @client_id_metadata_document_url = client_id_metadata_document_url
           @authorization_request_validator = authorization_request_validator

data/lib/mcp/client/stdio.rb

@@ -442,17 +442,22 @@ module MCP
           # 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"])
+            # A JSON-RPC id is a String or a Number, and `jsonrpc` is "2.0"; the reference SDKs reject
+            # other shapes at schema validation, so a ping carrying one is skipped rather than echoed back.
+            answer_ping(parsed) if answerable_ping?(parsed)
             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")
+          next unless parsed["id"] == request_id
 
-          return parsed if parsed["id"] == request_id
+          # Nothing else will answer the awaited request, so a response that is not JSON-RPC 2.0 fails it
+          # instead of being skipped: without a `read_timeout`, skipping would wait forever.
+          raise_invalid_response!(method, params) unless JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+
+          return parsed
         end
       rescue JSON::ParserError => e
         raise RequestHandlerError.new(
@@ -475,6 +480,10 @@ module MCP
         # surface as an error of the unrelated request whose response the loop is reading.
       end
 
+      def answerable_ping?(parsed)
+        parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"]) && JsonRpcHandler.valid_version?(parsed["jsonrpc"])
+      end
+
       def json_rpc_id?(id)
         id.is_a?(String) || id.is_a?(Numeric)
       end
@@ -532,6 +541,16 @@ module MCP
           error_type: :internal_error,
         )
       end
+
+      # The line framing is intact, so the transport stays usable; the received value is left out of
+      # the message because it can be any JSON value.
+      def raise_invalid_response!(method, params)
+        raise RequestHandlerError.new(
+          'Server response is not a valid JSON-RPC 2.0 message: "jsonrpc" must be "2.0"',
+          { method: method, params: params },
+          error_type: :internal_error,
+        )
+      end
     end
   end
 end