mcp 1.7.0 → 1.8.0

data/lib/mcp/server/oauth/jwt_verifier.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "mcp/client/oauth/discovery"
+require_relative "token_verifier"
+
+# This file is autoloaded only when `JWTVerifier` is referenced, so the `jwt` dependency does not affect users of other verifiers.
+begin
+  require "jwt"
+rescue LoadError
+  raise LoadError, "The 'jwt' gem is required to use MCP::Server::OAuth::JWTVerifier. Add it to your Gemfile: gem 'jwt'"
+end
+
+module MCP
+  class Server
+    module OAuth
+      # Verifies JWT access tokens locally: signature (via a JWKS endpoint, a static JWKS document, or a single key), `iss`, `aud`, `exp`, and `nbf`.
+      #
+      #
+      #   verifier = MCP::Server::OAuth::JWTVerifier.new(
+      #     resource_metadata: metadata, # the ProtectedResourceMetadata this server publishes
+      #     jwks_uri: "https://as.example.com/.well-known/jwks.json",
+      #   )
+      #
+      # `aud` is checked against the document's `resource`, the canonical resource URL spec-conformant authorization servers
+      # put into `aud` via the RFC 8707 `resource` parameter, and `iss` against the document's authorization server, of which
+      # there must be exactly one: this verifier holds one key set, so it verifies the tokens of one issuer.
+      #
+      # `alg: none` is refused whatever `algorithms:` says, and HMAC and asymmetric algorithms cannot share one allowlist, which defeats HS256 key-confusion attacks:
+      # a token symmetrically signed with the public key bytes never meets an HMAC verifier holding that key. The default allowlist contains only asymmetric algorithms.
+      # Pass `algorithms: ["HS256"]` together with `key: shared_secret` only when the authorization server genuinely issues HMAC-signed tokens, and understand
+      # that anyone holding the secret can mint tokens.
+      class JWTVerifier < TokenVerifier
+        # Raised when the JWKS endpoint cannot be fetched or parsed. Deliberately not an `OAuth::Error`:
+        # an unreachable key set is an internal failure (HTTP 500), not a problem with the client's token.
+        class JWKSFetchError < StandardError; end
+
+        DEFAULT_ALGORITHMS = ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"].freeze
+
+        HMAC_ALGORITHM_PATTERN = /\AHS\d+\z/i.freeze
+        private_constant :HMAC_ALGORITHM_PATTERN
+
+        # Minimum seconds between JWKS refetches triggered by an unknown `kid`, so a stream of forged tokens cannot hammer the JWKS endpoint.
+        JWKS_REFETCH_COOLDOWN = 30
+
+        # The RFC 7519 NumericDate claims the jwt gem compares with the clock under the `verify_expiration` and
+        # `verify_not_before` options passed in `decode`; `iat` joins the list only if its verification is ever enabled.
+        NUMERIC_DATE_CLAIMS = ["exp", "nbf"].freeze
+        private_constant :NUMERIC_DATE_CLAIMS
+
+        def initialize(resource_metadata:, jwks_uri: nil, jwks: nil, key: nil, algorithms: DEFAULT_ALGORITHMS, leeway: 0, jwks_cache_ttl: 300, jwks_max_stale: 3600, open_timeout: 5, read_timeout: 5)
+          super()
+
+          issuer = issuer_from(resource_metadata)
+          audience = resource_from(resource_metadata)
+          require_expected_claim!(:issuer, issuer)
+          require_expected_claim!(:audience, audience)
+          require_non_negative_number!(:leeway, leeway)
+          require_non_negative_number!(:jwks_cache_ttl, jwks_cache_ttl)
+          require_non_negative_number!(:jwks_max_stale, jwks_max_stale)
+          require_positive_number!(:open_timeout, open_timeout)
+          require_positive_number!(:read_timeout, read_timeout)
+
+          key_sources = [jwks_uri, jwks, key].compact
+          raise ArgumentError, "exactly one of jwks_uri, jwks, or key is required" unless key_sources.size == 1
+
+          if jwks_uri && !Client::OAuth::Discovery.secure_url?(jwks_uri)
+            raise ArgumentError, "jwks_uri must use https (http is allowed only on loopback): #{jwks_uri.inspect}"
+          end
+
+          @issuer = issuer
+          @audience = audience
+          @jwks_uri = jwks_uri
+          @static_jwks = jwks && deep_symbolize(jwks)
+          @key = key
+          @algorithms = validate_algorithms!(algorithms, key)
+          @leeway = leeway
+          @jwks_cache_ttl = jwks_cache_ttl
+          @jwks_max_stale = jwks_max_stale
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
+          @cached_jwks = nil
+          @jwks_fetched_at = nil
+          @kid_refetch_at = nil
+          @refetch_failed_at = nil
+          @state_mutex = Mutex.new
+          @fetch_mutex = Mutex.new
+        end
+
+        def verify(token)
+          validate_time_claims!(token)
+          claims, _header = decode(token)
+
+          access_token_from_claims(token, claims, resource: @audience)
+        rescue JWT::ExpiredSignature
+          raise InvalidTokenError, "Token expired"
+        rescue JWT::ImmatureSignature
+          raise InvalidTokenError, "Token not yet valid"
+        rescue JWT::InvalidIssuerError
+          raise InvalidTokenError, "Invalid issuer"
+        rescue JWT::InvalidAudError
+          raise InvalidTokenError, "Invalid audience"
+        rescue JWT::DecodeError
+          # Covers malformed tokens, signature mismatches, disallowed algorithms (including `alg: none`), missing required claims,
+          # and unknown key IDs. The generic message is deliberate: it goes into the `WWW-Authenticate` header, and detailing why
+          # verification failed would only help an attacker probe.
+          raise InvalidTokenError, "Invalid token"
+        end
+
+        private
+
+        def decode(token)
+          options = {
+            algorithms: @algorithms,
+            iss: @issuer,
+            verify_iss: true,
+            aud: @audience,
+            verify_aud: true,
+            verify_expiration: true,
+            verify_not_before: true,
+            # `verify_expiration` alone lets a token without `exp` through, and a token that never expires cannot be aged out.
+            # Spec-conformant access tokens always carry `exp` (RFC 9068 requires it).
+            required_claims: ["exp"],
+            leeway: @leeway,
+          }
+
+          if @key
+            JWT.decode(token, @key, true, options)
+          elsif @static_jwks
+            JWT.decode(token, nil, true, options.merge(jwks: @static_jwks))
+          else
+            JWT.decode(token, nil, true, options.merge(jwks: jwk_loader))
+          end
+        end
+
+        # The jwt gem calls `to_i` on `exp` and `nbf` while verifying, so a claim of the wrong type raises inside the gem
+        # instead of failing the token. The unverified payload is inspected first: a claim that is neither a finite number
+        # nor a digit string makes the token invalid, the same answer `expiry_from_claims` gives an introspection response.
+        def validate_time_claims!(token)
+          payload, = JWT.decode(token, nil, false)
+          raise InvalidTokenError, "Invalid token" unless payload.is_a?(Hash)
+
+          NUMERIC_DATE_CLAIMS.each do |name|
+            value = payload[name]
+            next if value.nil? || (value.is_a?(Numeric) && value.finite?) || (value.is_a?(String) && value.match?(/\A\d+\z/))
+
+            raise InvalidTokenError, "Malformed #{name} claim"
+          end
+        end
+
+        # `none` is never acceptable, and HMAC must not share an allowlist with asymmetric algorithms: an attacker who picks `alg`
+        # would otherwise sign with the public key bytes as the HMAC secret. A String key can only be an HMAC secret,
+        # so it is refused for asymmetric algorithms at construction rather than failing every verification later, and a `JWT::JWK`
+        # is refused outright because the decode path would reject every token signed by it.
+        def validate_algorithms!(algorithms, key)
+          if key.is_a?(JWT::JWK::KeyBase)
+            raise ArgumentError, "key must be an OpenSSL::PKey or an HMAC secret String; pass a JWK through jwks: { keys: [jwk.export] }"
+          end
+
+          list = Array(algorithms).map(&:to_s)
+          raise ArgumentError, "algorithms must name at least one signature algorithm" if list.empty?
+
+          if list.any? { |algorithm| algorithm.casecmp?("none") }
+            raise ArgumentError, "algorithms must not include none: unsigned tokens would be accepted"
+          end
+
+          hmac, asymmetric = list.partition { |algorithm| algorithm.match?(HMAC_ALGORITHM_PATTERN) }
+
+          if hmac.any? && asymmetric.any?
+            raise ArgumentError, "algorithms must not mix HMAC (#{hmac.join(", ")}) with asymmetric algorithms (#{asymmetric.join(", ")})"
+          end
+          if key.is_a?(String) && hmac.empty?
+            raise ArgumentError, "key must be an OpenSSL::PKey for asymmetric algorithms; a String key is an HMAC secret and needs an HS* allowlist"
+          end
+
+          list
+        end
+
+        # Loader for the `jwt` gem's `jwks:` option. The gem invokes it once per decode and again with `kid_not_found: true` when
+        # the token's `kid` is not in the returned set, which is the signal that the authorization server may have rotated its keys.
+        def jwk_loader
+          lambda do |options|
+            load_jwks(options)
+          end
+        end
+
+        # Refreshes the JWKS cache without performing network I/O under a lock other verifications wait on: only cache-state reads
+        # and swaps are synchronized, one thread fetches at a time, and the remaining threads keep verifying against the previous key
+        # set in the meantime. A failed refresh also falls back to that set, so a flaky JWKS endpoint degrades to slightly stale keys
+        # instead of taking verification down, but only for `jwks_max_stale` seconds past the TTL: beyond that the failure surfaces,
+        # so a key set the authorization server retired cannot stay trusted indefinitely. A failed unknown-`kid` refetch starts
+        # the cooldown all the same, or the endpoint would be retried on every such token while it is down.
+        def load_jwks(options)
+          # The key set and its fetch time are read as one snapshot and judged together: a refresh another thread completes
+          # in the meantime must not lend its fetch time to the set this thread is holding.
+          cached, fetched_at, refetch = @state_mutex.synchronize { [@cached_jwks, @jwks_fetched_at, refetch_required?(options)] }
+          unless refetch
+            # A refresh that failed moments ago is not retried yet, and keys past the stale bound are not served meanwhile.
+            raise JWKSFetchError, "JWKS endpoint could not be fetched" if cached && stale_beyond_bound?(fetched_at)
+
+            return cached
+          end
+
+          if @fetch_mutex.try_lock
+            begin
+              fresh = fetch_jwks
+              @state_mutex.synchronize do
+                @cached_jwks = fresh
+                @jwks_fetched_at = monotonic_now
+                @refetch_failed_at = nil
+                @kid_refetch_at = monotonic_now if options[:kid_not_found]
+              end
+
+              fresh
+            rescue JWKSFetchError
+              @state_mutex.synchronize do
+                @refetch_failed_at = monotonic_now
+                @kid_refetch_at = monotonic_now if options[:kid_not_found]
+              end
+              raise if cached.nil? || stale_beyond_bound?(fetched_at)
+
+              cached
+            ensure
+              @fetch_mutex.unlock
+            end
+          elsif cached && !stale_beyond_bound?(fetched_at)
+            cached
+          else
+            # Cold start, or a cached set past its stale bound, while another thread performs the fetch: wait for that fetch
+            # instead of failing the request with an empty or outdated key set. A fetch time that moved means the refresh succeeded,
+            # and its set is served the way the fetching thread serves it; an unchanged one means the refresh failed,
+            # and the set it left behind is judged by the bound.
+            @fetch_mutex.synchronize {}
+            fetched, refreshed_at = @state_mutex.synchronize { [@cached_jwks, @jwks_fetched_at] }
+            if fetched.nil? || (refreshed_at == fetched_at && stale_beyond_bound?(refreshed_at))
+              raise JWKSFetchError, "JWKS endpoint could not be fetched"
+            end
+
+            fetched
+          end
+        end
+
+        # An unknown `kid` refetches immediately (the usual key-rotation case) but at most once per cooldown window, so forged tokens with
+        # random `kid`s cannot turn every request into a JWKS fetch. Outside of a `kid` miss, the cache is refreshed only when the TTL lapses.
+        def refetch_required?(options)
+          return true if @cached_jwks.nil?
+
+          if options[:kid_not_found]
+            return @kid_refetch_at.nil? || monotonic_now - @kid_refetch_at >= JWKS_REFETCH_COOLDOWN
+          end
+
+          # A refresh that just failed is not retried on every request while the endpoint stays down.
+          return false if @refetch_failed_at && monotonic_now - @refetch_failed_at < JWKS_REFETCH_COOLDOWN
+
+          monotonic_now - @jwks_fetched_at >= @jwks_cache_ttl
+        end
+
+        # Whether a key set fetched at `fetched_at` has outlived its TTL by more than `jwks_max_stale`, the point past which
+        # a refresh failure is no longer bridged with the stale keys.
+        def stale_beyond_bound?(fetched_at)
+          monotonic_now - fetched_at > @jwks_cache_ttl + @jwks_max_stale
+        end
+
+        def fetch_jwks
+          uri = URI.parse(@jwks_uri)
+          request = Net::HTTP::Get.new(uri.request_uri, { "Accept" => "application/json" })
+          body = "".dup
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+            http.request(request) do |response|
+              unless response.is_a?(Net::HTTPOK)
+                raise JWKSFetchError, "JWKS endpoint responded with status #{response.code}"
+              end
+
+              response.read_body do |chunk|
+                body << chunk
+                if body.bytesize > MAX_UPSTREAM_RESPONSE_BYTES
+                  raise JWKSFetchError, "JWKS response exceeded #{MAX_UPSTREAM_RESPONSE_BYTES} bytes"
+                end
+              end
+            end
+          end
+
+          parsed = JSON.parse(body, symbolize_names: true)
+          raise JWKSFetchError, "JWKS endpoint returned a non-object JSON document" unless parsed.is_a?(Hash)
+
+          # A document without a `keys` array would replace a good cache with one that verifies nothing.
+          raise JWKSFetchError, "JWKS endpoint returned a document without a keys array" unless parsed[:keys].is_a?(Array)
+
+          # So would a set with a member the jwt gem cannot turn into a key: the gem refuses the whole set for a malformed member
+          # (jwt 3.3.0 and later skip a member of an unsupported type instead, see below), and unlike an unknown `kid` that refusal
+          # never triggers a refetch, so the document counts as a failed refresh instead of replacing the cache.
+          unless parsed[:keys].all? { |key| key.is_a?(Hash) }
+            raise JWKSFetchError, "JWKS endpoint returned a key that is not a JSON object"
+          end
+
+          key_set = begin
+            JWT::JWK::Set.new(parsed)
+          rescue JWT::JWKError => e
+            raise JWKSFetchError, "JWKS endpoint returned a key set that cannot be loaded: #{e.message}"
+          end
+
+          # jwt 3.3.0 and later skip a member whose key type they do not support instead of refusing the set (RFC 7517 Section 5.1),
+          # so a document whose every member is skipped loads as a set that verifies nothing; it counts as a failed refresh
+          # the same way an unloadable set does.
+          raise JWKSFetchError, "JWKS endpoint returned a key set with no loadable keys" if key_set.keys.empty?
+
+          parsed
+        rescue JSON::ParserError
+          raise JWKSFetchError, "JWKS endpoint returned invalid JSON"
+        rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, IOError, Net::HTTPBadResponse, Net::ProtocolError => e
+          # A connection-level failure is the same event as an HTTP error from the caller's point of view: the key set could not be refreshed,
+          # and `load_jwks` decides whether the cached one still bridges the gap.
+          raise JWKSFetchError, "JWKS endpoint could not be fetched: #{e.class}"
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        # The `jwt` gem's JWKS handling expects symbol keys; user-supplied static documents commonly arrive as parsed JSON with string keys.
+        def deep_symbolize(jwks)
+          JSON.parse(JSON.generate(jwks), symbolize_names: true)
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/middleware.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "authenticator"
+require_relative "challenge"
+require_relative "errors"
+
+module MCP
+  class Server
+    module OAuth
+      # Rack middleware that enforces bearer authentication for everything it wraps, per RFC 6750 and the MCP authorization specification:
+      #
+      #   use MCP::Server::OAuth::Middleware,
+      #     token_verifier: verifier,
+      #     required_scopes: ["mcp:tools"],
+      #     resource_metadata: metadata
+      #   run transport
+      #
+      # See `Authenticator` for the option semantics; this class only adapts it to the Rack middleware calling convention.
+      # The streamable HTTP transport embeds the same authenticator via its `token_verifier:` option, so use this middleware when composition
+      # at the Rack layer is preferable (for example to share one authenticator across several apps).
+      #
+      # Tokens are accepted from the `Authorization` header only, never from a query string. On success the verified `AccessToken` is stored in
+      # `env[MCP::Server::OAuth::ENV_KEY]`, where the streamable HTTP transport picks it up and exposes it to handlers as `server_context.auth_info`.
+      #
+      # Because the middleware wraps the whole app, POST, GET (SSE), and DELETE requests are protected uniformly. Mount the metadata document outside
+      # the protected scope: it is how unauthenticated clients bootstrap. When a browser-based client is involved, run the CORS middleware before
+      # this one; otherwise its preflight OPTIONS request dies here with a 401 that the browser will not let the client see.
+      class Middleware
+        def initialize(app, token_verifier:, required_scopes: [], resource_metadata: nil, resource_metadata_url: nil, scope_matcher: nil)
+          @app = app
+          @authenticator = Authenticator.new(
+            token_verifier: token_verifier,
+            required_scopes: required_scopes,
+            resource_metadata: resource_metadata,
+            resource_metadata_url: resource_metadata_url,
+            scope_matcher: scope_matcher,
+          )
+        end
+
+        def call(env)
+          begin
+            env[ENV_KEY] = @authenticator.authenticate(env)
+          rescue Error => e
+            return @authenticator.challenge_response(e)
+          rescue => e
+            # A misbehaving verifier (e.g. an unreachable JWKS or introspection endpoint) is an internal failure: report it
+            # and answer 500 without a challenge, so the client does not discard a perfectly good token.
+            MCP.configuration.exception_reporter.call(e, { middleware: self.class.name })
+
+            return [500, { "content-type" => "application/json" }, [{ error: "server_error" }.to_json]]
+          end
+
+          # Outside the rescue on purpose: only verification is this middleware's business, and a failure in the wrapped app
+          # must reach whatever handles that app's errors, as it does with the Python SDK's bearer middleware.
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/protected_resource_metadata.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "mcp/client/oauth/discovery"
+
+module MCP
+  class Server
+    module OAuth
+      # OAuth 2.0 Protected Resource Metadata (RFC 9728) for an MCP server.
+      # The MCP authorization spec requires servers to publish this document so clients can discover which authorization servers can
+      # issue tokens for the resource.
+      #
+      # - `resource` - the canonical resource identifier: the URL clients connect to, without a fragment. Clients send this back to
+      #   the authorization server as the RFC 8707 `resource` parameter.
+      # - `authorization_servers` - issuer URLs of the authorization servers that protect this resource (at least one).
+      # - `scopes_supported` - an Array of the scope strings clients may request (also the default scope hint in `WWW-Authenticate` challenges);
+      #   `offline_access` is dropped, and a result with nothing left omits the member.
+      # - `bearer_methods_supported` - defaults to `["header"]`: the SDK accepts bearer tokens only in the `Authorization` header,
+      #   never in a query string.
+      # - `extra` - additional RFC 9728 fields (e.g. `jwks_uri`, `resource_signing_alg_values_supported`, `resource_policy_uri`) merged into
+      #   the document as given; the members above cannot be overridden through it.
+      #
+      # https://www.rfc-editor.org/rfc/rfc9728
+      # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/authorization-server-discovery
+      class ProtectedResourceMetadata
+        WELL_KNOWN_PATH_PREFIX = "/.well-known/oauth-protected-resource"
+
+        DEFAULT_BEARER_METHODS_SUPPORTED = ["header"].freeze
+        private_constant :DEFAULT_BEARER_METHODS_SUPPORTED
+
+        # The members `initialize` validates. `extra` may not name them, or the merge in `to_h` would undo the validation.
+        VALIDATED_MEMBERS = ["resource", "authorization_servers", "scopes_supported", "resource_name", "resource_documentation", "bearer_methods_supported"].freeze
+        private_constant :VALIDATED_MEMBERS
+
+        attr_reader :resource, :authorization_servers, :scopes_supported, :resource_name, :resource_documentation, :bearer_methods_supported, :extra
+
+        def initialize(resource:, authorization_servers:, scopes_supported: nil, resource_name: nil, resource_documentation: nil, bearer_methods_supported: DEFAULT_BEARER_METHODS_SUPPORTED, extra: {})
+          @resource_uri = parse_resource_uri(resource)
+          @resource = resource
+
+          servers = Array(authorization_servers)
+          raise ArgumentError, "authorization_servers must contain at least one issuer URL" if servers.empty?
+
+          servers.each do |server|
+            next if Client::OAuth::Discovery.secure_url?(server)
+
+            raise ArgumentError, "authorization_servers must use https (http is allowed only on loopback): #{server.inspect}"
+          end
+
+          overridden = extra.keys.map(&:to_s) & VALIDATED_MEMBERS
+          unless overridden.empty?
+            raise ArgumentError, "extra must not override #{overridden.join(", ")}; pass them as keyword arguments so they are validated"
+          end
+
+          @authorization_servers = servers
+          @scopes_supported = advertisable_scopes(scopes_supported)
+          @resource_name = resource_name
+          @resource_documentation = resource_documentation
+          @bearer_methods_supported = bearer_methods_supported
+          @extra = extra
+        end
+
+        def to_h
+          {
+            resource: resource,
+            authorization_servers: authorization_servers,
+            scopes_supported: scopes_supported,
+            resource_name: resource_name,
+            resource_documentation: resource_documentation,
+            bearer_methods_supported: bearer_methods_supported,
+          }.compact.merge(extra)
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+
+        # The path-inserted well-known path per RFC 9728 Section 3: a resource of `https://example.com/mcp` is described at
+        # `/.well-known/oauth-protected-resource/mcp`, and a resource at the origin root is described at `/.well-known/oauth-protected-resource`.
+        # The path math intentionally matches what `MCP::Client::OAuth::Discovery.protected_resource_metadata_urls` probes.
+        def well_known_path
+          path = @resource_uri.path
+          path = "" if path == "/"
+
+          "#{WELL_KNOWN_PATH_PREFIX}#{path}"
+        end
+
+        # The absolute URL of the metadata document. Pass this to `Middleware` (or `Challenge`) as `resource_metadata_url` so 401/403 challenges point
+        # clients at the document.
+        def well_known_url
+          port = @resource_uri.port && @resource_uri.port != @resource_uri.default_port ? ":#{@resource_uri.port}" : ""
+
+          "#{@resource_uri.scheme}://#{@resource_uri.host}#{port}#{well_known_path}"
+        end
+
+        private
+
+        # The MCP authorization specification tells protected resources not to advertise `offline_access`: refresh token issuance
+        # is the authorization server's business, not a resource requirement. `Authenticator` already drops it from the `scope` parameter of
+        # a `WWW-Authenticate` challenge, so dropping it here keeps the document and the challenges saying the same thing.
+        # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+        # Nothing left to advertise drops the member from the document instead of emitting `[]`, which RFC 9728 tells servers to omit,
+        # and a non-Array is refused because a bare String would be ambiguous between one scope and a list.
+        def advertisable_scopes(scopes_supported)
+          return if scopes_supported.nil?
+          raise ArgumentError, "scopes_supported must be an Array of scope strings" unless scopes_supported.is_a?(Array)
+
+          scopes = scopes_supported.map(&:to_s) - ["offline_access"]
+
+          scopes.empty? ? nil : scopes
+        end
+
+        def parse_resource_uri(resource)
+          uri = begin
+            URI.parse(resource.to_s)
+          rescue URI::InvalidURIError
+            raise ArgumentError, "resource must be a valid URI: #{resource.inspect}"
+          end
+
+          unless ["http", "https"].include?(uri.scheme.to_s.downcase) && uri.host && !uri.host.empty?
+            raise ArgumentError, "resource must be an absolute http(s) URL: #{resource.inspect}"
+          end
+
+          if uri.fragment
+            raise ArgumentError, "resource must not contain a fragment per RFC 8707: #{resource.inspect}"
+          end
+
+          unless Client::OAuth::Discovery.secure_url?(resource.to_s)
+            raise ArgumentError, "resource must use https (http is allowed only on loopback): #{resource.inspect}"
+          end
+
+          uri
+        end
+      end
+    end
+  end
+end

