mcp 1.5.1 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a1945319168ba9681dadea47a487f973d718e7f3504418a2b4b6e60bc0a1ba4
-  data.tar.gz: 6523b4e444a94354adc9421c54c1091acbbb82e6d2789625fca5b47c8df60457
+  metadata.gz: 3cb0f742e469efeb15202b40310bfb2eab52b94bb208bab1f33cfd2204bcf8c9
+  data.tar.gz: 07df380a1dd652b6fd5deb0ddbafe3c3379bc6fa77c8a391f169f6a7fed11742
 SHA512:
-  metadata.gz: 9f67b440f824785842c513c350dcc6ffbe6753f6854924ae1655efce948dfde31fb29f5d431c763d314cef9863951722049aa45f1b2f3ccae667e6d621440007
-  data.tar.gz: 8fc66cc8e4f90c59eaeb3033ff0797735a6c0a1d91f0a2663f23b5250840f5a70b6854f24d55096cfb7288c66cda4c8d82b2616573af85677a35702a07c9070c
+  metadata.gz: c756d7552fbf3accc8eedc32876e715c1d34939ed8c44d9d540a97b46ccf4cc2d3a163f5ba5989277be6e8933bce374ccab80f27ddf62ed52f6ea27c0367a3c5
+  data.tar.gz: '0873ea9933d9b30e1c0e2bcbd6f56eb0c658f16736ae309007cd752b097cb9f75ebcead7277c89ea9f255f92f3f62d2d4f1ac5d4ae87cf36359df4e42e030d38'

data/README.md

@@ -101,7 +101,7 @@ stdio_transport = MCP::Client::Stdio.new(
 )
 client = MCP::Client.new(transport: stdio_transport)
 
-# Perform the MCP initialization handshake before sending any requests.
+# Negotiate the protocol lifecycle before sending any requests.
 client.connect
 
 # List available tools.

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

@@ -26,7 +26,7 @@ module MCP
         # Faraday `on_data` streaming callback. The chunks arrive decompressed: the default `Net::HTTP` adapter negotiates
         # `Accept-Encoding` itself and reads the body through `Net::HTTPResponse#inflater`, so a small compressed body
         # that expands past the cap is refused partway through the expansion rather than after it. That holds only while
-        # the connection leaves `Accept-Encoding` to the adapter; see `Flow#default_http_client`.
+        # the connection leaves `Accept-Encoding` to the adapter; see `Flow.build_http_client`.
         def on_data
           proc do |chunk, _received_bytes, _env|
             @buffer << chunk

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

@@ -37,11 +37,17 @@ module MCP
       #   also take the algorithm as an explicit option).
       # - `scope`   - String of space-separated scopes to request when the server's
       #   `WWW-Authenticate` and the Protected Resource Metadata do not specify one.
-      # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
-      #   `client_information`, and `save_client_information(info)`. Defaults to
-      #   an `InMemoryStorage`. The `client_id` / `client_secret` are written
-      #   into it so the token exchange reads them through the same path as
-      #   a pre-registered authorization-code client.
+      # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`, `client_information`,
+      #   and `save_client_information(info)`. Defaults to an `InMemoryStorage`.
+      #   The `client_id` / `client_secret` are written into it so the token exchange reads
+      #   them through the same path as a pre-registered authorization-code client.
+      # - `token_request_params` - Hash of String keys and values added to every
+      #   token request this provider makes, for parameters the authorization
+      #   server requires beyond the grant itself (Auth0's `audience`, for example).
+      #   A key in `Flow::RESERVED_TOKEN_REQUEST_PARAMS` raises `Flow::InvalidTokenRequestParamsError`.
+      #   The Hash is copied and frozen. See `StorageBackedProvider#token_request_params`.
+      # - `http_client_customizer` - Callable invoked with the `Faraday::Connection` the flow builds for
+      #   its own requests; see `StorageBackedProvider#http_client_customizer`.
       class ClientCredentialsProvider
         include StorageBackedProvider
 
@@ -61,7 +67,9 @@ module MCP
           signing_algorithm: nil,
           scope: nil,
           storage: nil,
-          authorization_request_validator: nil
+          authorization_request_validator: nil,
+          token_request_params: nil,
+          http_client_customizer: nil
         )
           if blank?(client_id)
             raise InvalidCredentialsError, "client_id is required for the client_credentials grant."
@@ -99,12 +107,16 @@ module MCP
             client_information["client_secret"] = client_secret
           end
 
+          http_client_customizer = validated_http_client_customizer(http_client_customizer)
+
           @client_id = client_id
           @private_key = private_key
           @signing_algorithm = signing_algorithm
           @scope = scope
           @storage = storage || InMemoryStorage.new
           @authorization_request_validator = authorization_request_validator
+          @token_request_params = frozen_token_request_params(token_request_params)
+          @http_client_customizer = http_client_customizer
           @storage.save_client_information(client_information)
         end
 

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

@@ -25,6 +25,12 @@ module MCP
       #   the Protected Resource Metadata do not specify one.
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`.
       #   Defaults to an `InMemoryStorage`.
+      # - `token_request_params` - Hash of String keys and values added to the `jwt-bearer` token request, for parameters
+      #   the authorization server requires beyond the grant itself. A key in `Flow::RESERVED_TOKEN_REQUEST_PARAMS` raises
+      #   `Flow::InvalidTokenRequestParamsError`. The Hash is copied and frozen.
+      #   See `StorageBackedProvider#token_request_params`.
+      # - `http_client_customizer` - Callable invoked with the `Faraday::Connection` the flow builds for its own requests;
+      #   see `StorageBackedProvider#http_client_customizer`.
       #
       # https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990
       class CrossAppAccessProvider
@@ -35,7 +41,16 @@ module MCP
 
         attr_reader :scope, :storage
 
