ruby-mcp-client 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99574cdccfbab39918f6576fc7c896b5208599313bd69e2f39df5b529c82c22
-  data.tar.gz: 823177bc1a531d773514b9d9da8d3d6f0f2aa15f6e8562e8c0123adcdb38911c
+  metadata.gz: 5687a9c54b7e5c4814e80bd2e5e97d2072dd0f994e3bebe680259a1a9db64c25
+  data.tar.gz: 05b3bce582f21e57ae07ac862daf6a74812f3ba79f6e4b806868850686c33467
 SHA512:
-  metadata.gz: bc352d545dbabb90322ab473eaff7c6d52111ccd6e4812baa8b6507dc720024e23752b4a68481dc5b83722d2c9c4b6b3a36a17821998fc745cd8164e57ac8380
-  data.tar.gz: 72b2cdc279b54f2b10cbac22755086edee67792bd18e035d167f2855ad1d5dc5999c87d98e17bef83a70632459003bbd4af516414fe0e7b78b918fc2b2c5a8ce
+  metadata.gz: 3aef7d0842eab30de7e84a5507298efd30ae78de3ea3223cc8f00bd31892e7665f55f533952df771a2d3ab38f874d3905e029b0d19b8147d07ffd030772106fe
+  data.tar.gz: 324f5121352512f827f05fa55f78917b3218b7d031c418cfa884a8718b2b06fda027b8b811df2083361200ff17682dbfea8998505db0e2932db3a545f605c35a

data/README.md

@@ -28,7 +28,10 @@ Built-in API conversions: `to_openai_tools()`, `to_anthropic_tools()`, `to_googl
 
 ## MCP Protocol Support
 
-Implements **MCP 2025-11-25** specification:
+Implements the **MCP 2025-11-25** specification. The client negotiates the
+protocol version during `initialize` and disconnects if the server answers
+with a revision it cannot speak (supported: `2025-11-25`, `2025-06-18`,
+`2025-03-26`, `2024-11-05`):
 
 - **Tools**: list, call, streaming, annotations (hint-style), structured outputs, title
 - **Prompts**: list, get with parameters
@@ -40,7 +43,9 @@ Implements **MCP 2025-11-25** specification:
 - **Logging**: Server log messages with level filtering
 - **Tasks**: Task-augmented `tools/call` — create with a `ttl`, poll `tasks/get`, retrieve via `tasks/result`, plus `tasks/list` and `tasks/cancel`
 - **Audio**: Audio content type support
-- **OAuth 2.1**: PKCE, server discovery, dynamic registration
+- **Progress & Cancellation**: `progressToken` plumbing with per-call callbacks; automatic `notifications/cancelled` for abandoned requests
+- **Metadata**: `icons`, `title` and `_meta` parsed on tools, prompts and resources
+- **OAuth 2.1**: PKCE (S256 required), RFC 8414/9728 discovery, dynamic registration, Client ID Metadata Documents, scope step-up challenges
 
 ## Quick Connect API (Recommended)
 
@@ -152,6 +157,25 @@ tool.output_schema       # JSON Schema for output
 
 result = client.call_tool('get_weather', { location: 'SF' })
 data = result['structuredContent']  # Type-safe structured data
+
+# Per MCP 2025-11-25, clients SHOULD validate structured results against the
+# tool's output schema, and a tool that declares an outputSchema must return
+# structuredContent in successful results. call_tool checks both automatically
+# for the common JSON Schema keywords (type, properties, required, items, enum,
+# numeric/string bounds). The full 2020-12 vocabulary ($ref/$dynamicRef/$defs,
+# allOf/anyOf/oneOf/not, if/then/else, additionalProperties, patternProperties,
+# propertyNames, prefixItems, contains/minContains/maxContains, uniqueItems,
+# multipleOf, format, dependentRequired/dependentSchemas, minProperties/
+# maxProperties, unevaluated*) is NOT evaluated: when a schema uses any of
+# those keywords, call_tool logs a "validation is partial" warning naming them
+# (in both modes), since data may pass this check that a full validator would
+# reject. By default a violation (mismatch, or missing structuredContent on a
+# successful result) logs a warning; opt in to strict mode to raise instead:
+client = MCPClient::Client.new(
+  mcp_server_configs: [...],
+  validate_structured_content: :strict # raises MCPClient::Errors::ValidationError on violation
+)
+# Task-delivered results (get_task_result) are not validated yet.
 ```
 
 ### Roots