data/lib/mcp/server/oauth/protected_resource_metadata_middleware.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+
+module MCP
+  class Server
+    module OAuth
+      # Rack middleware that serves a Protected Resource Metadata document (RFC 9728) at its well-known path,
+      # with the CORS headers browser-based MCP clients need, and passes every other request down the stack.
+      # The Rack shape of the Python SDK's `create_protected_resource_routes` and the TypeScript SDK's `mcpAuthMetadataRouter`.
+      #
+      # Use it at the top of the stack: the well-known path lives at the origin root, not under the MCP endpoint
+      # (`/.well-known/oauth-protected-resource/mcp` for a resource at `/mcp`), so inside a `map` block it would never see that path.
+      # The metadata is how unauthenticated clients bootstrap, so it belongs above any bearer enforcement.
+      #
+      #   metadata = MCP::Server::OAuth::ProtectedResourceMetadata.new(...)
+      #   use MCP::Server::OAuth::ProtectedResourceMetadataMiddleware, metadata
+      #   map("/mcp") { run(transport) }
+      class ProtectedResourceMetadataMiddleware
+        ALLOWED_METHODS = "GET, HEAD, OPTIONS"
+        private_constant :ALLOWED_METHODS
+
+        # @param app [#call] the rest of the Rack stack
+        # @param metadata [ProtectedResourceMetadata] the document to serve, which also names the path it is served at
+        def initialize(app, metadata)
+          # The document is published as `to_json`, so only the class whose serialization is a validated RFC 9728 document will do.
+          unless metadata.is_a?(ProtectedResourceMetadata)
+            raise ArgumentError, "metadata must be a ProtectedResourceMetadata (got #{metadata.class})"
+          end
+
+          @app = app
+          @well_known_path = metadata.well_known_path
+          @metadata_json = metadata.to_json
+        end
+
+        def call(env)
+          # An exact match only: a deeper well-known path describes another resource on this host (RFC 9728),
+          # and every other path is the application's.
+          return @app.call(env) unless env["PATH_INFO"] == @well_known_path
+
+          case env["REQUEST_METHOD"]
+          when "GET"
+            metadata_response
+          when "HEAD"
+            metadata_response(head: true)
+          when "OPTIONS"
+            preflight_response
+          else
+            method_not_allowed_response
+          end
+        end
+
+        private
+
+        def metadata_response(head: false)
+          headers = {
+            "content-type" => "application/json",
+            "cache-control" => "public, max-age=3600",
+            "access-control-allow-origin" => "*",
+          }
+
+          [200, headers, head ? [] : [@metadata_json]]
+        end
+
+        def preflight_response
+          headers = {
+            "access-control-allow-origin" => "*",
+            "access-control-allow-methods" => ALLOWED_METHODS,
+            "access-control-allow-headers" => "*",
+          }
+
+          [204, headers, []]
+        end
+
+        def method_not_allowed_response
+          headers = {
+            "content-type" => "application/json",
+            "allow" => ALLOWED_METHODS,
+          }
+
+          [405, headers, [{ error: "method_not_allowed" }.to_json]]
+        end
+      end
+    end
+  end
+end