mcp 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 959e38a26541c9681c11e8bc227e84c42d20e3d98de1568c0afd45c80f3b4474
-  data.tar.gz: e2bf6b0c7926e1803f9dff1279c1f5a35d96f1cf8a1e3c6141b22a97871c8ec2
+  metadata.gz: b7ace5af244e82b2df4f3fef449fd0942d3d9be46746d820f8207cfcee87af52
+  data.tar.gz: ce4b53defad3ed24646806c2236a8d79c68597c7225fa4fcef20fd2d85031c24
 SHA512:
-  metadata.gz: 5f347a7259f4e728df5edad217d6963cb3428188e46244efd9be9908e84bf4a7134600c6f453249eedc87e33f998f3f51811922659f116811251a64d78f1bbee
-  data.tar.gz: 3d8d25f65c590d07157db74d87423bbde82250b5d99cf2e3182c8adbc198f534f96809265c8615160f49f963a3b2dc2a07a85db2f6f2cc83e11b068583f405de
+  metadata.gz: 2c2ef2a03fb1b989e691aea55d350f06b9f1f357b0acfcda4e227ca359c3a12990d06fe280ced39b1e6d620181aa9c7b8d355d5985c70d090512636da7c34f3a
+  data.tar.gz: a75f884057bc318a98943fec8967c4725c63dd767552dc52591c8e08143474f8a28907e929cdbe0efb645426766b75314449b9df8c3c86aa90bb0a68247004ff

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
@@ -230,6 +231,31 @@ server = MCP::Server.new(
 )
 ```
 
+### Capability Extensions
+
+Per SEP-2133, both clients and servers can declare protocol extensions under the `extensions` member of their capabilities.
+Keys are extension identifiers using the reverse-DNS prefix convention (e.g. `"io.modelcontextprotocol/tasks"`, `"com.example/feature"`);
+values are extension-defined configuration objects, with `{}` meaning "supported with no settings".
+
+On the server, declare extensions through the `capabilities` keyword, either as a plain hash or via the `MCP::Server::Capabilities` builder:
+
+```ruby
+capabilities = MCP::Server::Capabilities.new
+capabilities.support_tools
+capabilities.support_extensions("com.example/feature" => { enabled: true })
+
+server = MCP::Server.new(name: "my_server", capabilities: capabilities)
+```
+
+The declared extensions appear in the `initialize` result's `capabilities.extensions`. Extensions the client declared during `initialize` are
+readable via `server.client_capabilities[:extensions]` (or `session.client_capabilities[:extensions]` for per-session transports).
+
+On the client, pass extensions through `connect`:
+
+```ruby
+client.connect(capabilities: { extensions: { "com.example/feature" => {} } })
+```
+
 ### Server Context and Configuration Block Data
 
 #### `server_context`
@@ -260,6 +286,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 +331,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 +484,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:
 
@@ -513,6 +574,10 @@ end
 The server_context parameter is the server_context passed into the server and can be used to pass per request information,
 e.g. around authentication state.
 
+Tool arguments arrive as a `Hash` with symbol keys at every nesting level, because the transports parse JSON with `symbolize_names: true`.
+Read nested objects with symbol keys (`payload[:subject]`, not `payload["subject"]`).
+See [Tool argument keys](docs/building-servers.md#tool-argument-keys) for details and a testing tip.
+
 ### Tool Annotations
 
 Tools can include annotations that provide additional metadata about their behavior. The following annotations are supported:
@@ -891,6 +956,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.
@@ -1586,6 +1664,11 @@ Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`
 transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)
 ```
 
+In stateless mode, each POST is fully self-contained per SEP-2567: no `Mcp-Session-Id` is issued or required,
+handlers run against an ephemeral per-request session (so client identity never leaks across requests or onto the shared server),
+and repeated `initialize` requests are permitted. Request-scoped notifications such as progress and log messages are skipped
+(there is no stream to deliver them), while server-to-client requests (`sampling/createMessage`, `roots/list`, `elicitation/create`) raise an error.
+
 You can enable JSON response mode, where the server returns `application/json` instead of `text/event-stream`.
 Set `enable_json_response: true` in `MCP::Server::Transports::StreamableHTTPTransport.new`:
 
@@ -1912,7 +1995,13 @@ pass an `MCP::Client::OAuth::Provider` to the transport instead of a static `Aut
 - Send `Authorization: Bearer <access_token>` on every request when a token is available.
 - 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.
