mcp 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7268234a54e4c0b422a916aabc08de04a4cde157b9a6b3909274ab4629885137
-  data.tar.gz: 1f48ca777ef0269c8c1f946a23efed1cd990e9ac1898568d8143d84e6c8d7fcb
+  metadata.gz: f1915f5e50dda558f3ba32d0c946dacafda7c0ee183300cd634632505ab206bd
+  data.tar.gz: 9f702e675c56e191effefa6a7a7ac5b4d5f3c0c8bded9284484bf7260b551f3b
 SHA512:
-  metadata.gz: bb859fc7e68f54f1a1d7c3d523a3487799c7b5ff8e3ddb5c01cd84101be79c9b5f81eeeb65b8fb06d620b87898f6c3466492e57ad921eac729c113cd5a609f8d
-  data.tar.gz: 0bf7b67aa29e8211c97168a9e9472e5fdfb1ea5a97db16d917ab1602f584db6076854e354abe0456384c70e712a797832c0949f12d5a5e76bea6761fcecab0c1
+  metadata.gz: 76797292c1345c02d77b63b5d840bf9a39fe719e2df6a232a32a342d9e6974e296bc4e1a08939bba539ea56f9a00ab25cf225936ecd02cd1cee31fdfd7e39d48
+  data.tar.gz: f1063ce3c1781e713f556489b0a70d58d102b42d6f220b63a138b97a0532dbfd521b7aea428ed2811d94923bff39ab6f02cad0504ad0597c53e48676cb27984f

data/README.md

@@ -47,6 +47,7 @@ It implements the Model Context Protocol specification, handling model context r
 
 - `initialize` - Initializes the protocol and returns server capabilities
 - `ping` - Simple health check
+- `logging/setLevel` - Configures the minimum log level for the server
 - `tools/list` - Lists all registered tools and their schemas
 - `tools/call` - Invokes a specific tool with provided arguments
 - `prompts/list` - Lists all registered prompts and their schemas