@@ -184,6 +208,81 @@ client = MCPClient.connect('http://server/mcp',
 )
 ```
 
+Sampling tool calling (SEP-1577) is opt-in: pass `sampling_supports_tools: true`
+to declare the `sampling.tools` capability. The handler then receives the full
+request params (including `tools`/`toolChoice`) as an optional fifth argument;
+without the opt-in, tool-enabled sampling requests are rejected with `-32602`
+as the spec requires:
+
+```ruby
+client = MCPClient::Client.new(
+  mcp_server_configs: [...],
+  sampling_supports_tools: true,
+  sampling_handler: ->(messages, prefs, system_prompt, max_tokens, params = nil) {
+    tools = params && params['tools'] # ToolUseContent may be returned in content
+    # ...
+  }
+)
+```
+
+### Progress Tracking
+
+Attach a per-call progress callback — the client generates a unique
+`progressToken`, places it in the request `_meta`, and routes matching
+`notifications/progress` to your block while the request is active (stale
+tokens after completion are dropped):
+
+```ruby
+client.call_tool('long_running', args, progress: ->(progress, total, message) {
+  puts "#{message}: #{progress}/#{total}"
+})
+```
+
+A request-level `_meta` (e.g. a hand-picked `progressToken`) can also be passed
+inside the arguments under the `'_meta'` key on every transport — it is hoisted
+to the JSON-RPC params level on the wire, never sent as a tool argument.
+
+### Timeouts and Cancellation
+
+Timeouts are configurable per request in addition to the per-server
+`read_timeout`. A timed-out request raises
+`MCPClient::Errors::RequestTimeoutError` (a `TransportError` subclass), is
+**never** silently re-sent by the retry layer, and a best-effort
+`notifications/cancelled` is sent for the abandoned request (never for
+`initialize`, and task-augmented calls use `tasks/cancel` instead):
+
+```ruby
+client.send_rpc('tools/call', params: { name: 'slow', arguments: {} }, timeout: 300)
+server.rpc_request('tools/list', {}, timeout: 5)
+```
+
+### Client Identity and Server Instructions
+
+Hosts can present their own `Implementation` info (sent as `clientInfo` during
+initialize; `name` and `version` required — `title`, `description`,
+`websiteUrl`, `icons` optional), and read the server's `instructions` hint
+after connecting:
+
+```ruby
+client = MCPClient::Client.new(
+  mcp_server_configs: [...],
+  client_info: { 'name' => 'my-ide', 'version' => '2.0.0', 'description' => 'An MCP-powered IDE' }
+)
+client.servers.first.connect
+puts client.servers.first.instructions # e.g. "Use the search tool before answering."
+```
+
+### Capability Gating
+
+Optional server features (`logging/setLevel`, `resources/subscribe`,
+`completion/complete`, `tasks/list`, `tasks/cancel`) are only sent to servers
+that negotiated the corresponding capability; otherwise
+`MCPClient::Errors::CapabilityError` is raised (the lifecycle forbids using
+capabilities that were not negotiated). `Client#log_level=` skips
+non-logging servers instead of failing. Declared *client* capabilities are
+derived from what the host actually registered (handlers, roots), never
+hardcoded.
+
 ### Completion (Autocomplete)
 
 ```ruby
@@ -213,6 +312,9 @@ end
 A task-capable server (one advertising `tasks.requests.tools.call`) can run a tool
 whose `execution.taskSupport` is `optional` or `required` as a background task:
 the call returns immediately with a task handle, and the result is fetched later.
+Try it locally: `python3 examples/echo_server_streamable.py &` then
+`./examples/tasks_example.rb` runs the full lifecycle against a task-capable
+demo server.
 
 ```ruby
 tool = client.find_tool('long_job')
@@ -470,6 +572,20 @@ Features: PKCE, server discovery (`.well-known`), dynamic registration, token re
 
 See [OAUTH.md](OAUTH.md) for full documentation.
 
