Support Client ID Metadata Documents in OAuth client

## Motivation and Context

The MCP 2025-11-25 authorization specification and `draft-ietf-oauth-client-id-metadata-document-00` define
Client ID Metadata Documents (CIMD): a client publishes its OAuth metadata at an HTTPS URL and uses that URL
as the OAuth `client_id` instead of going through Dynamic Client Registration. The Python and TypeScript SDKs
already implement this; the Ruby SDK now reaches parity.

The change adds:

- `MCP::Client::OAuth::Provider` accepts an optional `client_id_metadata_document_url:` keyword.
- A new `Discovery.client_id_metadata_document_url?` validator enforces structural requirements.
  Spec-required: `https` scheme, a non-root path, and no fragment, userinfo, or `.`/`..` segments
  (including the percent-encoded form `%2E`). Stricter than the draft as an SDK policy: query strings
  are also rejected, because different encodings of the same query would yield distinct `client_id` strings for
  the same logical document. The loopback `http` carve-out used for discovery URLs does not extend to CIMD URLs,
  since the value is sent verbatim to the authorization server as the OAuth `client_id` and travels off-loopback.
  Validation failures raise `Provider::InvalidClientIDMetadataDocumentURLError`.
- `Flow#ensure_client_registered` routes through CIMD only when the authorization server advertises
  `client_id_metadata_document_supported` as JSON `boolean true`; truthy non-boolean values
  (string `"true"`, `"false"`, etc.) fall back to DCR, matching the gating in the Python and TypeScript SDKs.
- The CIMD `client_id` is NOT persisted to storage. AS support is re-read on every flow so a server
  that later drops CIMD support stops receiving the stale URL. Pre-registered `client_information`
  continues to win over CIMD when both are available.
- `Flow#refresh!` reconstructs the CIMD `client_id` from live AS metadata when refreshing tokens obtained via CIMD.
  When support has been withdrawn and no other identity is stored, it raises a clear `AuthorizationError` rather than
  sending a `client_id` the authorization server no longer recognises.
- The Provider docstring and README OAuth section explain that DCR `client_metadata` and the JSON document served at
  the CIMD URL are separate artifacts: DCR 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`.
- `auth/basic-cimd` is removed from `conformance/expected_failures.yml`.

## How Has This Been Tested?

`Discovery` tests cover: https with path accepted; non-https rejected (http, ftp, file); root and empty path rejected;
fragment, query, and userinfo rejected; dot segments rejected including the percent-encoded form `%2E`; nil, empty,
and malformed inputs rejected.

`Provider` tests cover: the default `nil`; rejection of http URLs (loopback included); non-https schemes;
root and empty path; fragment; query; userinfo; and dot segments.

`Flow#run!` tests cover: skip DCR when the authorization server advertises CIMD and the provider has a URL;
fall back to DCR when the authorization server does not advertise support; fall back to DCR when the value is
the string `"false"` or `"true"`; pre-registered `client_information` wins over CIMD; the CIMD `client_id` is not
persisted to storage; a second flow against an authorization server that has dropped CIMD support recovers via DCR.

`Flow#refresh!` tests cover: refresh reconstructs the CIMD `client_id` without a stored `client_information`;
refresh raises when the authorization server no longer advertises CIMD support; stored `client_information`
takes precedence over the CIMD URL during refresh.

Conformance: `auth/basic-cimd` now passes 12/12 with no warnings. `bundle exec rake test`, `bundle exec rake rubocop`,
and `bundle exec rake conformance` are all green.

## Breaking Changes

None. The `client_id_metadata_document_url:` keyword is purely opt-in and defaults to `nil`.
When the keyword is omitted, the DCR flow is unchanged. Existing OAuth users see no behaviour change.
The CIMD path is only entered when both the user explicitly configures a URL and the authorization server
advertises support via `client_id_metadata_document_supported: true`.

Author: koic

README.md

@@ -1958,6 +1958,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:
 

conformance/client.rb

@@ -19,6 +19,11 @@
   abort("Usage: MCP_CONFORMANCE_SCENARIO=<scenario> ruby conformance/client.rb <server-url>")
 end
 
+# URL the conformance harness expects to see as the OAuth `client_id` for the `auth/basic-cimd` scenario
+# when the AS advertises `client_id_metadata_document_supported`. The harness does not fetch the document,
+# only matches the value, so the URL does not need to resolve.
+CONFORMANCE_CIMD_URL = "https://conformance-test.local/client-metadata.json"
+
 # The conformance harness optionally injects scenario-specific data via
 # the `MCP_CONFORMANCE_CONTEXT` environment variable as a JSON document. The shape is
 # defined by the harness, not the MCP spec, and has varied between versions:
@@ -50,7 +55,7 @@ def conformance_context
 # non-interactively against the conformance test's auth server. The conformance
 # `/authorize` endpoint redirects synchronously to `redirect_uri` with
 # `code=test-auth-code`, so we follow it manually instead of opening a browser.
-def build_oauth_provider(context)
+def build_oauth_provider(context, scenario:)
   callback_holder = {}
   redirect_uri = "http://localhost:0/callback"
 
@@ -90,10 +95,11 @@ def build_oauth_provider(context)
     redirect_handler: redirect_handler,
     callback_handler: callback_handler,
     storage: storage,
+    client_id_metadata_document_url: (scenario == "auth/basic-cimd" ? CONFORMANCE_CIMD_URL : nil),
   )
 end
 
-oauth = scenario.start_with?("auth/") ? build_oauth_provider(conformance_context) : nil
+oauth = scenario.start_with?("auth/") ? build_oauth_provider(conformance_context, scenario: scenario) : nil
 transport = MCP::Client::HTTP.new(url: server_url, oauth: oauth)
 client = MCP::Client.new(transport: transport)
 client.connect(client_info: { name: "ruby-sdk-conformance-client", version: MCP::VERSION })

conformance/expected_failures.yml

@@ -5,7 +5,6 @@ client:
   # TODO: Elicitation not implemented in Ruby client.
   - elicitation-sep1034-client-defaults
   # TODO: Remaining OAuth/auth scenarios not yet implemented in Ruby client.
-  - auth/basic-cimd
   - auth/scope-step-up
   - auth/2025-03-26-oauth-metadata-backcompat
   - auth/2025-03-26-oauth-endpoint-fallback

lib/mcp/client/oauth/discovery.rb

@@ -183,6 +183,50 @@ def secure_url?(url)
             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

lib/mcp/client/oauth/flow.rb

@@ -104,8 +104,16 @@ 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 +134,18 @@ def refresh!(server_url:, resource_metadata_url: nil)
           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 +305,24 @@ def ensure_client_registered(as_metadata:)
           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,

lib/mcp/client/oauth/provider.rb

@@ -25,6 +25,16 @@ module OAuth
       # - `storage` - Object responding to `tokens`, `save_tokens(tokens)`,
       #   `client_information`, and `save_client_information(info)`. Defaults to
       #   an `InMemoryStorage`.
+      # - `client_id_metadata_document_url` - URL where the client publishes its Client ID Metadata Document
+      #   (`draft-ietf-oauth-client-id-metadata-document-00` 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: `https://` scheme, a non-root path, and no fragment, userinfo, or `.`/`..` segments.
+      #   The SDK additionally refuses to send query strings (the draft marks them only SHOULD NOT include,
+      #   but different encodings of the same query would yield different `client_id` strings for the same document).
+      #   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`.
       class Provider
         # Raised when `Provider#initialize` is called with a `redirect_uri` that
         # is neither HTTPS nor a loopback `http://` URL, per the MCP
@@ -38,20 +48,30 @@ class InsecureRedirectURIError < ArgumentError; end
         # runtime; failing at construction surfaces the bug earlier.
         class UnregisteredRedirectURIError < ArgumentError; end
 
+        # Raised when `client_id_metadata_document_url` is provided but does not meet
+        # the structural requirements for a Client ID Metadata Document URL:
+        # HTTPS, non-root path, and no fragment, query, userinfo, or `.`/`..` segments.
+        # The CIMD URL is sent to the authorization server as the OAuth `client_id`,
+        # so the same Communication Security guarantee that protects the redirect URI
+        # applies and the value must unambiguously identify the document.
+        class InvalidClientIDMetadataDocumentURLError < ArgumentError; end
+
         attr_reader :client_metadata,
           :redirect_uri,
           :scope,
           :storage,
           :redirect_handler,
-          :callback_handler
+          :callback_handler,
+          :client_id_metadata_document_url
 
         def initialize(
           client_metadata:,
           redirect_uri:,
           redirect_handler:,
           callback_handler:,
           scope: nil,
-          storage: nil
+          storage: nil,
+          client_id_metadata_document_url: nil
         )
           unless Discovery.secure_url?(redirect_uri)
             raise InsecureRedirectURIError,