@@ -260,6 +261,11 @@ See the relevant sections below for the arguments they receive.
 
 The MCP protocol supports a special [`_meta` parameter](https://modelcontextprotocol.io/specification/2025-06-18/basic#general-fields) in requests that allows clients to pass request-specific metadata. The server automatically extracts this parameter and makes it available to tools and prompts as a nested field within the `server_context`.
 
+> [!NOTE]
+> `_meta` is only merged when `server_context` is a `Hash` (or `nil`, in which case a new `{ _meta: ... }` hash is synthesized).
+> If you assign a non-`Hash` value to `server_context`, `_meta` is not merged and tools will not see it
+> under `server_context[:_meta]`. Keep `server_context` as a `Hash` if your tools need access to `_meta`.
+
 **Access Pattern:**
 
 When a client includes `_meta` in the request params, it becomes available as `server_context[:_meta]`:
@@ -300,6 +306,36 @@ end
 }
 ```
 
+**Distributed Tracing (W3C Trace Context):**
+
+Per SEP-414, the keys `traceparent`, `tracestate`, and `baggage` are reserved un-prefixed `_meta` keys for propagating
+[W3C Trace Context](https://www.w3.org/TR/trace-context/) across MCP requests. The SDK guarantees these keys pass through
+incoming request `_meta` untouched, and exposes their names as constants on `MCP::TraceContext` (`TRACEPARENT_META_KEY`,
+`TRACESTATE_META_KEY`, `BAGGAGE_META_KEY`, and `META_KEYS`). The SDK does not depend on OpenTelemetry; bridge the values
+to your tracing system yourself:
+
+```ruby
+class TracedTool < MCP::Tool
+  def self.call(message:, server_context:)
+    traceparent = server_context.dig(:_meta, :traceparent)
+    # Hand traceparent/tracestate/baggage to your tracing library
+    # (e.g. the opentelemetry-ruby gems) to continue the caller's trace.
+
+    MCP::Tool::Response.new([{ type: "text", text: "ok" }])
+  end
+end
+```
+
+On the client side, every request method (`call_tool`, `read_resource`, `get_prompt`, `complete`, `ping`, and the `list_*` methods)
+accepts a `meta:` keyword to inject these keys into the outgoing request, so trace context can flow on every request:
+
+```ruby
+meta = { MCP::TraceContext::TRACEPARENT_META_KEY => "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" }
+
+client.call_tool(tool: tool, arguments: { message: "Hello" }, meta: meta)
+client.read_resource(uri: "file:///report.txt", meta: meta)
+```
+
 #### Configuration Block Data
 
 ##### Exception Reporter
@@ -423,10 +459,10 @@ The exception reporter receives two arguments:
 - `exception`: The Ruby exception object that was raised
 - `server_context`: A hash containing contextual information about where the error occurred
 
-The server_context hash includes:
+The `server_context` hash includes:
 
-- For tool calls: `{ tool_name: "name", arguments: { ... } }`
-- For general request handling: `{ request: { ... } }`
+- For request handling failures: `{ request: { ... } }` (the raw JSON-RPC request hash)
+- For notification delivery failures: `{ notification: "tools_list_changed" }` (or the relevant notification name)
 
 When an exception occurs:
 
@@ -891,6 +927,19 @@ end
 
 otherwise `resources/read` requests will be a no-op.
 
+For unknown URIs, raise `MCP::Server::ResourceNotFoundError` from the handler.
+Per SEP-2164, the server then responds with the standard JSON-RPC Invalid Params error (`-32602`)
+carrying the requested URI in the error `data` member:
+
+```ruby
+server.resources_read_handler do |params|
+  resource = lookup(params[:uri])
+  raise MCP::Server::ResourceNotFoundError.new(params[:uri], params) unless resource
+
+  [{ uri: params[:uri], mimeType: resource.mime_type, text: resource.body }]
+end
+```
+
 ### Resource Templates
 
 The `MCP::ResourceTemplate` class provides a way to register resource templates with the server.
@@ -1913,6 +1962,12 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - On a `401 Unauthorized`, parse the `WWW-Authenticate` header, discover the authorization server (Protected Resource Metadata + RFC 8414 Authorization Server Metadata),
   perform Dynamic Client Registration if needed, run the OAuth 2.1 Authorization Code flow with PKCE (S256), and retry the failed request with the acquired token.
 - On subsequent 401s with a saved `refresh_token`, exchange it at the token endpoint before falling back to the full interactive flow (RFC 6749 Section 6).
+- On a `403 Forbidden` whose `WWW-Authenticate` header carries `error="insufficient_scope"` (OAuth 2.0 step-up, RFC 6750 Section 3.1 and the MCP scope-selection-strategy),
+  run a fresh authorization request for the union of the currently granted scope and the scope named in the challenge, then retry the failed request once.
+  The refresh path is bypassed because refreshing would re-issue the same scope set the server just rejected. A `403` without that challenge is surfaced unchanged.
+- Request the `offline_access` scope when `client_metadata[:grant_types]` includes `refresh_token` and the authorization server advertises `offline_access` in its metadata
+  `scopes_supported` (SEP-2207). This is what lets the server issue the `refresh_token` used above. As an SDK-level safeguard, when the authorization server does not advertise
+  `offline_access` the scope is also stripped from any other source (challenge, PRM, or provider-supplied scope) so a server that does not support it never receives it.
 
 ```ruby
 require "mcp"
@@ -1958,6 +2013,17 @@ Optional keyword arguments:
 - `scope`: Space-separated scopes to request when the server's `WWW-Authenticate` does not specify one.
 - `storage`: Object responding to `tokens`, `save_tokens(t)`, `client_information`, `save_client_information(info)`. Defaults to `MCP::Client::OAuth::InMemoryStorage`,
   which keeps credentials in process memory only.