-        def initialize(client_id:, client_secret:, assertion_provider:, scope: nil, storage: nil, authorization_request_validator: nil)
+        def initialize(
+          client_id:,
+          client_secret:,
+          assertion_provider:,
+          scope: nil,
+          storage: nil,
+          authorization_request_validator: nil,
+          token_request_params: nil,
+          http_client_customizer: nil
+        )
           if blank?(client_id)
             raise InvalidConfigurationError, "client_id is required for the jwt-bearer grant."
           end
@@ -48,10 +63,14 @@ module MCP
             raise InvalidConfigurationError, "assertion_provider must be callable as `call(audience:, resource:)` and return the ID-JAG assertion."
           end
 
+          http_client_customizer = validated_http_client_customizer(http_client_customizer)
+
           @assertion_provider = assertion_provider
           @scope = scope
           @storage = storage || InMemoryStorage.new
           @authorization_request_validator = authorization_request_validator
+          @token_request_params = frozen_token_request_params(token_request_params)
+          @http_client_customizer = http_client_customizer
           @storage.save_client_information(
             "client_id" => client_id,
             "client_secret" => client_secret,

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

@@ -336,6 +336,29 @@ module MCP
             uri.to_s
           end
 
+          # Drops userinfo, query and fragment from `url` and leaves the host and path spelled as given, for reporting
+          # a URL next to the request that failed, where it must still match the server's access log; `URI#to_s`
+          # still lowercases the scheme and drops an explicit default port. Unlike `canonicalize_origin_and_path`
+          # it neither normalizes nor resolves dot segments, so its cost stays linear in the URL length, which matters
+          # for a URL the server chose. A URL that does not parse is not echoed, since the raw value could carry
+          # the very credentials being dropped.
+          def redact_url(url)
+            uri = URI.parse(url.to_s)
+
+            uri.fragment = nil
+            uri.query = nil
+            # `URI::Generic#userinfo=` is a no-op on Ruby 2.7 (the project's minimum supported version),
+            # so clear the components individually.
+            if uri.respond_to?(:user) && (uri.user || uri.password)
+              uri.user = nil
+              uri.password = nil
+            end
+
+            uri.to_s
+          rescue URI::Error
+            "[unparseable URL]"
+          end
+
           # Returns true when `prm` (a PRM `resource` URL) covers `server` (the MCP endpoint URL):
           # same scheme/host/port, with PRM's path being a prefix of the server's path. When PRM
           # also advertises a query string, the server's query MUST be identical to it (otherwise

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

@@ -14,7 +14,38 @@ module MCP
       # `Provider`; this class consumes a Provider plus signal data extracted from
       # the failing response (resource_metadata URL, scope challenge).
       class Flow
-        class AuthorizationError < StandardError; end
+        TOKEN_ENDPOINT_ERROR_MAX_LENGTH = 128
+        TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH = 512
+        METADATA_DIAGNOSTIC_MAX_LENGTH = 128
+        METADATA_URL_MAX_LENGTH = 2048
+
+        # 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 = [
+          "grant_type",
+          "client_id",
+          "client_secret",
+          "client_assertion",
+          "client_assertion_type",
+          "scope",
+          "resource",
+          "code",
+          "code_verifier",
+          "redirect_uri",
+          "refresh_token",
+          "assertion",
+        ].freeze
+
+        class AuthorizationError < StandardError
+          attr_reader :http_status, :error, :error_description
+
+          def initialize(message = nil, http_status: nil, error: nil, error_description: nil)
+            super(message)
+            @http_status = http_status
+            @error = error
+            @error_description = error_description
+          end
+        end
 
         # Raised specifically when the token endpoint rejects a grant with
         # `error: "invalid_grant"` (RFC 6749 §5.2). Callers use this to
@@ -28,6 +59,136 @@ module MCP
         # or authorization server metadata failure by rescuing a class rather than by matching the message text.
         class AuthorizationRefusedError < AuthorizationError; end
 