@@ -66,12 +86,20 @@ def initialize(
                 "(got #{registered.inspect}); otherwise the authorization server will reject the authorization request."
           end
 
+          if client_id_metadata_document_url && !Discovery.client_id_metadata_document_url?(client_id_metadata_document_url)
+            raise InvalidClientIDMetadataDocumentURLError,
+              "client_id_metadata_document_url #{client_id_metadata_document_url.inspect} must be an https URL " \
+                "with a non-root path and no fragment, query, userinfo, or `.`/`..` segments, " \
+                "per the MCP authorization specification and `draft-ietf-oauth-client-id-metadata-document`."
+          end
+
           @client_metadata = client_metadata
           @redirect_uri = redirect_uri
           @redirect_handler = redirect_handler
           @callback_handler = callback_handler
           @scope = scope
           @storage = storage || InMemoryStorage.new
+          @client_id_metadata_document_url = client_id_metadata_document_url
         end
 
         def access_token

test/mcp/client/oauth/discovery_test.rb

@@ -367,6 +367,68 @@ def test_secure_url_rejects_malformed_or_hostless_urls
           refute(Discovery.secure_url?("not a url"))
         end
 
+        def test_client_id_metadata_document_url_accepts_https_with_path
+          assert(Discovery.client_id_metadata_document_url?("https://app.example.com/client-metadata.json"))
+          assert(Discovery.client_id_metadata_document_url?("https://app.example.com/path/to/cm"))
+          assert(Discovery.client_id_metadata_document_url?("https://app.example.com:8443/cm"))
+        end
+
+        def test_client_id_metadata_document_url_accepts_boundary_forms
+          # An uppercase scheme is `https` after case folding (URIs are scheme-insensitive, RFC 3986 Section 3.1).
+          assert(Discovery.client_id_metadata_document_url?("HTTPS://app.example.com/cm"))
+
+          # A trailing slash and consecutive slashes are non-root, non-dot paths.
+          # RFC 3986 `remove_dot_segments` does not collapse them, so they remain
+          # stable `client_id` strings rather than aliasing another URL.
+          assert(Discovery.client_id_metadata_document_url?("https://app.example.com/cm/"))
+          assert(Discovery.client_id_metadata_document_url?("https://app.example.com//cm"))
+
+          # The default https port is equivalent to omitting it; either form is a valid origin.
+          assert(Discovery.client_id_metadata_document_url?("https://app.example.com:443/cm"))
+
+          # IPv6 literal hosts and Punycode (IDN) hosts are ordinary hosts.
+          assert(Discovery.client_id_metadata_document_url?("https://[2001:db8::1]/cm"))
+          assert(Discovery.client_id_metadata_document_url?("https://[::1]/cm"))
+          assert(Discovery.client_id_metadata_document_url?("https://xn--e1afmkfd.example.com/cm"))
+        end
+
+        def test_client_id_metadata_document_url_rejects_non_https_schemes
+          refute(Discovery.client_id_metadata_document_url?("http://localhost/cm"))
+          refute(Discovery.client_id_metadata_document_url?("http://app.example.com/cm"))
+          refute(Discovery.client_id_metadata_document_url?("ftp://app.example.com/cm"))
+          refute(Discovery.client_id_metadata_document_url?("file:///cm"))
+        end
+
+        def test_client_id_metadata_document_url_rejects_root_and_empty_path
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com"))
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/"))
+        end
+
+        def test_client_id_metadata_document_url_rejects_fragment_query_userinfo
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/cm#frag"))
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/cm?x=1"))
+          refute(Discovery.client_id_metadata_document_url?("https://user:pass@app.example.com/cm"))
+          refute(Discovery.client_id_metadata_document_url?("https://user@app.example.com/cm"))
+        end
+
+        def test_client_id_metadata_document_url_rejects_dot_segments
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/./cm"))
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/a/../cm"))
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/cm/."))
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/cm/.."))
+          # Percent-encoded `.` would otherwise let `%2E` and `.` produce
+          # different `client_id` values for the same document.
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/%2E/cm"))
+          refute(Discovery.client_id_metadata_document_url?("https://app.example.com/%2e/cm"))
+        end
+
+        def test_client_id_metadata_document_url_rejects_nil_or_empty_or_malformed
+          refute(Discovery.client_id_metadata_document_url?(nil))
+          refute(Discovery.client_id_metadata_document_url?(""))
+          refute(Discovery.client_id_metadata_document_url?("not a url"))
+          refute(Discovery.client_id_metadata_document_url?("https://"))
+        end
+
         def test_resource_covers_blocks_percent_encoded_dot_segment_bypass
           server = Discovery.canonicalize_url("https://srv.example.com/api/%2e%2e/mcp")
           prm = Discovery.canonicalize_url("https://srv.example.com/api")