+- `client_id_metadata_document_url`: URL where you publish a Client ID Metadata Document
+  (`draft-ietf-oauth-client-id-metadata-document` and the MCP authorization specification).
+  When the authorization server advertises `client_id_metadata_document_supported: true`,
+  the SDK uses this URL as the OAuth `client_id` and skips Dynamic Client Registration.
+  Spec-required: the URL MUST be `https://` with a non-root path and MUST NOT include a fragment,
+  userinfo, or `.`/`..` segments. The SDK additionally rejects query strings (the draft only marks
+  them SHOULD NOT include, but the SDK refuses to send any) for `client_id` stability.
+  Any of these failures raise `Provider::InvalidClientIDMetadataDocumentURLError`. The CIMD document
+  served at the URL is a separate JSON artifact from the `client_metadata` keyword above:
+  the DCR `client_metadata` MUST NOT include `client_id`, while the CIMD document MUST include
+  `client_id` set to the document URL, `client_name`, and `redirect_uris` covering `redirect_uri`.
 
 To persist credentials across restarts, supply your own storage:
 
@@ -2000,6 +2066,29 @@ provider = MCP::Client::OAuth::Provider.new(
 )
 ```
 
+##### Client Credentials Grant
+
+For a confidential machine-to-machine client (no user, no browser redirect), use `MCP::Client::OAuth::ClientCredentialsProvider` instead of `Provider`.
+The transport discovers the authorization server the same way, then exchanges the OAuth 2.1 `client_credentials` grant (RFC 6749 Section 4.4) at
+the token endpoint. There is no authorization request, PKCE, or `offline_access`, because the grant does not issue a refresh token.
+
+```ruby
+provider = MCP::Client::OAuth::ClientCredentialsProvider.new(
+  client_id: "my-service",
+  client_secret: ENV.fetch("MCP_CLIENT_SECRET"),
+  # token_endpoint_auth_method: "client_secret_basic" (default) or "client_secret_post"
+  # scope: "mcp:read mcp:write" (optional; used when the server does not advertise scopes)
+)
+
+transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp", oauth: provider)
+```
+
+Keyword arguments:
+
+- `client_id`, `client_secret`: Required. The grant is for confidential clients, so a credential is mandatory.
+- `token_endpoint_auth_method`: `"client_secret_basic"` (default) or `"client_secret_post"`. `"none"` is rejected with `ClientCredentialsProvider::InvalidCredentialsError`.
+- `scope`, `storage`: Optional, same meaning as on `Provider`.
+
 ##### Communication Security
 
 When `oauth:` is set, the MCP transport URL and every OAuth-facing URL (PRM, Authorization Server metadata, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`,

data/lib/json_rpc_handler.rb

@@ -73,13 +73,18 @@ module JsonRpcHandler
 
     error = if !valid_version?(request[:jsonrpc])
       "JSON-RPC version must be 2.0"
-    elsif !valid_id?(request[:id], id_validation_pattern)
+    elsif !valid_id?(id, id_validation_pattern)
       "Request ID must match validation pattern, or be an integer or null"
     elsif !valid_method_name?(request[:method])
       'Method name must be a string and not start with "rpc."'
     end
 