+        # Raised by metadata discovery when every candidate URL answered that nothing usable is published there
+        # (a `4xx` other than `429`, a redirect that was not followed, or a body that is not a JSON object).
+        # The only discovery failure that may select the legacy 2025-03-26 path.
+        class MetadataNotPublishedError < AuthorizationError; end
+
+        # Raised by metadata discovery when the answer says nothing about what is published: the request failed to
+        # reach the server, or a candidate answered `5xx` or `429`. Falling back on this would move
+        # the flow to a different authorization server because of a transient failure, so it is surfaced instead,
+        # as the TypeScript SDK does for network errors outside browsers and the Python SDK does for both.
+        class MetadataUnreachableError < AuthorizationError; end
+
+        # Raised for a `token_request_params` value the SDK refuses: a reserved key, a Hash comparing keys by identity,
+        # or anything but a Hash of Strings. An `ArgumentError` because the value is a configuration mistake,
+        # not a failed authorization, and deliberately outside `AuthorizationError`, which `MCP::Client::HTTP` treats on
+        # a failed refresh as a reason to run the interactive flow.
+        class InvalidTokenRequestParamsError < ArgumentError; end
+
+        # Raised by `RequestedOriginGuard` when middleware added through the provider's `http_client_customizer`
+        # would send a request to an origin other than the one the flow validated, or has dropped the record of
+        # the URL the flow asked for. An `ArgumentError` because the middleware is a configuration mistake,
+        # and deliberately outside `AuthorizationError`, which discovery treats as "nothing published"
+        # and `MCP::Client::HTTP` treats on a failed refresh as a reason to run the interactive flow.
+        class DestinationMismatchError < ArgumentError; end
+
+        # Faraday middleware registered on the connection `build_http_client` assembles before the customizer
+        # is invoked, so with the usual `use` it sits ahead of the customizer's middleware and sees the URL exactly
+        # as the flow requested it, which it records on the request environment for `RequestedOriginGuard`.
+        # The guard covers what happens to a request after that record; middleware inserted ahead of it with
+        # `builder.insert(0, ...)` that rewrites the URL before it or rebuilds the environment is outside the guard.
+        # The record lives on the environment, not in `env.request.context`: that slot belongs to the application,
+        # which may fill it on the connection or replace it from a middleware of its own. Only the first URL seen
+        # on an environment is recorded: a middleware inserted ahead of this one that re-enters the stack after
+        # a `3xx` with the same environment, or with its `dup`, which shares the record, cannot replace it with
+        # the redirected URL.
+        class RequestedURLStamp
+          KEY = :mcp_oauth_requested_url
+
+          def initialize(app)
+            @app = app
+          end
+
+          def call(env)
+            env[KEY] ||= env.url.to_s
+            @app.call(env)
+          end
+        end
+
+        # Faraday middleware registered last on that connection, so it sees `env.url` after any customizer-added
+        # middleware has rewritten it or followed a redirect. A request that would leave the origin the flow asked
+        # for is refused before it reaches the adapter, since every destination check ran against the URL as
+        # written; a same-origin change stays with the server those checks admitted. The record survives
+        # the `env.dup` that redirect-following middleware performs, and a request that arrives without it is
+        # refused as well, so a middleware that rebuilds the environment fails closed rather than open.
+        # The origin boundary resembles the one the Python SDK keeps for its own auth requests, which follows
+        # a redirect itself only within the origin; this flow follows none.
+        class RequestedOriginGuard
+          def initialize(app)
+            @app = app
+          end
+
+          def call(env)
+            requested = env[RequestedURLStamp::KEY]
+            unless requested
+              raise DestinationMismatchError, <<~MESSAGE
+                Request to #{Discovery.canonicalize_origin_and_path(env.url.to_s).inspect} carries no record of \
+                the URL the flow asked for; middleware that rebuilds the request environment is refused.
+              MESSAGE
+            end
+
+            unless Discovery.same_origin?(env.url.to_s, requested)
+              raise DestinationMismatchError, <<~MESSAGE
+                Request to #{Discovery.canonicalize_origin_and_path(requested).inspect} would be sent to \
+                #{Discovery.canonicalize_origin_and_path(env.url.to_s).inspect}, on a different origin; \
+                middleware that follows redirects or rewrites URLs is refused.
+              MESSAGE
+            end
+
+            @app.call(env)
+          end
+        end
+        private_constant :RequestedURLStamp, :RequestedOriginGuard
+
+        class << self
+          # Returns why `params` cannot ride a token request as `token_request_params`, or `nil` when it can.
+          # Shared by the provider constructors and the flow, which both refuse the value with `InvalidTokenRequestParamsError`,
+          # so the same problem reads the same wherever it surfaces.
+          def token_request_params_problem(params)
+            return "must be a Hash (got #{params.class})." unless params.is_a?(Hash)
+
+            # Two equal keys are two entries here, which would be sent twice from a provider method
+            # or silently collapse into one when the constructors copy the Hash.
+            return "must not compare keys by identity." if params.compare_by_identity?
+
+            params.each do |key, value|
+              return "keys must be Strings (got #{key.class})." unless key.is_a?(String)
+              return "values must be Strings (got #{value.class} for #{key.inspect})." unless value.is_a?(String)
+              return "must not set #{key.inspect}, which the SDK sets itself." if RESERVED_TOKEN_REQUEST_PARAMS.include?(key)
+            end
+
+            nil
+          end
+
+          # Builds the connection the flow uses for its own requests: the SDK's defaults, `RequestedURLStamp`,
+          # then `customizer` (a provider's `http_client_customizer`, called with the `Faraday::Connection`),
+          # then `RequestedOriginGuard` last so it sees what the customizer's middleware does to each request
+          # after the stamp recorded it. Every request on the connection passes through both, so a caller using
+          # it directly is held to the same origin rule.
+          #
+          # Deliberately built without redirect-following middleware. Every destination check in this class runs
+          # against the URL as written, before the request goes out, so a connection that transparently followed
+          # a `3xx` would let a server reach a host the checks just refused. The guard turns following at
+          # the middleware level into a refusal; following inside an adapter stays invisible, so a customizer must
+          # not enable it.
+          #
+          # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
+          # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
+          # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
+          # after the check.
+          def build_http_client(customizer = nil)
+            require "faraday"
+
+            Faraday.new do |faraday|
+              faraday.headers["Accept"] = "application/json"
+              faraday.use(RequestedURLStamp)
+              customizer&.call(faraday)
+              faraday.use(RequestedOriginGuard)
+            end
+          end
+        end
+
         def initialize(provider:, http_client_factory: nil)
           @provider = provider
           @http_client_factory = http_client_factory || -> { default_http_client }
@@ -75,7 +236,7 @@ module MCP
 
           ensure_pkce_supported!(as_metadata)
 
-          effective_scope = resolve_scope(scope: scope, prm: prm || {})
+          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
@@ -126,7 +287,7 @@ module MCP
         # Runs the OAuth 2.1 `client_credentials` grant (machine-to-machine, no user interaction) and persists
         # the resulting token. Shares the same discovery and security checks as `run!`; the only difference is
         # the grant exchanged at the token endpoint. There is no PKCE, redirect, or authorization request,
-        # and no `offline_access` augmentation because the grant does not issue a refresh token (OAuth 2.1 Section 4.3.3).
+        # and no `offline_access` augmentation because the grant is not expected to 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:, server_url:)
@@ -219,19 +380,22 @@ module MCP
         # checks before talking to it.
         #
         # Returns `:refreshed` on success. Raises `AuthorizationError` when the provider has no refresh token, no client information,
