mcp 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cb0f742e469efeb15202b40310bfb2eab52b94bb208bab1f33cfd2204bcf8c9
-  data.tar.gz: 07df380a1dd652b6fd5deb0ddbafe3c3379bc6fa77c8a391f169f6a7fed11742
+  metadata.gz: 87f6233cbd083a14b47183b21558ee995c06953ef5bb8d9ea568eca8e69103de
+  data.tar.gz: 11697a1b6e71297211fac5ecf411ac381a064e66274ac9c9a9640087284859ad
 SHA512:
-  metadata.gz: c756d7552fbf3accc8eedc32876e715c1d34939ed8c44d9d540a97b46ccf4cc2d3a163f5ba5989277be6e8933bce374ccab80f27ddf62ed52f6ea27c0367a3c5
-  data.tar.gz: '0873ea9933d9b30e1c0e2bcbd6f56eb0c658f16736ae309007cd752b097cb9f75ebcead7277c89ea9f255f92f3f62d2d4f1ac5d4ae87cf36359df4e42e030d38'
+  metadata.gz: ec9899cc307eb88706aded076b0e7be9bb2bdbf2fbf52c3d8f8f7a7ebe05dbb1da802ebfc8ea9bc1d5ecc18c361a2249488815c60175650203815a084aad9833
+  data.tar.gz: c43d95b541108f64ac594567e44f3de9e103f4f52c2c122ef0f0d90dcaa52b391b419c536cf4653c784299324a71c23c9bb7da9a7c4f9f69db87c2ab1d730871

data/README.md