-    return error_response(id: :unknown_id, id_validation_pattern: id_validation_pattern, error: {
+    # 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.
+    return error_response(id: id.nil? ? :unknown_id : id, id_validation_pattern: id_validation_pattern, error: {
       code: ErrorCode::INVALID_REQUEST,
       message: "Invalid Request",
       data: error,

data/lib/mcp/client/http.rb

@@ -185,6 +185,7 @@ module MCP
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
         oauth_retried = false
+        step_up_retried = false
 
         begin
           response = client.post("", request, session_headers)
@@ -217,6 +218,19 @@ module MCP
             original_error: e,
           )
         rescue Faraday::ForbiddenError => e
+          # OAuth 2.0 step-up: a 403 carrying `error="insufficient_scope"` in
+          # the Bearer challenge means the existing access token is valid
+          # but lacks scopes the server now requires for this operation.
+          # Re-run the full authorization flow with the escalated scope from
+          # the challenge and retry once. A plain 403 without the challenge is
+          # surfaced unchanged.
+          if @oauth && !step_up_retried && insufficient_scope_challenge?(e)
+            step_up_retried = true
+            run_step_up_flow!(forbidden_error: e)
+
+            retry
+          end
+
           raise RequestHandlerError.new(
             "You are forbidden to make #{method} requests",
             { method: method, params: params },
@@ -337,16 +351,63 @@ module MCP
       #
       # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#error-handling
       def run_oauth_flow!(unauthorized_error:)
-        response = unauthorized_error.response || {}
-        response_headers = response[:headers] || {}
-        www_authenticate = response_headers["www-authenticate"] || response_headers["WWW-Authenticate"]
-        params = MCP::Client::OAuth::Discovery.parse_www_authenticate(www_authenticate)
+        params = parse_www_authenticate_from_error(unauthorized_error)
+        flow = MCP::Client::OAuth::Flow.new(provider: @oauth)
+        return if attempt_refresh(flow: flow, resource_metadata_url: params["resource_metadata"])
 
+        run_full_authorization_flow!(flow: flow, params: params)
+      end
+
+      # Drives a full Authorization Code + PKCE flow without first attempting
+      # to refresh the access token. Used for the MCP scope-selection-strategy
+      # step-up path: the provider already holds a valid access token,
+      # but the server returned a 403 with
+      # `WWW-Authenticate: ... error="insufficient_scope", scope="..."`
+      # per RFC 6750 Section 3.1. Refreshing the existing token would re-issue
+      # the same scope set the server already rejected, so the SDK must run
+      # a fresh authorization request. The request asks for the union of
+      # the currently granted scope and the newly demanded scope; otherwise
+      # the caller would lose previously held scopes and trigger another step-up
+      # on the next operation that needs them.
+      # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-selection-strategy
+      def run_step_up_flow!(forbidden_error:)
+        params = parse_www_authenticate_from_error(forbidden_error)
         flow = MCP::Client::OAuth::Flow.new(provider: @oauth)
-        if attempt_refresh(flow: flow, resource_metadata_url: params["resource_metadata"])
-          return
-        end
+        params = params.merge("scope" => escalated_step_up_scope(params["scope"]))
+
+        run_full_authorization_flow!(flow: flow, params: params)
+      end
+
+      # Returns the space-separated union of the currently granted scope (read
+      # from the stored token response per RFC 6749 Section 5.1) and the scope
+      # demanded by the step-up challenge. Duplicates are collapsed; order
+      # follows first appearance so existing scopes precede the newly added
+      # ones. Returns `nil` when neither side carries a scope so
+      # `build_authorization_url` omits the `scope` parameter entirely.
+      def escalated_step_up_scope(challenge_scope)
+        tokens = @oauth.tokens
+        granted = tokens.is_a?(Hash) ? (tokens["scope"] || tokens[:scope]) : nil
+        scopes = [granted, challenge_scope].compact.flat_map { |scope| scope.to_s.split }.uniq
+
+        scopes.empty? ? nil : scopes.join(" ")
+      end
+
+      # True when the response on `forbidden_error` carries a Bearer challenge
+      # with `error="insufficient_scope"` per RFC 6750 Section 3.1 and the MCP
+      # scope-selection-strategy section. A 403 without that signal is not a
+      # step-up challenge and must not trigger re-authorization.
+      def insufficient_scope_challenge?(forbidden_error)
+        parse_www_authenticate_from_error(forbidden_error)["error"] == "insufficient_scope"
+      end
+
+      def parse_www_authenticate_from_error(error)
+        response = error.response || {}
+        response_headers = response[:headers] || {}
+        header = response_headers["www-authenticate"] || response_headers["WWW-Authenticate"]
+        MCP::Client::OAuth::Discovery.parse_www_authenticate(header)
+      end
 
+      def run_full_authorization_flow!(flow:, params:)
         # Use the URL snapshotted at `initialize` time so a post-construction
         # mutation of `@url` cannot redirect PRM/AS discovery and the authorize
         # URL to an attacker-controlled host.

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    module OAuth
+      # OAuth client configuration for the OAuth 2.1 `client_credentials` grant
+      # (machine-to-machine, no user and no browser redirect). Handed to
+      # `MCP::Client::HTTP` via the `oauth:` keyword, the same as `Provider`.
+      # The interactive Authorization Code flow lives in `Provider`;
+      # this class exists so a credentials-only client never has to supply
+      # the redirect arguments that grant has no use for, mirroring the dedicated
+      # `ClientCredentialsProvider` in the TypeScript SDK and
+      # `ClientCredentialsOAuthProvider` in the Python SDK.
+      #
+      # Required keyword arguments:
+      #
+      # - `client_id`     - String identifying the pre-registered confidential client.
+      # - `client_secret` - String shared secret. The `client_credentials` grant
+      #   is for confidential clients, so a credential is mandatory.
+      #
+      # Optional keyword arguments:
+      #
+      # - `token_endpoint_auth_method` - `"client_secret_basic"` (default) or
+      #   `"client_secret_post"`. `"none"` is rejected: an unauthenticated
+      #   `client_credentials` request is meaningless.
+      # - `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.
+      class ClientCredentialsProvider
+        include StorageBackedProvider
+
+        # Raised when the credentials required for the `client_credentials` grant are
+        # missing or the requested client authentication method cannot carry them.
+        class InvalidCredentialsError < ArgumentError; end
+
+        SUPPORTED_AUTH_METHODS = ["client_secret_basic", "client_secret_post"].freeze
+
+        attr_reader :scope, :storage
+
+        def initialize(
+          client_id:,
+          client_secret:,
+          token_endpoint_auth_method: "client_secret_basic",
+          scope: nil,
+          storage: nil
+        )
+          if blank?(client_id)
+            raise InvalidCredentialsError, "client_id is required for the client_credentials grant."
+          end
+
+          unless SUPPORTED_AUTH_METHODS.include?(token_endpoint_auth_method)
+            raise InvalidCredentialsError,
+              "token_endpoint_auth_method must be one of #{SUPPORTED_AUTH_METHODS.inspect} for the " \
+                "client_credentials grant (got #{token_endpoint_auth_method.inspect}); an unauthenticated " \
+                "client_credentials request is not allowed."
+          end
+
+          if blank?(client_secret)
+            raise InvalidCredentialsError,
+              "client_secret is required for the client_credentials grant with #{token_endpoint_auth_method}."
+          end
+
+          @scope = scope
+          @storage = storage || InMemoryStorage.new
+          @storage.save_client_information(
+            "client_id" => client_id,
+            "client_secret" => client_secret,
+            "token_endpoint_auth_method" => token_endpoint_auth_method,
+          )
+        end
+
+        # See `Provider#authorization_flow`.
+        def authorization_flow
+          :client_credentials
+        end
+
+        private
+
+        def blank?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
+        end
+      end
+    end
+  end
+end

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

@@ -90,7 +90,17 @@ module MCP
           end
 
           # Returns the candidate Authorization Server metadata URLs to probe, in priority order.
-          # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery
+          #
+          # Per SEP-2351, MCP uses the default `oauth-authorization-server` well-known URI suffix
+          # registered by RFC 8414 Section 7.3 and defines no application-specific suffix of its own.
+          # The OAuth candidates below therefore use only that default suffix
+          # (plus the `openid-configuration` suffix from OpenID Connect Discovery),
+          # both in the RFC 8414 Section 3.1 path-inserted form for issuers with a path component
+          # and in the root form for issuers without one.
+          #
+          # - https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#authorization-server-metadata-discovery
+          # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2351
+          # - https://www.rfc-editor.org/rfc/rfc8414#section-3.1
           def authorization_server_metadata_urls(issuer_url)
             uri = URI.parse(issuer_url)
             path = uri.path == "/" ? "" : uri.path.to_s
@@ -183,6 +193,50 @@ module MCP
             false
           end
 
+          # Returns true when `url` satisfies the structural requirements for
+          # a Client ID Metadata Document URL per the MCP 2025-11-25
+          # authorization specification and `draft-ietf-oauth-client-id-metadata-document-00`.
+          #
+          # Spec-required:
+          #
+          # - scheme MUST be `https` (the loopback-`http` carve-out used for discovery does not apply:
+          #   the document URL is sent verbatim to the authorization server as the OAuth `client_id`
+          #   and travels off-loopback)
+          # - host MUST be present
+          # - path MUST be non-empty and MUST NOT be the root (`/`); the document is a discrete resource,
+          #   not the origin
+          # - URL MUST NOT carry a fragment or userinfo: a fragment is not sent to the server, and userinfo
+          #   would leak credentials into every `client_id` log line
+          # - path MUST be already free of `.` / `..` dot segments after percent-decoding, so two URLs with
+          #   the same effective path do not produce different `client_id` strings
+          #
+          # SDK policy (stricter than the draft):
+          #
+          # - URL MUST NOT carry a query string. The draft marks query components only SHOULD NOT include,
+          #   but different encodings of the same query (`?a=1&b=2` vs `?b=2&a=1`) would yield distinct
+          #   `client_id` values for the same logical document.
+          def client_id_metadata_document_url?(url)
+            return false if url.nil? || url.to_s.empty?
+
+            uri = URI.parse(url.to_s)
+            return false unless uri.scheme&.downcase == "https"
+            return false if uri.host.nil? || uri.host.empty?
+            return false unless uri.fragment.nil?
+            return false unless uri.query.nil?
+            return false if uri.respond_to?(:user) && (uri.user || uri.password)
+
+            path = uri.path.to_s
+            return false if path.empty? || path == "/"
+
+            decoded = path.gsub(/%2[eE]/, ".")
+            segments = decoded.split("/", -1)
+            return false if segments.any? { |segment| segment == "." || segment == ".." }
+
+            true
+          rescue URI::InvalidURIError
+            false
+          end
+
           # Like `canonicalize_url` but also strips query string, fragment, and
           # userinfo. This variant is used for identity comparison against
           # the request URL Faraday actually sends, which differs from the value

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

@@ -54,11 +54,17 @@ module MCP
           as_metadata = fetch_authorization_server_metadata(issuer_url: authorization_server)
           ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
           ensure_secure_endpoints!(as_metadata)
+
+          if provider_authorization_flow == :client_credentials
+            return run_client_credentials!(as_metadata: as_metadata, prm: prm, resource: resource, scope: scope)
+          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)
           pkce = PKCE.generate
           state = SecureRandom.urlsafe_base64(32)
 
@@ -91,21 +97,60 @@ module MCP
           :authorized
         end
 
-        # Exchanges the saved `refresh_token` for a fresh access token (RFC 6749
-        # Section 6). Re-discovers PRM and AS metadata so we always pick up a moved
-        # token endpoint, and re-runs the audience / issuer / security checks
-        # before talking to it.
+        # 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).
+        # 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:)
+          client_info = client_credentials_client_info
+
+          form = { "grant_type" => "client_credentials" }
+          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)
+          :authorized
+        end
+
+        # Reads the pre-registered credentials for the `client_credentials` grant directly from the provider's stored
+        # `client_information`, rather than going through `ensure_client_registered` (which targets the authorization-code
+        # flow and reaches for `Provider`-only methods like `client_metadata` and `client_id_metadata_document_url`).
+        # The grant is for confidential clients, so a missing `client_id` is a clean configuration error, not a fallback
+        # to dynamic registration.
+        def client_credentials_client_info
+          info = @provider.client_information
+          unless info.is_a?(Hash) && client_info_required_value(info, "client_id")
+            raise AuthorizationError,
+              "Cannot run the client_credentials grant: the provider has no stored `client_id`."
+          end
+
+          info
+        end
+
+        # Exchanges the saved `refresh_token` for a fresh access token (RFC 6749 Section 6).
+        # Re-discovers PRM and AS metadata so we always pick up a moved token endpoint, and re-runs the audience / issuer / security
+        # checks before talking to it.
         #
-        # Returns `:refreshed` on success. Raises `AuthorizationError` when
-        # the provider has no refresh token, no client information, or when
-        # the token endpoint refuses the refresh request.
+        # Returns `:refreshed` on success. Raises `AuthorizationError` when the provider has no refresh token, no client information,
+        # 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
 
-          client_info = @provider.client_information
-          unless client_info.is_a?(Hash) && client_info_required_value(client_info, "client_id")
+          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?
+
+          unless have_stored_client_info || have_cimd_url
             raise AuthorizationError, "Cannot refresh: no client_information in provider storage."
           end
 
@@ -126,6 +171,18 @@ module MCP
           ensure_issuer_matches!(expected: authorization_server, returned: as_metadata["issuer"])
           ensure_secure_endpoints!(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.
+            stored_client_info
+          elsif as_metadata["client_id_metadata_document_supported"] == true
+            { "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 " \
+                "`client_id_metadata_document_supported: true`."
+          end
+
           new_tokens = exchange_refresh_token(
             as_metadata: as_metadata,
             client_info: client_info,
@@ -285,6 +342,24 @@ module MCP
           existing = @provider.client_information
           return existing if existing.is_a?(Hash) && client_info_required_value(existing, "client_id")
 
+          # Per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`,
+          # if the authorization server advertises Client ID Metadata Document support and the provider has
+          # a CIMD URL configured, use the URL as the OAuth `client_id` and skip Dynamic Client Registration.
+          #
+          # The `== true` comparison is intentional: only a JSON `boolean` `true` opts the flow in.
+          # A string `"false"`, an empty Hash, or any other truthy value MUST NOT be treated as CIMD support,
+          # otherwise a misconfigured AS could trick the client into using the CIMD `client_id` against
+          # a server that has not actually adopted it.
+          #
+          # The CIMD `client_id` is NOT persisted to storage. The AS may later stop advertising CIMD support
+          # (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
+          if cimd_url && as_metadata["client_id_metadata_document_supported"] == true
+            return { "client_id" => cimd_url }
+          end
+
           registration_endpoint = as_metadata["registration_endpoint"]
           unless registration_endpoint
             raise AuthorizationError,
@@ -403,6 +478,60 @@ module MCP
           nil
         end
 
+        # Applies the SDK's `offline_access` policy to the resolved scope. The policy has two halves:
+        #
+        # - Spec (SEP-2207): a client that wants a refresh token (signalled here by listing
+        #   `refresh_token` in its registered `grant_types`) MAY request `offline_access`
+        #   when the authorization server advertises it in metadata `scopes_supported`.
+        #   When the server advertises it and the client opted in, add it if absent.
+        #
+        # - SDK policy (defensive hardening): when the server does NOT advertise `offline_access`,
+        #   strip it from the resolved scope no matter where it came from (the `WWW-Authenticate` challenge,
+        #   PRM `scopes_supported`, or the provider-supplied scope). SEP-2207 only says clients SHOULD NOT
+        #   request unsupported scopes, but a misbehaving RS that includes `offline_access` in its challenge,
+        #   or a misconfigured PRM that lists it under `scopes_supported`, would otherwise propagate into
+        #   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.
+        # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207
+        def normalize_offline_access_scope(scope, as_metadata:)
+          scopes = scope.to_s.split
+
+          if server_supports_offline_access?(as_metadata)
+            scopes << "offline_access" if wants_refresh_token? && !scopes.include?("offline_access")
+          else
+            scopes.delete("offline_access")
+          end
+
+          scopes.empty? ? nil : scopes.join(" ")
+        end
+
+        def server_supports_offline_access?(as_metadata)
+          supported = as_metadata["scopes_supported"]
+
+          supported.is_a?(Array) && supported.include?("offline_access")
+        end
+
+        def wants_refresh_token?
+          metadata = @provider.client_metadata
+          grant_types = metadata[:grant_types] || metadata["grant_types"]
+
+          Array(grant_types).include?("refresh_token")
+        end
+
+        # The OAuth flow the provider drives. Dispatching on the provider's
+        # declared flow keeps `Flow` from second-guessing intent by parsing
+        # `client_metadata[:grant_types]` (which is protocol metadata for the
+        # authorization server, not an SDK control signal). A provider that
+        # predates this method is treated as the interactive authorization-code
+        # flow it was the only option for.
+        def provider_authorization_flow
+          return :authorization_code unless @provider.respond_to?(:authorization_flow)
+
+          @provider.authorization_flow
+        end
+
         def build_authorization_url(as_metadata:, client_id:, scope:, state:, code_challenge:, resource:)
           authorization_endpoint = as_metadata["authorization_endpoint"]
           unless authorization_endpoint