+        # when a `client_credentials` or `jwt-bearer` provider's tokens record no issuer,
         # or when the token endpoint refuses the refresh request.
         # https://www.rfc-editor.org/rfc/rfc6749#section-6
         def refresh!(server_url:, resource_metadata_url: nil)
           refresh_token = read_token("refresh_token")
           raise AuthorizationError, "Cannot refresh: no refresh_token in provider storage." unless refresh_token
 
+          ensure_refresh_token_issuer_recorded!
+
           stored_client_info = @provider.client_information
           have_stored_client_info = stored_client_info.is_a?(Hash) && client_info_required_value(stored_client_info, "client_id")
 
           # A CIMD-configured provider stores no `client_information` on purpose
           # (the CIMD URL is re-resolved against the live AS metadata on every flow).
           # Allow refresh to proceed in that case so the `refresh_token` obtained via the CIMD flow remains usable.
-          have_cimd_url = !@provider.client_id_metadata_document_url.nil?
+          have_cimd_url = !provider_client_id_metadata_document_url.nil?
 
           unless have_stored_client_info || have_cimd_url
             raise AuthorizationError, "Cannot refresh: no client_information in provider storage."
@@ -267,7 +431,7 @@ module MCP
             ensure_refreshable_client_information!(stored_client_info, as_metadata: as_metadata)
             stored_client_info
           elsif as_metadata["client_id_metadata_document_supported"] == true
-            { "client_id" => @provider.client_id_metadata_document_url }
+            { "client_id" => provider_client_id_metadata_document_url }
           else
             raise AuthorizationError,
               "Cannot refresh: provider has a CIMD URL but the authorization server no longer advertises " \
@@ -319,7 +483,12 @@ module MCP
         #
         # Legacy path (2025-03-26 backwards compatibility): when the server publishes no PRM, `prm` is nil
         # and the MCP server's own origin acts as the authorization base URL, matching the TypeScript and Python SDKs.
-        # Any PRM discovery failure (404s, network errors, malformed documents) selects the legacy path, mirroring both SDKs' behavior.
+        # Only a discovery answer saying that nothing usable is published (`MetadataNotPublishedError`: a `4xx` other than `429`,
+        # a redirect that was not followed, or a body that is not a JSON object) selects the legacy path.
+        # A request that failed to reach the server, or returned a `5xx` or `429`, says nothing about what the server publishes,
+        # so once no candidate has served a usable document it is surfaced instead (`MetadataUnreachableError`),
+        # as both SDKs do for network errors (the TypeScript SDK outside browsers) and the Python SDK does for server errors.
+        # A body over the response cap is refused outright and never reaches the fallback either.
         # https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization#fallbacks-for-servers-without-metadata-discovery
         def locate_authorization_server(server_url:, resource_metadata_url:)
           prm = begin
@@ -327,7 +496,7 @@ module MCP
               server_url: server_url,
               resource_metadata_url: resource_metadata_url,
             )
-          rescue AuthorizationError
+          rescue MetadataNotPublishedError
             nil
           end
 
@@ -349,16 +518,26 @@ module MCP
 
         # Fetches and validates the authorization server's RFC 8414 metadata.
         #
-        # On the modern path the metadata `issuer` must be byte-identical to the discovery URL (RFC 8414 Section 3.3).
-        # On the legacy 2025-03-26 path that validation is skipped: the legacy spec predates the requirement,
-        # and a pre-PRM server may host its OAuth endpoints under a path prefix whose `issuer` legitimately differs from
-        # the origin the metadata was discovered at (neither the TypeScript nor the Python SDK validates the issuer on this path).
+        # The metadata `issuer` must be byte-identical to the discovery URL (RFC 8414 Section 3.3) on both paths.
+        # On the legacy 2025-03-26 path the discovery URL is the MCP server's origin, which that spec names as
+        # the authorization base URL and which a document may render with a trailing slash; the TypeScript and Python SDKs
+        # accept the same slash-only difference. A document naming any other issuer is refused: an unverified `issuer`
+        # would otherwise become the identity tokens and client information are bound to, assertions are minted for,
+        # and the validator is shown, so a server could claim another authorization server and unlock the credentials
+        # bound to it.
         # When even the metadata document is absent, the legacy spec's default endpoints are used.
         def authorization_server_metadata(authorization_server:, legacy:, server_url:)
           metadata = if legacy
-            begin
+            fetched = begin
               fetch_authorization_server_metadata(issuer_url: authorization_server)
             rescue AuthorizationError
+              nil
+            end
+
+            if fetched
+              ensure_legacy_issuer_matches!(expected: authorization_server, returned: fetched["issuer"])
+              fetched
+            else
               default_legacy_metadata(authorization_server)
             end
           else
@@ -403,6 +582,14 @@ module MCP
           fetch_metadata_json(urls, label: "authorization server metadata")
         end
 
+        # The legacy authorization base is an origin, which a document may render as `https://host/`;
+        # both name the same server, and nothing else does.
+        def ensure_legacy_issuer_matches!(expected:, returned:)
+          return if returned == "#{expected}/"
+
+          ensure_issuer_matches!(expected: expected, returned: returned)
+        end
+
         # Reads `authorization_servers` from a PRM document and returns
         # the first entry, raising `AuthorizationError` for any of the malformed
         # shapes a non-compliant server could emit (missing field, non-Array
@@ -430,44 +617,63 @@ module MCP
           first
         end
 