+### OAuth Extras (2025-11-25)
+
+- **Client ID Metadata Documents (SEP-991)** — pass
+  `client_id_metadata_url: 'https://myapp.example/oauth-client.json'` (an HTTPS
+  URL with a path, which doubles as the `client_id`); when the authorization
+  server advertises `client_id_metadata_document_supported`, dynamic client
+  registration is skipped entirely.
+- **Scope challenges (SEP-835)** — an HTTP 403 `insufficient_scope` challenge
+  raises `MCPClient::Errors::InsufficientScopeError` (a `ConnectionError`
+  subclass) exposing `#scope` and `#error_description`; the challenged scopes
+  are treated as authoritative for the next authorization flow.
+- **PKCE** — authorization refuses to proceed when the authorization server
+  does not advertise `code_challenge_methods_supported` including `S256`.
+
 ## Server Notifications
 
 ```ruby
@@ -492,7 +608,9 @@ Both HTTP and Streamable HTTP transports automatically handle session-based serv
 - **Session capture**: Extracts `Mcp-Session-Id` from initialize response
 - **Session persistence**: Includes session header in subsequent requests
 - **Session termination**: Sends DELETE request during cleanup
-- **Resumability** (Streamable HTTP): Tracks event IDs for message replay
+- **Resumability** (Streamable HTTP, SEP-1699): tracks SSE event IDs and, when a
+  response stream is interrupted, resumes via GET with `Last-Event-ID` so the
+  server can replay missed messages — honoring the server's `retry:` directive
 
 No configuration required - works automatically.
 

data/lib/mcp_client/auth/oauth_provider.rb

@@ -11,6 +11,18 @@ module MCPClient
     # Handles the complete OAuth flow including server discovery, client registration,
     # authorization, token exchange, and refresh
     class OAuthProvider
+      # One auth-param (name = token / quoted-string) as it appears in a
+      # WWW-Authenticate challenge (RFC 7235 §2.1, optional whitespace around
+      # '='). Mirrors HttpTransportBase::AUTH_PARAM so provider-side challenge
+      # parsing segments headers exactly like the transport does.
+      AUTH_PARAM = /[A-Za-z0-9._~+-]+\s*=\s*(?:"(?:[^"\\]|\\.)*"|[^,\s]*)/
+      # A run of comma/space separated auth-params anchored at the start of a
+      # string. The run ends before a token that is NOT followed by '=' — the
+      # auth-scheme introducing the next challenge — while commas inside quoted
+      # values are consumed by the quoted-string branch, not treated as
+      # boundaries. Mirrors HttpTransportBase::AUTH_PARAMS_RUN.
+      AUTH_PARAMS_RUN = /\A(?:[\s,]*#{AUTH_PARAM})*/
+
       # @!attribute [rw] redirect_uri
       #   @return [String] OAuth redirect URI
       # @!attribute [rw] scope
@@ -21,8 +33,10 @@ module MCPClient
       #   @return [Object] Storage backend for tokens and client info
       # @!attribute [r] server_url
       #   @return [String] The MCP server URL (normalized)
+      # @!attribute [r] client_id_metadata_url
+      #   @return [String, nil] HTTPS URL of this client's Client ID Metadata Document (SEP-991)
       attr_accessor :redirect_uri, :scope, :logger, :storage
-      attr_reader :server_url
+      attr_reader :server_url, :client_id_metadata_url
 
       # Initialize OAuth provider
       # @param server_url [String] The MCP server URL (used as OAuth resource parameter)
@@ -32,19 +46,28 @@ module MCPClient
       # @param storage [Object, nil] Storage backend for tokens and client info
       # @param client_metadata [Hash] Extra OIDC client metadata fields for DCR registration.
       #   Supported keys: :client_name, :client_uri, :logo_uri, :tos_uri, :policy_uri, :contacts
+      # @param client_id_metadata_url [String, nil] HTTPS URL identifying this client per
+      #   MCP 2025-11-25 Client ID Metadata Documents (SEP-991). The URL doubles as the OAuth
+      #   client_id when the authorization server advertises client_id_metadata_document_supported,
+      #   skipping dynamic registration. Hosting the metadata JSON at that URL is the
+      #   application's responsibility.
+      # @raise [ArgumentError] if client_id_metadata_url is not an HTTPS URL with a path component
       def initialize(server_url:, redirect_uri: 'http://localhost:8080/callback', scope: nil, logger: nil, storage: nil,
-                     client_metadata: {})
+                     client_metadata: {}, client_id_metadata_url: nil)
         self.server_url = server_url
         self.redirect_uri = redirect_uri
         self.scope = scope
         self.logger = logger || Logger.new($stdout, level: Logger::WARN)
         self.storage = storage || MemoryStorage.new
+        self.client_id_metadata_url = client_id_metadata_url
         @extra_client_metadata = client_metadata
         @http_client = create_http_client
         # Protected resource metadata learned from a 401 WWW-Authenticate
         # challenge, reused by discovery so a challenge-advertised metadata URL
-        # is not re-derived (and possibly missed).
+        # is not re-derived (and possibly missed). The URL itself is retained
+        # separately so a failed fetch is retried authoritatively by discovery.
         @challenge_resource_metadata = nil
+        @challenge_metadata_url = nil
       end
 
       # @param url [String] Server URL to normalize
@@ -52,6 +75,15 @@ module MCPClient
         @server_url = normalize_server_url(url)
       end
 
+      # Set the Client ID Metadata Document URL (SEP-991), validating it per the
+      # MCP spec: the client_id URL MUST use the "https" scheme and contain a
+      # path component (e.g. https://example.com/client.json).
+      # @param url [String, nil] HTTPS URL of this client's metadata document, or nil to clear
+      # @raise [ArgumentError] if the URL is not HTTPS or lacks a path component
+      def client_id_metadata_url=(url)
+        @client_id_metadata_url = url.nil? ? nil : validate_client_id_metadata_url(url)
+      end
+
       # Get current access token (refresh if needed)
       # @return [Token, nil] Current valid access token or nil
       def access_token
@@ -146,9 +178,27 @@ module MCPClient
         www_authenticate = response.headers['WWW-Authenticate'] || response.headers['www-authenticate']
         return nil unless www_authenticate
 
+        # Challenge parameters are read from the Bearer challenge's own
+        # segment only — never from the whole (possibly multi-challenge)
+        # header — so parameters belonging to Basic or another scheme cannot
+        # drive Bearer scope selection or resource metadata discovery. A
+        # header without a Bearer challenge carries no usable Bearer params.
+        bearer_params = bearer_challenge_segment(www_authenticate)
+
+        # MCP 2025-11-25: "Clients MUST treat the scopes provided in the
+        # challenge as authoritative for satisfying the current request" —
+        # including resetting a previously challenged scope when the current
+        # challenge carries none.
+        @challenge_scope = bearer_params && extract_challenge_param(bearer_params, 'scope')
+
         url = extract_resource_metadata_url(www_authenticate)
         return nil unless url
 
+        # Remember the advertised URL even if the fetch below fails, so a
+        # later discovery retries it instead of probing well-known URIs the
+        # challenge already superseded.
+        @challenge_metadata_url = url
+
         # This URL was explicitly advertised by the 401 challenge, so a 404 is a
         # misconfiguration to surface (strict), not a speculative miss to skip.
         metadata = fetch_resource_metadata(url, strict: true)
@@ -160,27 +210,93 @@ module MCPClient
 
       # Extract the protected-resource-metadata URL from a WWW-Authenticate header.
       # Per RFC 9728 the parameter is `resource_metadata`; a legacy `resource`
-      # parameter is accepted as a fallback for older servers.
+      # parameter is accepted as a fallback for older servers. Only the Bearer
+      # challenge's own segment is consulted, so a parameter belonging to
+      # another scheme's challenge can never drive discovery.
       # @param header [String] the WWW-Authenticate header value
       # @return [String, nil] the metadata URL if present
       def extract_resource_metadata_url(header)
+        params = bearer_challenge_segment(header)
+        return nil unless params
+
         # Auth-params may include optional whitespace around '=' (RFC 7235).
         # Quoted form: resource_metadata = "https://..."
-        if (m = header.match(/resource_metadata\s*=\s*"([^"]+)"/))
+        if (m = params.match(/resource_metadata\s*=\s*"([^"]+)"/))
           return m[1]
         end
 
         # Unquoted token form: resource_metadata = https://...
-        if (m = header.match(/resource_metadata\s*=\s*([^,\s]+)/))
+        if (m = params.match(/resource_metadata\s*=\s*([^,\s]+)/))
           return m[1]
         end
 
         # Legacy fallback: resource="https://..."
-        header.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
+        params.match(/resource\s*=\s*"([^"]+)"/)&.captures&.first
+      end
+
+      # Extract the Bearer challenge's own parameter segment from a (possibly
+      # multi-challenge) WWW-Authenticate header, so params belonging to other
+      # schemes (e.g. `Basic resource_metadata="...", Bearer realm="x"`) are
+      # never attributed to the Bearer challenge. Mirrors
+      # HttpTransportBase#bearer_challenge_segment.
+      # @param header [String, nil] the WWW-Authenticate header value
+      # @return [String, nil] the Bearer challenge's parameters (possibly
+      #   empty), or nil when the header has no Bearer challenge
+      def bearer_challenge_segment(header)
+        return nil unless header
+
+        # Locate the Bearer scheme token only OUTSIDE quoted strings: a
+        # quoted value such as realm="prefix Bearer x" must not anchor the
+        # segment.
+        masked = header.gsub(/"(?:\\.|[^"\\])*"/) { |q| "\"#{' ' * (q.length - 2)}\"" }
+        match = masked.match(/(?:\A|[\s,])Bearer(?=[\s,]|\z)/i)
+        return nil unless match
+
+        header[match.end(0)..][AUTH_PARAMS_RUN]
       end
 
+      # Extract an auth-param value from a WWW-Authenticate header
+      # (quoted or unquoted form, optional whitespace around '=').
+      # @param header [String] the WWW-Authenticate header value
+      # @param name [String] the auth-param name
+      # @return [String, nil] the parameter value if present
+      def extract_challenge_param(header, name)
+        if (m = header.match(/(?:^|[\s,])#{Regexp.escape(name)}\s*=\s*"([^"]*)"/i))
+          return m[1]
+        end
+
+        header.match(/(?:^|[\s,])#{Regexp.escape(name)}\s*=\s*([^,\s]+)/i)&.captures&.first
+      end
+
+      # Scope requested by the most recent WWW-Authenticate challenge.
+      # @return [String, nil]
+      attr_reader :challenge_scope
+
       private
 
+      # Resolve the scope for authorization/registration requests using the
+      # MCP 2025-11-25 scope selection strategy: the challenge's scope
+      # parameter is authoritative; then an explicitly configured scope
+      # (:all resolves to the AS-advertised scope list); then the Protected
+      # Resource Metadata's scopes_supported; otherwise omit scope entirely.
+      # @return [String, nil]
+      def resolved_scope
+        return @challenge_scope if @challenge_scope && !@challenge_scope.empty?
+
+        if scope == :all
+          all_scopes = supported_scopes
+          return all_scopes.join(' ') unless all_scopes.empty?
+        elsif scope
+          return scope
+        end
+
+        prm = @challenge_resource_metadata || @resource_metadata
+        prm_scopes = prm&.scopes_supported
+        return prm_scopes.join(' ') if prm_scopes && !prm_scopes.empty?
+
+        nil
+      end
+
       # Normalize server URL to canonical form
       # @param url [String] Server URL
       # @return [String] Normalized URL
@@ -299,8 +415,11 @@ module MCPClient
       # @raise [MCPClient::Errors::ConnectionError] if discovery fails
       def discover_authorization_server
         # A fresh 401 challenge is authoritative and overrides any cached
-        # (possibly stale or direct-discovered) authorization server metadata.
-        cached = storage.get_server_metadata(server_url) unless @challenge_resource_metadata
+        # (possibly stale or direct-discovered) authorization server metadata —
+        # whether the challenge-advertised PRM was already fetched or only its
+        # URL is pending (e.g. the initial fetch failed and must be retried).
+        challenge_pending = @challenge_resource_metadata || @challenge_metadata_url
+        cached = storage.get_server_metadata(server_url) unless challenge_pending
         if cached
           # Validate the cached entry before use so a persisted/older cache with
           # an HTTP endpoint or without S256 is still rejected.
@@ -333,6 +452,7 @@ module MCPClient
 
         storage.set_server_metadata(server_url, server_metadata)
         @challenge_resource_metadata = nil # consumed
+        @challenge_metadata_url = nil # consumed
         server_metadata
       end
 
@@ -375,8 +495,7 @@ module MCPClient
         # once PRM IS found it is authoritative: any subsequent failure must be a
         # hard error, never a silent fallback to an authorization server the PRM
         # did not advertise.
-        resource_metadata = @challenge_resource_metadata ||
-                            fetch_first_resource_metadata(protected_resource_metadata_urls(server_url))
+        resource_metadata = challenge_or_well_known_resource_metadata
         return nil unless resource_metadata
 
         validate_resource_matches!(resource_metadata)
@@ -397,6 +516,25 @@ module MCPClient
         server_metadata
       end
 
+      # Resolve the Protected Resource Metadata for discovery.
+      #
+      # MCP 2025-11-25 MUST: use the resource metadata URL from the parsed
+      # WWW-Authenticate headers when present; otherwise fall back to the
+      # well-known URIs. A challenge-advertised URL is therefore authoritative:
+      # it is fetched strictly, and any failure (including a 404) raises rather
+      # than falling through to constructed well-known candidates the challenge
+      # superseded.
+      # @return [ResourceMetadata, nil] metadata, or nil when no PRM exists at
+      #   the speculative well-known URLs (permitting the direct-AS fallback)
+      # @raise [MCPClient::Errors::ConnectionError] if the challenge-advertised
+      #   URL cannot be fetched, or a well-known candidate exists but is invalid
+      def challenge_or_well_known_resource_metadata
+        return @challenge_resource_metadata if @challenge_resource_metadata
+        return fetch_resource_metadata(@challenge_metadata_url, strict: true) if @challenge_metadata_url
+
+        fetch_first_resource_metadata(protected_resource_metadata_urls(server_url))
+      end
+
       # Legacy/self-hosted discovery: treat the MCP server ORIGIN as its own
       # authorization server issuer.
       # @return [ServerMetadata, nil]
@@ -444,17 +582,18 @@ module MCPClient
       end
 
       # Verify the authorization server supports PKCE S256 (RFC 8414 / MCP).
-      # Refuses when S256 is explicitly not offered; warns (and proceeds, since
-      # the client always uses S256) when the field is not advertised at all.
+      # Per MCP 2025-11-25, "If code_challenge_methods_supported is absent,
+      # the authorization server does not support PKCE and MCP clients MUST
+      # refuse to proceed" — absence is a hard stop, not a warning, because
+      # proceeding would defeat the authorization-code downgrade protection.
       # @param server_metadata [ServerMetadata]
-      # @raise [MCPClient::Errors::ConnectionError] if S256 is explicitly unsupported
+      # @raise [MCPClient::Errors::ConnectionError] if PKCE S256 support cannot be verified
       def verify_pkce_support!(server_metadata)
         methods = server_metadata.code_challenge_methods_supported
         if methods.nil?
-          logger.warn(
-            'Authorization server metadata omits code_challenge_methods_supported; ' \
-            'proceeding with PKCE S256'
-          )
+          raise MCPClient::Errors::ConnectionError,
+                'Authorization server metadata omits code_challenge_methods_supported; ' \
+                'the server does not support PKCE and the client must refuse to proceed'
         elsif !methods.include?('S256')
           raise MCPClient::Errors::ConnectionError,
                 'Authorization server does not support PKCE S256 ' \
@@ -571,7 +710,11 @@ module MCPClient
         end
 
         data = JSON.parse(response.body)
-        ResourceMetadata.from_h(data)
+        metadata = ResourceMetadata.from_h(data)
+        # Retain the most recently fetched PRM so scope resolution can fall
+        # back to its scopes_supported (MCP scope selection priority 2).
+        @resource_metadata = metadata
+        metadata
       rescue JSON::ParserError => e
         raise MCPClient::Errors::ConnectionError, "Invalid resource metadata JSON: #{e.message}"
       rescue Faraday::Error => e
@@ -601,18 +744,28 @@ module MCPClient
         raise MCPClient::Errors::ConnectionError, "Network error fetching server metadata: #{e.message}"
       end
 
-      # Get or register OAuth client
+      # Get or register OAuth client, following the MCP 2025-11-25 client
+      # registration priority order: pre-registered/cached client information
+      # first, then Client ID Metadata Documents (SEP-991) when the
+      # authorization server advertises support and a metadata URL is
+      # configured, then Dynamic Client Registration as a fallback.
       # @param server_metadata [ServerMetadata] Authorization server metadata
       # @return [ClientInfo] Client information
       # @raise [MCPClient::Errors::ConnectionError] if registration fails
       def get_or_register_client(server_metadata)
-        # Try to get existing client info from storage
+        # 1. Pre-registered or previously registered client info from storage
         if (client_info = storage.get_client_info(server_url)) && !client_info.client_secret_expired?
           logger.debug("Using cached OAuth client for #{server_url}")
           return client_info
         end
 
-        # Register new client if server supports it
+        # 2. Client ID Metadata Documents (SEP-991): the HTTPS metadata URL is
+        # itself the client_id — no registration request is needed.
+        if client_id_metadata_url && server_metadata.supports_client_id_metadata_documents?
+          return client_info_from_metadata_url
+        end
+
+        # 3. Dynamic Client Registration (RFC 7591) fallback
         logger.debug('No cached client found, registering new OAuth client...')
         if server_metadata.supports_registration?
           register_client(server_metadata)
@@ -622,6 +775,67 @@ module MCPClient
         end
       end
 
+      # Build client information for a Client ID Metadata Document client
+      # (SEP-991): the configured HTTPS metadata URL is used directly as the
+      # client_id in authorization and token requests, without a dynamic
+      # registration POST. Serving the metadata JSON at that URL is the
+      # application's responsibility, not this library's.
+      # @return [ClientInfo] Client information with the metadata URL as client_id
+      def client_info_from_metadata_url
+        logger.debug("Using Client ID Metadata Document URL as client_id: #{client_id_metadata_url}")
+
+        metadata = ClientMetadata.new(
+          redirect_uris: [redirect_uri],
+          token_endpoint_auth_method: 'none', # Public client
+          grant_types: %w[authorization_code refresh_token],
+          response_types: ['code'],
+          scope: resolved_scope,
+          **@extra_client_metadata
+        )
+
+        client_info = ClientInfo.new(client_id: client_id_metadata_url, metadata: metadata)
+
+        # Persist so complete_authorization_flow and token refresh can find it
+        storage.set_client_info(server_url, client_info)
+
+        client_info
+      end
+
+      # Validate a Client ID Metadata Document URL (SEP-991): "The client_id
+      # URL MUST use the 'https' scheme and contain a path component, e.g.
+      # https://example.com/client.json". Per the Client ID Metadata Document
+      # draft the URL must also have a host and must not contain userinfo,
+      # a fragment, or single-/double-dot path segments.
+      # @param url [String] Candidate metadata URL
+      # @return [String] The validated URL
+      # @raise [ArgumentError] if the URL is invalid, not HTTPS, lacks a host or path
+      #   component, or contains userinfo, a fragment, or dot path segments
+      def validate_client_id_metadata_url(url)
+        uri = URI.parse(url)
+        raise ArgumentError, "client_id_metadata_url must be an HTTPS URL: #{url.inspect}" unless uri.is_a?(URI::HTTPS)
+
+        raise ArgumentError, "client_id_metadata_url must include a host: #{url.inspect}" if uri.host.to_s.empty?
+
+        raise ArgumentError, "client_id_metadata_url must not contain userinfo: #{url.inspect}" if uri.userinfo
+
+        raise ArgumentError, "client_id_metadata_url must not contain a fragment: #{url.inspect}" if uri.fragment
+
+        if uri.path.to_s.empty? || uri.path == '/'
+          raise ArgumentError,
+                'client_id_metadata_url must contain a path component ' \
+                "(e.g. https://example.com/client.json): #{url.inspect}"
+        end
+
+        if uri.path.split('/').intersect?(['.', '..'])
+          raise ArgumentError,
+                "client_id_metadata_url must not contain '.' or '..' path segments: #{url.inspect}"
+        end
+
+        url
+      rescue URI::InvalidURIError
+        raise ArgumentError, "client_id_metadata_url is not a valid URL: #{url.inspect}"
+      end
+
       # Register OAuth client dynamically
       # @param server_metadata [ServerMetadata] Authorization server metadata
       # @return [ClientInfo] Registered client information
@@ -629,8 +843,6 @@ module MCPClient
       def register_client(server_metadata)
         logger.debug("Registering OAuth client at: #{server_metadata.registration_endpoint}")
 
-        resolved_scope = scope == :all ? supported_scopes.join(' ') : scope
-
         metadata = ClientMetadata.new(
           redirect_uris: [redirect_uri],
           token_endpoint_auth_method: 'none', # Public client
@@ -706,8 +918,6 @@ module MCPClient
         # Use the redirect_uri that was actually registered
         registered_redirect_uri = client_info.metadata.redirect_uris.first
 
-        resolved_scope = scope == :all ? supported_scopes.join(' ') : scope
-
         params = {
           response_type: 'code',
           client_id: client_info.client_id,