+- Fall back to the legacy 2025-03-26 discovery when the server publishes no Protected Resource Metadata, matching the TypeScript and Python SDKs: the MCP server's origin acts
+  as the authorization base URL, its metadata is fetched from `<origin>/.well-known/oauth-authorization-server` without the RFC 8414 issuer byte-match (which the legacy spec predates),
+  and when even that is absent the spec's default endpoints `/authorize`, `/token`, and `/register` at the origin are used with PKCE S256 assumed.
 - 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.
@@ -1952,6 +2041,8 @@ Required keyword arguments to `Provider.new`:
 
 - `client_metadata`: Hash sent to the authorization server's Dynamic Client Registration endpoint. Must include `redirect_uris`, `grant_types`, `response_types`,
   `token_endpoint_auth_method`. `redirect_uri` (below) must appear in this list, otherwise the constructor raises `Provider::UnregisteredRedirectURIError`.
+  When `application_type` is omitted, the SDK infers `"native"` or `"web"` from `redirect_uris` per SEP-837 before registering (loopback or custom-scheme URIs are native);
+  an explicit value always wins.
 - `redirect_uri`: String. Must use HTTPS or be a loopback URL (`localhost`, `127.0.0.0/8`, `::1`); other values raise `Provider::InsecureRedirectURIError`.
 - `redirect_handler`: Callable invoked with the fully-built authorization `URI`. Typically opens the user's browser.
 - `callback_handler`: Callable that returns `[code, state]` after the user is redirected back to `redirect_uri`.
@@ -2014,6 +2105,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/annotations.rb

@@ -5,6 +5,8 @@ module MCP
     attr_reader :audience, :priority, :last_modified
 
     def initialize(audience: nil, priority: nil, last_modified: nil)
+      raise ArgumentError, "The value of priority must be between 0 and 1." if priority && !priority.between?(0, 1)
+
       @audience = audience
       @priority = priority
       @last_modified = last_modified

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
@@ -227,6 +237,23 @@ module MCP
             false
           end
 
+          # Infers the OIDC Dynamic Client Registration `application_type` for a client from its `redirect_uris`.
+          # Per SEP-837, MCP clients MUST specify an appropriate application type during Dynamic Client Registration
+          # so the authorization server can apply the matching redirect URI policy.
+          #
+          # Returns `"native"` when every redirect URI is a native-app URI: a custom non-http(s) scheme (RFC 8252 Section 7.1)
+          # or an http(s) URI whose host is a loopback address (`localhost`, `127.0.0.0/8`, or `::1`, RFC 8252 Section 7.3).
+          # Returns `"web"` otherwise, including when `redirect_uris` is nil, empty, or contains an unparseable URI.
+          #
+          # - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/837
+          # - https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata
+          def infer_application_type(redirect_uris)
+            uris = Array(redirect_uris)
+            return "web" if uris.empty?
+
+            uris.all? { |uri| native_redirect_uri?(uri) } ? "native" : "web"
+          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
@@ -335,6 +362,20 @@ module MCP
             nil
           end
 
+          # A redirect URI counts as native when it uses a custom non-http(s) scheme
+          # (e.g. `com.example.app:/callback`) or when it is an http(s) URI whose host is
+          # a loopback address. A URI without a scheme or one that fails to parse is not native.
+          def native_redirect_uri?(url)
+            uri = URI.parse(url.to_s)
+            scheme = uri.scheme&.downcase
+            return false if scheme.nil?
+            return loopback_host?(uri.host) if ["http", "https"].include?(scheme)
+
+            true
+          rescue URI::InvalidURIError
+            false
+          end
+
           def base_url(uri)
             port_part = uri.port && uri.port != uri.default_port ? ":#{uri.port}" : ""
             "#{uri.scheme}://#{uri.host}#{port_part}"