-        # Walks candidate metadata URLs and returns the parsed JSON body of
-        # the first 2xx response. Raises `AuthorizationError` for transport
-        # failures (`Faraday::Error`) and malformed bodies (`JSON::ParserError`)
-        # so callers do not have to handle raw Faraday/JSON exceptions.
+        # Walks candidate metadata URLs and returns the parsed body of the first 2xx response that is a JSON object;
+        # the caller checks its fields. Candidates are tried until one serves such a body, since a later one may still
+        # be usable when an earlier one is broken or down (the URL from `WWW-Authenticate` against the well-known path,
+        # or the OAuth document against the OpenID one). Once the candidates are exhausted, an answer that said nothing
+        # about what is published (a network error, a `5xx`, or a `429`) outranks the rest and raises
+        # `MetadataUnreachableError`; otherwise (any other status, such as a `4xx` other than `429` or a redirect that
+        # was not followed, a body that is not JSON, or not a JSON object) `MetadataNotPublishedError`.
+        # A body over the cap is refused outright by `bounded_request` with a plain `AuthorizationError`,
+        # before any classification. Each failure is listed with its URL stripped of userinfo, query and fragment
+        # and cut to `METADATA_URL_MAX_LENGTH`, but otherwise spelled as requested, so it can be matched against
+        # a server's access log, and with exception text bounded, since the message lands in every log destination
+        # the error passes through.
         def fetch_metadata_json(urls, label:)
-          last_error = nil
+          failures = []
+          inconclusive = false
           urls.each do |url|
             response = begin
               http_get(url)
             rescue Faraday::Error => e
-              last_error = "GET #{url} raised #{e.class}: #{e.message}"
+              detail = bounded_diagnostic(e.message, limit: METADATA_DIAGNOSTIC_MAX_LENGTH)
+              failures << "GET #{reported_url(url)} raised #{[e.class, detail].compact.join(": ")}"
+              inconclusive = true
               next
             end
 
-            if response.status >= 200 && response.status < 300
-              parsed = begin
-                JSON.parse(response_body_string(response))
-              rescue JSON::ParserError => e
-                raise AuthorizationError, "Failed to parse #{label} from #{url}: #{e.message}."
-              end
+            unless response.status >= 200 && response.status < 300
+              failures << "GET #{reported_url(url)} returned #{response.status}"
+              inconclusive = true if response.status >= 500 || response.status == 429
+              next
+            end
 
-              # Even valid JSON can be the wrong shape (a top-level array,
-              # a bare `null`, a string, ...). The discovery callers index by
-              # name (`prm["authorization_servers"]`, etc.), so anything that
-              # is not a Hash would raise `TypeError` / `NoMethodError`
-              # downstream. Surface that as `AuthorizationError` instead so
-              # callers see a single, documented error type.
-              unless parsed.is_a?(Hash)
-                raise AuthorizationError,
-                  "#{label} from #{url} is not a JSON object (got #{parsed.class})."
-              end
+            parsed = begin
+              JSON.parse(response_body_string(response))
+            rescue JSON::ParserError => e
+              detail = bounded_diagnostic(e.message, limit: METADATA_DIAGNOSTIC_MAX_LENGTH) || e.class.name
+              failures << "GET #{reported_url(url)} returned a body that is not JSON: #{detail}"
+              next
+            end
 
-              return parsed
+            # Even valid JSON can be the wrong shape (a top-level array, a bare `null`, a string, ...).
+            # The discovery callers index by name (`prm["authorization_servers"]`, etc.), so anything that
+            # is not a Hash would raise `TypeError` / `NoMethodError` downstream.
+            unless parsed.is_a?(Hash)
+              failures << "GET #{reported_url(url)} returned a body that is not a JSON object (got #{parsed.class})"
+              next
             end
 
-            last_error = "GET #{url} returned #{response.status}"
+            return parsed
+          end
+
+          message = "Failed to fetch #{label}: #{failures.join("; ")}."
+
+          if inconclusive
+            raise MetadataUnreachableError, message
+          else
+            raise MetadataNotPublishedError, message
           end
-          raise AuthorizationError, "Failed to fetch #{label}: #{last_error}."
         end
 
         def ensure_pkce_supported!(as_metadata)
@@ -628,7 +834,7 @@ module MCP
           # (or the operator may rotate the CIMD URL), and a stale `client_information` entry would otherwise
           # keep sending the old CIMD URL forever. Re-evaluating on every flow re-reads the current AS metadata
           # and the current `provider.client_id_metadata_document_url`.
-          cimd_url = @provider.client_id_metadata_document_url
+          cimd_url = provider_client_id_metadata_document_url
           if cimd_url && as_metadata["client_id_metadata_document_supported"] == true
             return { "client_id" => cimd_url }
           end
@@ -758,6 +964,18 @@ module MCP
           MESSAGE
         end
 
+        # `Provider` tolerates tokens stored before the issuer was recorded (see `ensure_token_issuer!`).
+        # The `client_credentials` and `jwt-bearer` providers have no such tokens, since their refresh is new,
+        # and a refresh asks no validator, so a token without an `issuer` would be presented to whatever
+        # authorization server discovery names now. Refusing it sends the transport back through the grant,
+        # which does ask.
+        def ensure_refresh_token_issuer_recorded!
+          return if provider_authorization_flow == :authorization_code
+          return unless read_token("issuer").nil?
+
+          raise AuthorizationError, "Cannot refresh: the stored tokens record no issuer; re-authorization is required."
+        end
+
         def ensure_refreshable_client_information!(client_info, as_metadata:)
           stored_issuer = client_info_required_value(client_info, "issuer")
           return if stored_issuer.nil?
@@ -886,7 +1104,8 @@ module MCP
         def resolve_scope(scope:, prm:)
           return scope if scope && !scope.empty?
 
-          supported = prm["scopes_supported"]
+          # `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?
 
           return @provider.scope if @provider.scope && !@provider.scope.empty?
@@ -948,6 +1167,31 @@ module MCP
           @provider.authorization_flow
         end
 