@@ -125,7 +125,7 @@ see [Client Transports](https://ruby.sdk.modelcontextprotocol.io/client/transpor
 
 ## Examples
 
-Runnable examples are available in [`examples/`](https://github.com/modelcontextprotocol/ruby-sdk/tree/main/examples),
+Runnable examples are available in [`examples`](https://github.com/modelcontextprotocol/ruby-sdk/tree/main/examples),
 including a complete Rails application in [`examples/rails`](https://github.com/modelcontextprotocol/ruby-sdk/tree/main/examples/rails).
 
 ## Documentation

data/lib/mcp/client/http.rb

@@ -902,15 +902,25 @@ module MCP
         MCP::Client::OAuth::Discovery.parse_www_authenticate(header)
       end
 
+      # A provider without a `callback_handler` finishes the authorization in the request that receives the redirect,
+      # not here, so there is nothing to retry with yet: the pending authorization surfaces as
+      # `Flow::AuthorizationPendingError`, and requests made after `Flow#finish!` pick up the stored tokens.
       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.
-        flow.run!(
+        result = flow.run!(
           server_url: @oauth_server_url,
           resource_metadata_url: params["resource_metadata"],
           scope: params["scope"],
         )
+        return unless result == :redirect
+
+        raise MCP::Client::OAuth::Flow::AuthorizationPendingError.new(
+          "Authorization is pending: the user was sent to the authorization server, and the request can be retried " \
+            "once `MCP::Client::OAuth::Flow#finish!` completes the authorization with the redirect's query.",
+          authorization_url: flow.authorization_url,
+        )
       end
 
       # Tries to swap a saved `refresh_token` for a fresh access token. Returns truthy

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ipaddr"
+require "strscan"
 require "uri"
 
 module MCP
@@ -43,6 +44,12 @@ module MCP
         # or a bare token, per RFC 7235.
         WWW_AUTH_PARAM_PATTERN = /\A([A-Za-z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,]+))/.freeze
 
+        # The whitespace and optional comma between two `key=value` pairs, or before the first one.
+        WWW_AUTH_PARAM_SEPARATOR_PATTERN = /\s*,?\s*/.freeze
+
+        # The `Bearer` challenge: at the start of the header or after a comma.
+        WWW_AUTH_BEARER_PATTERN = /(?:\A|,)\s*Bearer(?:\s+|\z)/i.freeze
+
         class << self
           # Parses a `WWW-Authenticate` header and returns the parameters of
           # the `Bearer` challenge as a hash with lower-cased keys (e.g. `resource_metadata`,
@@ -55,25 +62,21 @@ module MCP
           def parse_www_authenticate(header)
             return {} unless header
 
-            # Locate the Bearer challenge: at the start of the header or after a comma.
-            bearer = header.match(/(?:\A|,)\s*Bearer(?:\s+|\z)/i)
-            return {} unless bearer
-
             # Walk key=value pairs starting where Bearer's parameters begin.
-            # The loop stops at the first token that is not a key=value pair,
-            # which marks the next challenge (e.g. `, DPoP algs="..."`).
-            cursor = bearer.end(0)
-            params = {}
-            while cursor < header.length
-              prefix = header[cursor..]
-              prefix = prefix.sub(/\A\s*,?\s*/, "")
-              break if prefix.empty?
+            # The loop stops at the first token that is not a key=value pair, which marks the next challenge (e.g. `, DPoP algs="..."`).
+            # The scanner keeps the walk linear in the header's length: slicing off the consumed prefix instead copies the remainder
+            # for every pair, and the server chooses how many pairs it sends. The header is also the server's to fill: a byte sequence
+            # that is not valid in the string's encoding would make the patterns raise `ArgumentError`, so such bytes are replaced first.
+            scanner = StringScanner.new(header.scrub)
+            return {} unless scanner.skip_until(WWW_AUTH_BEARER_PATTERN)
 
-              match = prefix.match(WWW_AUTH_PARAM_PATTERN)
-              break unless match
+            params = {}
+            until scanner.eos?
+              scanner.skip(WWW_AUTH_PARAM_SEPARATOR_PATTERN)
+              break if scanner.eos?
+              break unless scanner.scan(WWW_AUTH_PARAM_PATTERN)
 
-              params[match[1].downcase] = match[2] ? unescape_quoted_pair(match[2]) : match[3]
-              cursor = header.length - prefix.length + match.end(0)
+              params[scanner[1].downcase] = scanner[2] ? unescape_quoted_pair(scanner[2]) : scanner[3]
             end
             params
           end
@@ -576,47 +579,46 @@ module MCP
               end.join("&")
           end
 
-          # Implements RFC 3986 Section 5.2.4 `remove_dot_segments`. Walks the input
-          # buffer one segment at a time, popping the previous output segment
-          # whenever a `..` is encountered, so that `/api/../mcp` collapses to
-          # `/mcp` and `/foo/./bar` collapses to `/foo/bar`.
+          # Implements RFC 3986 Section 5.2.4 `remove_dot_segments` over the path's segments, so that `/api/../mcp` collapses to
+          # `/mcp` and `/foo/./bar` collapses to `/foo/bar`. Each segment is visited once: the RFC's buffer rewriting,
+          # applied literally, copies the remaining input for every dot segment, and the path is the server's to choose.
+          #
+          # The output matches the RFC's algorithm for a relative path as well, including its quirk that a `..` popping
+          # the first segment leaves the result absolute (`a/../b` becomes `/b`), although `URI#path` never hands over a relative path.
+          # The rule letters below are the RFC's own: steps A through E of its loop.
           # https://www.rfc-editor.org/rfc/rfc3986#section-5.2.4
           def remove_dot_segments(path)
             return path if path.nil? || path.empty?
 
-            input = path.dup
-            output = +""
-            until input.empty?
-              if input.start_with?("../")
-                input = input[3..]
-              elsif input.start_with?("./")
-                input = input[2..]
-              elsif input.start_with?("/./")
-                input = "/#{input[3..]}"
-              elsif input == "/."
-                input = "/"
-              elsif input.start_with?("/../")
-                input = "/#{input[4..]}"
-                output = remove_last_segment(output)
-              elsif input == "/.."
-                input = "/"
-                output = remove_last_segment(output)
-              elsif input == "." || input == ".."
-                input = ""
+            absolute = path.start_with?("/")
+            segments = path.split("/", -1)
+            segments.shift if absolute
+
+            output = []
+
+            # True until a segment other than `.` or `..` is kept: a relative path's leading `./` and `../` are dropped together with
+            # the slash after them (Rule A), so the segment that follows is still the slash-less first one.
+            leading = !absolute
+            segments.each_with_index do |segment, index|
+              last = index == segments.length - 1
+
+              # Rule A, and Rule D for a path that is nothing but `.` or `..`.
+              next if leading && (segment == "." || segment == "..")
+
+              if segment == "."
+                # Rule B: `/./` disappears; a final `/.` leaves its slash behind.
+                output << "/" if last
+              elsif segment == ".."
+                # Rule C: `/../` removes the previous segment; a final `/..` leaves its slash behind.
+                output.pop
+                output << "/" if last
               else
-                segment = input.match(%r{\A/?[^/]*})[0]
-                output << segment
-                input = input[segment.length..]
+                # Rule E: the first segment of a relative path carries no slash.
+                output << (leading ? segment : "/#{segment}")
               end
+              leading = false
             end
-            output
-          end
-
-          def remove_last_segment(output)
-            idx = output.rindex("/")
-            return +"" if idx.nil?
-
-            output[0...idx]
+            output.join
           end
         end
       end

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

@@ -83,6 +83,27 @@ module MCP
         # and `MCP::Client::HTTP` treats on a failed refresh as a reason to run the interactive flow.
         class DestinationMismatchError < ArgumentError; end
 
+        # Raised by `MCP::Client::HTTP` when a provider without a `callback_handler` has sent the user to the authorization server:
+        # the request cannot be retried until the application finishes the authorization with `finish!` in the request that
+        # receives the redirect. `authorization_url` is the URL handed to `redirect_handler`; it is kept out of the message,
+        # which may reach logs, because it carries the `state` that `finish!` looks the pending authorization up by.
+        # Deliberately outside `AuthorizationError`, which `MCP::Client::HTTP` treats on a failed refresh as a reason to run
+        # the interactive flow: this is the interactive flow waiting on the user, not a failure.
+        class AuthorizationPendingError < StandardError
+          attr_reader :authorization_url
+
+          def initialize(message = nil, authorization_url: nil)
+            super(message)
+            @authorization_url = authorization_url
+          end
+        end
+
+        # A `state` the SDK generates is 43 characters; a callback carrying a much longer one is refused before storage is asked.
+        CALLBACK_STATE_MAX_LENGTH = 128
+
+        UNKNOWN_PENDING_AUTHORIZATION_MESSAGE =
+          "Authorization callback `state` matches no pending authorization; it is unknown, already used, or expired."
+
         # Faraday middleware registered on the connection `build_http_client` assembles before the customizer
         # is invoked, so with the usual `use` it sits ahead of the customizer's middleware and sees the URL exactly
         # as the flow requested it, which it records on the request environment for `RequestedOriginGuard`.
@@ -189,13 +210,20 @@ module MCP
           end
         end
 
+        # The authorization URL the last `run!` handed to `redirect_handler` before returning `:redirect`, or `nil`.
+        attr_reader :authorization_url
+
         def initialize(provider:, http_client_factory: nil)
           @provider = provider
           @http_client_factory = http_client_factory || -> { default_http_client }
+          @authorization_url = nil
         end
 
         # Runs the full discovery, registration, authorization, and token exchange flow.
         # On success, persists tokens via the provider and returns `:authorized`.
+        # A provider without a `callback_handler` stops after the redirect instead: the flow saves
+        # a pending authorization in the provider's storage, keyed by `state`, and returns `:redirect`, leaving the code
+        # exchange to `finish!` in the request that receives the redirect.
         def run!(server_url:, resource_metadata_url: nil, scope: nil)
           # The `resource_metadata` URL ships in `WWW-Authenticate` and is the very
           # first thing we contact in the OAuth flow, so it has to clear the same
@@ -257,6 +285,20 @@ module MCP
             resource: resource,
           )
 
+          if @provider.callback_handler.nil?
+            save_pending_authorization(
+              state: state,
+              code_verifier: pkce[:code_verifier],
+              server_url: server_url,
+              resource: resource,
+              client_id: client_info_required_value(client_info, "client_id"),
+              as_metadata: as_metadata,
+            )
+            @authorization_url = authorization_url
+            @provider.redirect_handler.call(authorization_url)
+            return :redirect
+          end
+
           @provider.redirect_handler.call(authorization_url)
           callback_result = Array(@provider.callback_handler.call)
           code, returned_state, returned_iss = callback_result
@@ -449,6 +491,87 @@ module MCP
           :refreshed
         end
 
+        # Finishes an authorization that `run!` left pending, in the request that receives the redirect to `redirect_uri`,
+        # which may run in another process. `callback_params` is that redirect's whole query as a Hash (`code`, `state`, and,
+        # when present, `iss`, `error`, and `error_description`); passing all of it, rather than picking values out, is
+        # the caller's part of the `iss` check: an `iss` the caller drops reads as absent, and the flow cannot tell the difference.
+        #
+        # The pending authorization is looked up by `state` before any request is made, and it binds the rest of the exchange:
+        # the code is redeemed at the token endpoint recorded when the authorization began, with the client registration,
+        # `resource`, and `redirect_uri` used then, and without discovery running again, so the code reaches the authorization
+        # server the user was sent to (SEP-2352). The RFC 9207 `iss` is validated against the recorded issuer before the pending
+        # authorization is consumed, so a callback from another authorization server, as in a mix-up, is refused without
+        # consuming the entry the legitimate callback needs, and before the callback's `error` is read, since in a mix-up
+        # those parameters are the other server's. The check establishes only that a present `iss` matches the recorded issuer,
+        # not who sent the callback, and a callback without `iss` passes it unless the metadata advertises
+        # `authorization_response_iss_parameter_supported`: whoever holds the `state`, passes that check, and reaches
+        # the consume first takes the entry, and the legitimate callback then finds nothing.
+        #
+        # Past that check the pending authorization is consumed with `delete_pending_authorization`, which returns the entry
+        # it removed; only a callback that gets the entry back redeems the code, so of callbacks racing on the same `state`
+        # (a retried redirect, say), at most one does.
+        #
+        # Binding the callback to the user who started the authorization stays with the application: scoping `storage`
+        # to that user means a callback delivered to another user's session finds no pending authorization.
+        #
+        # On success, persists tokens via the provider and returns `:authorized`.
+        def finish!(server_url:, callback_params:)
+          unless provider_authorization_flow == :authorization_code && @provider.callback_handler.nil?
+            raise ArgumentError,
+              "finish! completes an authorization started by a provider without a callback_handler; " \
+                "this provider finishes its authorizations in `run!`."
+          end
+
+          state = callback_param(callback_params, "state")
+          raise AuthorizationError, "Authorization callback carried no `state`." unless state
+
+          pending = @provider.pending_authorization(state) if state.bytesize <= CALLBACK_STATE_MAX_LENGTH
+          raise AuthorizationError, UNKNOWN_PENDING_AUTHORIZATION_MESSAGE unless valid_pending_authorization?(pending)
+
+          if pending_authorization_expired?(pending)
+            @provider.delete_pending_authorization(state)
+            raise AuthorizationError, "The pending authorization has expired; start a new authorization."
+          end
+
+          unless safe_canonicalize_url(server_url, label: "MCP server URL") == pending["server_url"]
+            raise AuthorizationError, "The pending authorization was started for a different MCP server."
+          end
+
+          as_metadata = pending["authorization_server_metadata"]
+          # Checked when the authorization began, and checked again because the metadata has since made a round trip
+          # through the application's storage.
+          ensure_secure_endpoints!(as_metadata, server_url: pending["server_url"])
+
+          validate_authorization_response_issuer!(
+            as_metadata: as_metadata,
+            iss: callback_param(callback_params, "iss"),
+            iss_provided: true,
+          )
+
+          # The read above and this delete are separate calls, so the storage's atomic delete is what decides
+          # which of two concurrent callbacks carrying this `state` proceeds.
+          consumed = @provider.delete_pending_authorization(state)
+          raise AuthorizationError, UNKNOWN_PENDING_AUTHORIZATION_MESSAGE unless valid_pending_authorization?(consumed)
+
+          error = callback_param(callback_params, "error")
+          raise authorization_response_error(error, callback_param(callback_params, "error_description")) if error
+
+          code = callback_param(callback_params, "code")
+          raise AuthorizationError, "Authorization callback carried no authorization code." unless code
+
+          tokens = exchange_authorization_code(
+            as_metadata: as_metadata,
+            client_info: pending_client_information(pending, as_metadata: as_metadata),
+            code: code,
+            code_verifier: pending["code_verifier"],
+            resource: pending["resource"],
+            redirect_uri: pending["redirect_uri"],
+          )
+
+          save_tokens_issued_by(tokens, as_metadata: as_metadata)
+          :authorized
+        end
+
         private
 
         def read_token(key)
@@ -1096,6 +1219,89 @@ module MCP
           result.zero?
         end
 
+        def provider_pending_authorization_max_age
+          return Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE unless @provider.respond_to?(:pending_authorization_max_age)
+
+          @provider.pending_authorization_max_age
+        end
+
+        # Records what `finish!` needs to redeem the code exactly as this authorization began: the PKCE verifier, the MCP server,
+        # the `resource` and `redirect_uri` sent, the client identity used, and the authorization server metadata already validated.
+        # The client secret is not copied: `finish!` reads the registration from storage and requires the same `client_id`.
+        # Every value is JSON-compatible, so storage can serialize the entry as-is.
+        def save_pending_authorization(state:, code_verifier:, server_url:, resource:, client_id:, as_metadata:)
+          @provider.save_pending_authorization(
+            state,
+            {
+              "code_verifier" => code_verifier,
+              "server_url" => safe_canonicalize_url(server_url, label: "MCP server URL"),
+              "resource" => resource,
+              "redirect_uri" => @provider.redirect_uri,
+              "client_id" => client_id,
+              "authorization_server_metadata" => as_metadata,
+              "created_at" => Time.now.to_i,
+            },
+          )
+        end
+
+        def valid_pending_authorization?(pending)
+          return false unless pending.is_a?(Hash)
+          return false unless ["code_verifier", "server_url", "redirect_uri", "client_id"].all? { |key| non_empty_string?(pending[key]) }
+          return false unless pending["resource"].nil? || non_empty_string?(pending["resource"])
+
+          pending["authorization_server_metadata"].is_a?(Hash) && pending["created_at"].is_a?(Integer)
+        end
+
+        def pending_authorization_expired?(pending)
+          Time.now.to_i - pending["created_at"] > provider_pending_authorization_max_age
+        end
+
+        # The registration the authorization began with. A stored registration is used only while it still carries
+        # that `client_id` and is bound to the recorded authorization server; a Client ID Metadata Document URL,
+        # which is never stored, is used again while the recorded metadata advertises support for it.
+        def pending_client_information(pending, as_metadata:)
+          client_id = pending["client_id"]
+
+          stored = @provider.client_information
+          if stored.is_a?(Hash) &&
+              client_info_required_value(stored, "client_id") == client_id &&
+              client_info_required_value(stored, "issuer") == as_metadata["issuer"]
+            return stored
+          end
+
+          if client_id == provider_client_id_metadata_document_url && as_metadata["client_id_metadata_document_supported"] == true
+            return { "client_id" => client_id }
+          end
+
+          raise AuthorizationError, "The client registration changed after the authorization began; start a new authorization."
+        end
+
+        # Reads one parameter of an authorization response. Only a non-empty String counts: a repeated parameter that
+        # a framework delivers as an Array, or an empty value, is treated as absent.
+        def callback_param(params, key)
+          return unless params.is_a?(Hash)
+
+          value = params[key] || params[key.to_sym]
+          non_empty_string?(value) ? value : nil
+        end
+
+        def non_empty_string?(value)
+          value.is_a?(String) && !value.empty?
+        end
+
+        # An RFC 6749 Section 4.1.2.1 error response, reported with the bounds a token endpoint error gets.
+        # Reached only after the `iss` check, so any `iss` beside the values matched the recorded issuer; that does not
+        # prove who sent them, and they are text the sender chose, so they are cut to a bounded length and confined to
+        # the printable ASCII the RFC permits.
+        def authorization_response_error(error, description)
+          error = bounded_diagnostic(error, limit: TOKEN_ENDPOINT_ERROR_MAX_LENGTH)
+          description = bounded_diagnostic(description, limit: TOKEN_ENDPOINT_ERROR_DESCRIPTION_MAX_LENGTH)
+          message = "The authorization server returned an error to the authorization callback."
+          message += " #{[error, description].compact.join(": ")}" if error || description
+
+          AuthorizationError.new(message, error: error, error_description: description)
+        end
+
         # Per MCP 2025-11-25 Authorization and the TS/Python SDKs, scope resolution
         # prefers the `WWW-Authenticate` challenge first, then `scopes_supported`
         # from the Protected Resource Metadata, and falls back to a provider-supplied
@@ -1206,24 +1412,38 @@ module MCP
               "Authorization server metadata `authorization_endpoint` is not a valid URI: #{e.message}."
           end
 
-          params = URI.decode_www_form(uri.query.to_s)
-          params << ["response_type", "code"]
-          params << ["client_id", client_id]
-          params << ["redirect_uri", @provider.redirect_uri]
-          params << ["code_challenge", code_challenge]
-          params << ["code_challenge_method", "S256"]
-          params << ["state", state]
-          params << ["scope", scope] if scope
-          params << ["resource", resource] if resource
-          uri.query = URI.encode_www_form(params)
+          # A parameter the flow sets replaces any of the same name the endpoint URL already carries.
+          # RFC 6749 Section 3.1 forbids sending a parameter twice, and which of two values a server would honor is
+          # its own choice; on the legacy path the endpoint URL is served by the MCP server, whose query must not speak
+          # for the client's `client_id`, `redirect_uri`, `code_challenge`, or `resource`.
+          # Other parameters in the URL are kept, as the TypeScript SDK's `searchParams.set` keeps them; that includes
+          # a `scope` when the flow has none, since an authorization server may set a default scope there.
+          # RFC 9101 `request` and `request_uri` are dropped as well, though the flow sets neither: a server takes
+          # the whole authorization request from the object they carry, over every parameter in the query, and both are
+          # the client's to send, never an endpoint URL's to supply.
+          own_params = [
+            ["response_type", "code"],
+            ["client_id", client_id],
+            ["redirect_uri", @provider.redirect_uri],
+            ["code_challenge", code_challenge],
+            ["code_challenge_method", "S256"],
+            ["state", state],
+          ]
+          own_params << ["scope", scope] if scope
+          own_params << ["resource", resource] if resource
+          dropped_names = own_params.map(&:first) + ["request", "request_uri"]
+
+          params = URI.decode_www_form(uri.query.to_s).reject { |name, _value| dropped_names.include?(name) }
+          uri.query = URI.encode_www_form(params + own_params)
+
           uri
         end
 
-        def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:)
+        def exchange_authorization_code(as_metadata:, client_info:, code:, code_verifier:, resource:, redirect_uri: @provider.redirect_uri)
           form = {
             "grant_type" => "authorization_code",
             "code" => code,
-            "redirect_uri" => @provider.redirect_uri,
+            "redirect_uri" => redirect_uri,
             "code_verifier" => code_verifier,
           }
           form["resource"] = resource if resource

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

@@ -16,6 +16,17 @@ module MCP
       #   binding the credentials to the authorization server that issued them (SEP-2352);
       #   custom storages should treat the hash as opaque and persist it as-is.
       #
+      # A provider without a `callback_handler` also keeps each pending authorization here, keyed by its `state`,
+      # between the request that sends the user to the authorization server and the request that receives
+      # the redirect (`save_pending_authorization(state, pending)`, `pending_authorization(state)`,
+      # `delete_pending_authorization(state)`). A pending authorization holds the PKCE verifier, so custom storages
+      # should treat it as a secret and persist it as-is. `Flow#finish!` touches only the entry its callback's `state`
+      # names, so an authorization the user never finished stays until the storage drops it: this class drops entries
+      # older than `pending_authorization_max_age` the next time one is saved, and a custom storage should expire them,
+      # with a TTL of that age. `delete_pending_authorization` must remove the entry and return it in one atomic step
+      # (`Hash#delete` under a mutex here; `GETDEL` in Redis, `DELETE ... RETURNING` in SQL), returning `nil` when
+      # there was none: the flow redeems the code only when it gets the entry back.
+      #
       # This class keeps everything in process memory, so the credentials live
       # only for the lifetime of the Ruby process. Applications that need
       # persistence across restarts should supply a custom object responding to
@@ -24,12 +35,25 @@ module MCP
       # `Provider.new(storage: ...)`. The shape mirrors Python SDK's
       # `TokenStorage` Protocol; TypeScript's `OAuthClientProvider` rolls
       # the same responsibilities into a single object.
+      # A web application may receive the redirect in another process, so pending authorizations
+      # need shared storage.
       class InMemoryStorage
         attr_accessor :tokens, :client_information
 
-        def initialize
+        # @param pending_authorization_max_age [Integer] seconds after which a pending authorization that was
+        #   never finished is dropped from this storage, at its next save. `Provider.new` passes its own
+        #   `pending_authorization_max_age` when it builds the default storage, so the two ages agree; a storage built
+        #   by hand defaults to `Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE`.
+        def initialize(pending_authorization_max_age: Provider::DEFAULT_PENDING_AUTHORIZATION_MAX_AGE)
+          unless pending_authorization_max_age.is_a?(Integer) && pending_authorization_max_age.positive?
+            raise ArgumentError, "pending_authorization_max_age must be a positive Integer number of seconds (got #{pending_authorization_max_age.inspect})."
+          end
+
           @tokens = nil
           @client_information = nil
+          @pending_authorizations = {}
+          @pending_authorization_max_age = pending_authorization_max_age
+          @pending_authorizations_mutex = Mutex.new
         end
 
         def save_tokens(tokens)
@@ -39,6 +63,55 @@ module MCP
         def save_client_information(info)
           @client_information = info
         end
+
+        # Drops every pending authorization older than `pending_authorization_max_age` before saving the new one.
+        # The flow refuses such an entry when it is looked up, but only a callback carrying its `state` looks it up,
+        # and an authorization the user abandoned never gets one; every `401` a provider without a `callback_handler` meets
+        # starts another, so without this the entries, each holding the verifier and the authorization server metadata,
+        # would accumulate for the life of the process.
+        def save_pending_authorization(state, pending)
+          @pending_authorizations_mutex.synchronize do
+            drop_expired_pending_authorizations
+            @pending_authorizations[state] = pending
+          end
+        end
+
+        def pending_authorization(state)
+          @pending_authorizations_mutex.synchronize { @pending_authorizations[state] }
+        end
+
+        # The mutex is what makes the removal and the return one step on every Ruby implementation: `Hash#delete`
+        # alone is atomic only where a global interpreter lock serializes it, and `Flow#finish!` relies on exactly
+        # one of two callbacks racing on the same `state` getting the entry back.
+        def delete_pending_authorization(state)
+          @pending_authorizations_mutex.synchronize { @pending_authorizations.delete(state) }
+        end
+
+        # Every hash this storage holds may carry a secret (an access token, a client secret, a PKCE verifier),
+        # and `inspect` is what error reporters and consoles print an object with, so it shows only whether each is present.
+        def inspect
+          pending_count = @pending_authorizations_mutex.synchronize { @pending_authorizations.size }
+
+          "#<#{self.class.name} tokens=#{present_or_nil(@tokens)} client_information=#{present_or_nil(@client_information)} pending_authorizations=#{pending_count}>"
+        end
+
+        private
+
+        # An entry's age is read from the Integer `created_at` the flow records when it saves the entry; an entry without one,
+        # which the flow never writes, is left alone.
+        def drop_expired_pending_authorizations
+          now = Time.now.to_i
+
+          @pending_authorizations.delete_if do |_state, pending|
+            created_at = pending.is_a?(Hash) ? pending["created_at"] : nil
+
+            created_at.is_a?(Integer) && now - created_at > @pending_authorization_max_age
+          end
+        end
+
+        def present_or_nil(value)
+          value.nil? ? "nil" : "[present]"
+        end
       end
     end
   end