+        # Parameters the provider adds to every token request it makes (RFC 6749 Section 8.2 leaves room for them;
+        # Auth0's `audience` is the usual one). Duck-typed like `authorization_flow`, so a provider without the method,
+        # or one returning `nil`, adds nothing.
+        # A bad value raises `InvalidTokenRequestParamsError`, as the provider constructors do.
+        def provider_token_request_params
+          return {} unless @provider.respond_to?(:token_request_params)
+
+          params = @provider.token_request_params
+          return {} if params.nil?
+
+          problem = self.class.token_request_params_problem(params)
+          raise InvalidTokenRequestParamsError, "The provider's token_request_params #{problem}" if problem
+
+          params
+        end
+
+        # The Client ID Metadata Document URL, when the provider has one. Only `Provider` exposes the reader
+        # (CIMD replaces Dynamic Client Registration on the authorization-code flow), while `refresh!` serves
+        # every provider that holds a `refresh_token`, so the read is duck-typed like `authorization_flow`.
+        def provider_client_id_metadata_document_url
+          return unless @provider.respond_to?(:client_id_metadata_document_url)
+
+          @provider.client_id_metadata_document_url
+        end
+
         def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint
@@ -997,9 +1241,12 @@ module MCP
           post_to_token_endpoint(as_metadata: as_metadata, client_info: client_info, form: form)
         end
 
-        # Submits a form-encoded request to the token endpoint, applying
-        # the client authentication method advertised in `client_information` and
-        # adding `client_id` (and `client_secret` when not using HTTP Basic).
+        # Submits a form-encoded token request using the authentication method
+        # stored in `client_information`. The method determines whether client
+        # credentials belong in the form body, a Basic header, or a JWT assertion.
+        # A provider's `token_request_params` go underneath the flow's own parameters,
+        # which therefore win, and are refused before the request is sent when they name
+        # a reserved parameter or are not a Hash of Strings.
         def post_to_token_endpoint(as_metadata:, client_info:, form:)
           client_id = client_info_required_value(client_info, "client_id")
           unless client_id
@@ -1009,13 +1256,15 @@ module MCP
 
           client_secret = client_info_required_value(client_info, "client_secret")
           token_endpoint_auth_method = client_info_value(client_info, "token_endpoint_auth_method")
+          form = provider_token_request_params.merge(form)
 
-          form = if token_endpoint_auth_method == "private_key_jwt"
-            # RFC 7523 Section 2.2 JWT client assertion for the `private_key_jwt` method of
-            # the `io.modelcontextprotocol/oauth-client-credentials` extension (SEP-1046).
-            # The client identity travels in the assertion's `iss`/`sub` claims, so `client_id` is
-            # omitted from the body per RFC 7521 Section 4.2 (the `client_assertion` conveys the client identity).
-            # The audience is the issuer identifier that `ensure_issuer_matches!` already byte-validated.
+          # Apply one client authentication method per request (RFC 6749 Section 2.3).
+          headers = {}
+          form = case token_endpoint_auth_method
+          when "private_key_jwt"
+            # The assertion identifies the client through its `iss` and `sub`
+            # claims, so the body needs no separate `client_id` (RFC 7521 Section 4.2).
+            # Use the issuer already checked by `ensure_issuer_matches!` as the audience.
             unless @provider.respond_to?(:client_assertion)
               raise AuthorizationError,
                 "token_endpoint_auth_method is private_key_jwt but the provider does not " \
@@ -1026,22 +1275,24 @@ module MCP
               "client_assertion_type" => JWTClientAssertion::ASSERTION_TYPE,
               "client_assertion" => @provider.client_assertion(audience: as_metadata["issuer"]),
             )
+          when "client_secret_post"
+            # Send the client ID and available secret in the form body.
+            body = form.merge("client_id" => client_id)
+            body["client_secret"] = client_secret if client_secret
+            body
           else
-            form.merge("client_id" => client_id)
-          end
-
-          headers = {}
-          if client_secret
-            case token_endpoint_auth_method
-            when "client_secret_post"
-              form["client_secret"] = client_secret
-            when "none"
-              # Public client; no credential.
-            else
-              # RFC 6749 §2.3.1 recommends Basic for confidential clients and
-              # both Python and TypeScript SDKs default here when
-              # the authentication method is not explicitly stored.
+            if client_secret && token_endpoint_auth_method != "none"
+              # Basic is also the fallback when a secret is present but no method
+              # is stored. A body `client_id` is optional (RFC 6749 Section 3.2.1);
+              # omit it because some servers treat it alongside Basic as a second
+              # authentication method and reject the request with `invalid_request`.
               headers["Authorization"] = "Basic " + basic_auth_credentials(client_id, client_secret)
+              form
+            else
+              # With `none` or no secret, identify the client using `client_id`.
+              # This is required for unauthenticated authorization-code exchanges
+              # (RFC 6749 Section 3.2.1).
+              form.merge("client_id" => client_id)
             end
           end
 
@@ -1059,11 +1310,7 @@ module MCP
           end
 
           if response.status < 200 || response.status >= 300
-            if token_endpoint_error_code(response) == "invalid_grant"
-              raise InvalidGrantError, "Token endpoint rejected the grant: invalid_grant."
-            end
-
-            raise AuthorizationError, "Token endpoint returned status #{response.status}."
+            raise token_endpoint_error(response)
           end
 
           parsed = begin
@@ -1084,17 +1331,41 @@ module MCP
           parsed
         end
 
-        # Extracts the `error` code from an RFC 6749 §5.2 error response body
-        # when one is parseable. Returns nil on any parse failure or when
-        # the body is not JSON.
-        def token_endpoint_error_code(response)
-          body = response_body_string(response).to_s
-          return if body.empty?
+        # Surface only RFC 6749 §5.2 diagnostic fields, never the raw response,
+        # which may contain tokens or other credentials. Classify the original
+        # code so sanitization cannot turn malformed input into invalid_grant.
+        def token_endpoint_error(response)
+          message = "Token endpoint returned status #{response.status}."
+          error_class = AuthorizationError
+          parsed = JSON.parse(response_body_string(response))
+          parsed = {} unless parsed.is_a?(Hash)
+
+          error_class = parsed["error"] == "invalid_grant" ? InvalidGrantError : AuthorizationError
+          error = bounded_diagnostic(parsed["error"], limit: TOKEN_ENDPOINT_ERROR_MAX_LENGTH)
+          description = bounded_diagnostic(parsed["error_description"], limit: TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH)
+          message += " #{[error, description].compact.join(": ")}" if error || description
+
+          error_class.new(message, http_status: response.status, error: error, error_description: description)
+        rescue StandardError
+          # Diagnostics must not mask the endpoint failure or change refresh recovery.
+          error_class.new("Token endpoint returned status #{response.status}.", http_status: response.status)
+        end
+
+        def bounded_diagnostic(value, limit:)
+          return unless value.is_a?(String)
 
-          parsed = JSON.parse(body)
-          parsed["error"] if parsed.is_a?(Hash)
-        rescue JSON::ParserError
-          nil
+          # RFC 6749 permits printable ASCII except double quotes and backslashes in token endpoint error fields.
+          # Replace other characters to keep text received off the network on one log line.
+          value = value.scrub(" ").gsub(/[^\x20-\x21\x23-\x5B\x5D-\x7E]/, " ").strip
+          return if value.empty?
+
+          value.length > limit ? "#{value[0, limit - 3]}..." : value
+        end
+
+        # A candidate URL as it goes into a failure string: redacted, and cut so a URL the server chose cannot
+        # grow the message without limit.
+        def reported_url(url)
+          bounded_diagnostic(Discovery.redact_url(url), limit: METADATA_URL_MAX_LENGTH)
         end
 
         # Per RFC 6749 Section 2.3.1, the `client_id` and `client_secret` MUST be
@@ -1162,22 +1433,18 @@ module MCP
           @http_client ||= @http_client_factory.call
         end
 
-        # Deliberately built without redirect-following middleware. Every destination check in
-        # this class runs against the URL as written, before the request goes out, so a connection
-        # that transparently followed a `3xx` would let a server reach a host the checks just refused.
-        # A caller passing `http_client_factory:` takes on that responsibility: add redirect following here
-        # and the guards above only cover the first hop.
-        #
-        # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
-        # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
-        # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
-        # after the check.
+        # A connection supplied through `http_client_factory:` replaces this one, the provider's customizer and
+        # `RequestedOriginGuard` included, so that caller takes on the redirect responsibility described on
+        # `build_http_client`; `bounded_request` caps its responses all the same.
         def default_http_client
-          require "faraday"
+          self.class.build_http_client(provider_http_client_customizer)
+        end
 
-          Faraday.new do |faraday|
-            faraday.headers["Accept"] = "application/json"
-          end
+        # `nil` for a provider that predates the hook or leaves it unset.
+        def provider_http_client_customizer
+          return unless @provider.respond_to?(:http_client_customizer)
+
+          @provider.http_client_customizer
         end
 
         def response_body_string(response)

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

@@ -95,7 +95,7 @@ module MCP
             assertion
           end
 
-          # `Accept-Encoding` is deliberately left unset, for the same reason as `Flow#default_http_client`:
+          # `Accept-Encoding` is deliberately left unset, for the same reason as `Flow.build_http_client`:
           # claiming that header turns Net::HTTP's `decode_content` off and would move `BoundedBody`'s cap
           # onto compressed bytes.
           def default_http_client

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

@@ -48,6 +48,13 @@ module MCP
       #   The document served at the URL is a separate JSON artifact from the `client_metadata` keyword:
       #   DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include `client_id` set
       #   to the URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
+      # - `token_request_params` - Hash of String keys and values added to every token request this provider makes
+      #   (the authorization code exchange and refresh), for parameters the authorization server requires beyond
+      #   the grant itself. The authorization request is not affected. A key in `Flow::RESERVED_TOKEN_REQUEST_PARAMS`
+      #   raises `Flow::InvalidTokenRequestParamsError`.
+      #   The Hash is copied and frozen. See `StorageBackedProvider#token_request_params`.
+      # - `http_client_customizer` - Callable invoked with the `Faraday::Connection` the flow builds for
+      #   its own requests; see `StorageBackedProvider#http_client_customizer`.
       class Provider
         include StorageBackedProvider
 
@@ -87,7 +94,9 @@ module MCP
           scope: nil,
           storage: nil,
           client_id_metadata_document_url: nil,
-          authorization_request_validator: nil
+          authorization_request_validator: nil,
+          token_request_params: nil,
+          http_client_customizer: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -109,6 +118,8 @@ module MCP
                 "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
           end
 
+          http_client_customizer = validated_http_client_customizer(http_client_customizer)
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
@@ -117,6 +128,8 @@ module MCP
           @storage = storage || InMemoryStorage.new
           @client_id_metadata_document_url = client_id_metadata_document_url
           @authorization_request_validator = authorization_request_validator
+          @token_request_params = frozen_token_request_params(token_request_params)
+          @http_client_customizer = http_client_customizer
         end
 
         # Identifies the OAuth flow this provider drives.

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

@@ -4,11 +4,11 @@ module MCP
   class Client
     module OAuth
       # Shared token/credential persistence for the OAuth provider classes
-      # (`Provider` for the authorization-code flow and `ClientCredentialsProvider`
-      # for the client_credentials flow). The two grants differ in how they authenticate,
-      # but both read and write the same two pieces of state through a `storage` object:
-      # the token response and the client information. This module supplies that delegation
-      # so the `Flow` orchestrator can treat any provider uniformly.
+      # (`Provider` for the authorization-code flow, `ClientCredentialsProvider`
+      # for the client_credentials flow, and `CrossAppAccessProvider` for the jwt-bearer flow).
+      # The grants differ in how they authenticate, but all read and write the same two pieces of state
+      # through a `storage` object: the token response and the client information. This module supplies
+      # that delegation so the `Flow` orchestrator can treat any provider uniformly.
       #
       # Including classes must set `@storage` to an object responding to `tokens`,
       # `save_tokens(tokens)`, `client_information`, and `save_client_information(info)`
@@ -21,6 +21,20 @@ module MCP
         # MCP SDK has today.
         attr_reader :authorization_request_validator
 
+        # Optional Hash of String keys and values added to every token request the provider makes, for parameters
+        # the authorization server requires beyond the grant itself (RFC 6749 Section 8.2 leaves room for them;
+        # Auth0's `audience` is the usual one). `nil` (the default) adds nothing.
+        # Set through `frozen_token_request_params`, which refuses a key `Flow` sets itself or a wrongly shaped value
+        # with `Flow::InvalidTokenRequestParamsError`.
+        attr_reader :token_request_params
+
+        # Optional callable invoked with the `Faraday::Connection` the flow builds for its own requests,
+        # after the SDK's defaults and before its origin guard (see `Flow.build_http_client`), so an application can
+        # add middleware to discovery, registration, and token requests or swap their adapter. `nil` (the default)
+        # keeps the default connection. The transport's own connection and customizer block never serve these requests:
+        # they are bound to the MCP server URL and carry headers meant for that server.
+        attr_reader :http_client_customizer
+
         def access_token
           tokens&.dig("access_token") || tokens&.dig(:access_token)
         end
@@ -44,6 +58,29 @@ module MCP
         def clear_tokens!
           @storage.save_tokens(nil)
         end
+
+        private
+
+        # Constructors call this before writing to `storage`, so a rejected provider leaves it untouched.
+        # The copy has its own frozen keys and values, so a later change to the caller's Hash, to a key,
+        # or to a value cannot alter what is sent to the token endpoint. Keys are copied explicitly
+        # because `Hash` copies and freezes only keys whose class is exactly `String`.
+        def frozen_token_request_params(params)
+          return if params.nil?
+
+          problem = Flow.token_request_params_problem(params)
+          raise Flow::InvalidTokenRequestParamsError, "token_request_params #{problem}" if problem
+
+          params.each_with_object({}) { |(key, value), copy| copy[key.dup.freeze] = value.dup.freeze }.freeze
+        end
+
+        # Returns `customizer` when it is `nil` or callable and raises otherwise, so a connection object passed
+        # in place of a callable fails at construction rather than at the first `401`.
+        def validated_http_client_customizer(customizer)
+          return customizer if customizer.nil? || customizer.respond_to?(:call)
+
+          raise ArgumentError, "http_client_customizer must respond to call (got #{customizer.class})."
+        end
       end
     end
   end

data/lib/mcp/icon.rb

@@ -1,13 +1,35 @@
 # frozen_string_literal: true
 
 module MCP
+  # An icon attached to a server, tool, prompt, or resource, per the specification's `Icon` type:
+  # https://modelcontextprotocol.io/specification/2026-07-28/basic#icons
+  #
+  # Each argument is checked against the schema's type, as the TypeScript and Python SDKs check theirs,
+  # so an icon that would serialize into something a client rejects fails here instead. What a value means
+  # is not judged: `src` may be any non-empty `String` (the schema types it as a URI, which an empty `String`
+  # is not, and the specification allows an HTTP/HTTPS URL or a `data:` URI), and a size may be any `String`
+  # (the specification expects `WxH` or `"any"`).
   class Icon
     SUPPORTED_THEMES = ["light", "dark"].freeze
 
     attr_reader :mime_type, :sizes, :src, :theme
 
-    def initialize(mime_type: nil, sizes: nil, src: nil, theme: nil)
-      raise ArgumentError, 'The value of theme must specify "light" or "dark".' if theme && !SUPPORTED_THEMES.include?(theme)
+    def initialize(mime_type: nil, sizes: nil, src:, theme: nil)
+      unless src.is_a?(String) && !src.empty?
+        raise ArgumentError, "The value of src must be a non-empty String (got #{src.class})."
+      end
+
+      unless mime_type.nil? || mime_type.is_a?(String)
+        raise ArgumentError, "The value of mime_type must be a String (got #{mime_type.class})."
+      end
+
+      if (problem = sizes_problem(sizes))
+        raise ArgumentError, "The value of sizes must be an Array of Strings such as [\"48x48\"] or [\"any\"] (#{problem})."
+      end
+
+      unless theme.nil? || SUPPORTED_THEMES.include?(theme)
+        raise ArgumentError, 'The value of theme must specify "light" or "dark".'
+      end
 
       @mime_type = mime_type
       @sizes = sizes
@@ -18,5 +40,16 @@ module MCP
     def to_h
       { mimeType: mime_type, sizes: sizes, src: src, theme: theme }.compact
     end
+
+    private
+
+    def sizes_problem(sizes)
+      return if sizes.nil?
+      return "got #{sizes.class}" unless sizes.is_a?(Array)
+
+      index = sizes.index { |size| !size.is_a?(String) }
+
+      "got #{sizes[index].class} inside the Array" if index
+    end
   end
 end

data/lib/mcp/tool.rb

@@ -149,7 +149,7 @@ module MCP
           raise ArgumentError, "Tool names should be between 1 and 128 characters in length (inclusive)."
         end
 
-        unless tool_name.match?(/\A[A-Za-z\d_\-\.]+\z/)
+        unless tool_name.match?(/\A[A-Za-z\d_\-.]+\z/)
           raise ArgumentError, <<~MESSAGE
             Tool names only allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.).
           MESSAGE

data/lib/mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcp
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.6.0
 platform: ruby
 authors:
 - Model Context Protocol
@@ -108,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.5.1
+  changelog_uri: https://github.com/modelcontextprotocol/ruby-sdk/releases/tag/v1.6.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
@@ -127,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: The official Ruby SDK for Model Context Protocol servers and clients
 test_files: []