ruby_llm 2.1.0 → 2.2.0

data/lib/ruby_llm/mcp/input_request.rb

@@ -2,117 +2,8 @@
 
 module RubyLLM
   class MCP
-    # A server's request for input from the user while it works on a call,
-    # received by MCP.before_input_request callbacks. A form request asks
-    # for values; a URL request asks the user to visit a page, such as to
-    # connect an account.
-    #
-    #   before_input_request do |request|
-    #     if request.url?
-    #       system "open", request.url
-    #       request.answer
-    #     else
-    #       request.answer(environment: "staging")
-    #     end
-    #   end
-    #
-    # In a chat, a request no callback answers pauses the tool call until
-    # Chat#answer or Chat#decline settles it; see Chat#pending_inputs.
-    class InputRequest
-      include Support::Inspectable
-
-      # A value a form request asks for.
-      Field = Struct.new(:name, :type, :title, :description, :required, :choices, :default, keyword_init: true) do
-        # Returns whether the server needs this value.
-        def required?
-          required == true
-        end
-      end
-
-      # Why the server needs the input.
-      attr_reader :message
-
-      # The page a URL request asks the user to visit, or +nil+.
-      attr_reader :url
-
-      # The values a form request asks for, as Field objects.
-      attr_reader :fields
-
-      attr_reader :key, :response # :nodoc:
-
-      # The ToolCall paused on this request, when it came from a chat.
-      attr_reader :tool_call
-
-      def self.from_h(data, tool_call: nil) # :nodoc:
-        new(data['key'], data['params'], response: data['response'], tool_call:)
-      end
-
-      def initialize(key, params, response: nil, tool_call: nil) # :nodoc:
-        @key = key
-        @params = params
-        @response = response
-        @tool_call = tool_call
-        @message = params['message']
-        @url = params['url'] if params['mode'] == 'url'
-        @fields = fields_from(params['requestedSchema'] || {})
-      end
-
-      # Returns whether the server asks the user to visit #url.
-      def url?
-        !url.nil?
-      end
-
-      # Returns whether the server asks for #fields.
-      def form?
-        !url?
-      end
-
-      # Accepts the request. A form request takes the values as keywords,
-      # and the fields you leave out take the defaults the server gave
-      # them; a URL request takes none, meaning the user agreed to visit
-      # the page.
-      def answer(**values)
-        @response = { action: 'accept', content: (with_defaults(values) unless url?) }.compact
-      end
-
-      # Declines the request.
-      def decline
-        @response = { action: 'decline' }
-      end
-
-      # Returns whether the request has been answered or declined.
-      def answered?
-        !response.nil?
-      end
-
-      def to_h # :nodoc:
-        { 'key' => key, 'params' => @params, 'response' => response&.transform_keys(&:to_s) }.compact
-      end
-
-      private
-
-      def with_defaults(values)
-        fields.reject { |field| field.default.nil? }.to_h { |field| [field.name, field.default] }
-              .merge(values).transform_keys(&:to_s)
-      end
-
-      def fields_from(schema)
-        required = Array(schema['required'])
-        schema.fetch('properties', {}).map do |name, property|
-          Field.new(name: name.to_sym, type: property['type'], title: property['title'],
-                    description: property['description'], required: required.include?(name),
-                    choices: choices(property), default: property['default'])
-        end
-      end
-
-      def choices(property)
-        options = property['enum'] || Array(property['oneOf'] || property.dig('items', 'anyOf')).map { |o| o['const'] }
-        options unless options.empty?
-      end
-
-      def inspect_attributes
-        { message:, url:, fields: fields.map(&:name) }
-      end
-    end
+    # A server's question to the person, the same Question a tool asks
+    # with Tool#ask, under its 2.1 name.
+    InputRequest = RubyLLM::Question
   end
 end

data/lib/ruby_llm/mcp/input_required_error.rb

@@ -3,27 +3,9 @@
 module RubyLLM
   class MCP
     # Raised when a server needs input from the user and no
-    # MCP.before_input_request callback answered. Its message includes what
-    # the server asked for, and #requests has the MCP::InputRequest objects.
-    # In a chat, the tool call pauses instead, and Chat#pending_inputs
-    # returns the requests.
-    class InputRequiredError < Error
-      def initialize(server, input) # :nodoc:
-        @input = input
-        asks = requests.map { |request| [request.message, request.url].compact.join(' ') }
-        super("#{server} needs input from the user: #{asks.join('; ')}")
-      end
-
-      # The unanswered MCP::InputRequest objects.
-      def requests
-        @input['requests'].reject(&:answered?)
-      end
-
-      # Returns everything needed to answer the requests later and resume
-      # the call, as a Hash that serializes to JSON.
-      def to_h # :nodoc:
-        @input.merge('requests' => @input['requests'].map(&:to_h)).compact
-      end
+    # MCP.before_input_request callback answered. Rescue
+    # RubyLLM::InputRequiredError to catch a tool's own questions too.
+    class InputRequiredError < RubyLLM::InputRequiredError
     end
   end
 end

data/lib/ruby_llm/mcp/insufficient_scope_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # Raised when an MCP server refuses a request because the token lacks a
+    # scope it needs. The message carries the server's reason, and #scopes
+    # the scopes it asked for. RubyLLM never widens a grant by itself: to
+    # grant them, send the user through MCP#authorization_url again.
+    #
+    #   begin
+    #     chat.ask "List the open issues in crmne/ruby_llm"
+    #   rescue RubyLLM::MCP::InsufficientScopeError => e
+    #     e.message  # => "api.githubcopilot.com refused the request: Additional scopes required: repo"
+    #     e.scopes   # => ["repo"]
+    #   end
+    class InsufficientScopeError < RubyLLM::ForbiddenError
+      # The scopes the server's challenge asked for, as Strings. Empty when
+      # it named none.
+      attr_reader :scopes
+
+      def initialize(message = nil, scopes: [], **) # :nodoc:
+        @scopes = scopes
+        super(message, **)
+      end
+    end
+  end
+end

data/lib/ruby_llm/mcp/listener.rb

@@ -58,7 +58,13 @@ module RubyLLM
         @changes = changes
         @pid = Process.pid
         @state = nil
-        @thread = Thread.new { Support::ProgressReporter.listen(nil) { run } }
+        @thread = Thread.new do
+          Support::Cancellation.watch(nil) do
+            Support::Instrumentation.with_workflow(nil) do
+              Support::ProgressReporter.listen(nil) { Accounting::Usage.with_owner(nil) { run } }
+            end
+          end
+        end
         @thread.name = 'ruby_llm-mcp-listener'
         @thread.report_on_exception = false
         acknowledgment

data/lib/ruby_llm/mcp/oauth.rb

@@ -34,6 +34,9 @@ module RubyLLM
       REFRESH_EARLY = 60
       ASSERTION_FOR = 60
       GRANTS = %i[authorization_code client_credentials jwt_bearer].freeze
+      RESERVED_AUTHORIZATION_PARAMS = %w[
+        client_id redirect_uri state code_challenge code_challenge_method response_type resource scope
+      ].freeze
       JWT_BEARER = 'urn:ietf:params:oauth:grant-type:jwt-bearer'
       TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange'
       ID_JAG = 'urn:ietf:params:oauth:token-type:id-jag'
@@ -45,7 +48,7 @@ module RubyLLM
         issuer token_endpoint token_endpoint_auth_methods_supported token_endpoint_auth_signing_alg_values_supported
         authorization_response_iss_parameter_supported
       ].freeze
-      CLIENT_FIELDS = %w[client_id client_secret issuer server redirect_uri dpop_key].freeze
+      CLIENT_FIELDS = %w[client_id client_secret issuer server redirect_uri dpop_key resource].freeze
       TOKEN = /[!\#$%&'*+.^_`|~0-9A-Za-z-]+/
       PARAMETER = /#{TOKEN}\s*=/
       QUOTED = /"((?:[^"\\]|\\.)*)"/
@@ -55,7 +58,7 @@ module RubyLLM
         '%<path>s/.well-known/openid-configuration'
       ].freeze
 
-      @refreshes = Hash.new { |refreshes, key| refreshes[key] = Mutex.new }
+      @refreshes = {}
       @refreshes_lock = Mutex.new
 
       def self.memory_store
@@ -75,9 +78,19 @@ module RubyLLM
       end
 
       # Runs the block while no other thread in this process refreshes the
-      # credentials stored under +key+.
+      # credentials stored under +key+. A key's lock lives only while a
+      # thread holds it or waits for it.
       def self.refreshing(key, &)
-        @refreshes_lock.synchronize { @refreshes[key] }.synchronize(&)
+        lock = @refreshes_lock.synchronize do
+          entry = @refreshes[key] ||= [Mutex.new, 0]
+          entry[1] += 1
+          entry.first
+        end
+        begin
+          lock.synchronize(&)
+        ensure
+          @refreshes_lock.synchronize { @refreshes.delete(key) if (@refreshes[key][1] -= 1).zero? }
+        end
       end
 
       # Reads the challenges of a WWW-Authenticate header (RFC 9110
@@ -98,8 +111,9 @@ module RubyLLM
       end
 
       def initialize(server_url, owner:, scopes: nil, client_id: nil, client_secret: nil, grant: nil,
-                     private_key: nil, assertion: nil, identity_provider: nil, config: RubyLLM.config,
-                     resolve: ->(value) { value })
+                     private_key: nil, assertion: nil, identity_provider: nil, authorization_params: nil,
+                     config: RubyLLM.config, resolve: ->(value) { value })
+        HTTP.parse(server_url)
         @server_url = server_url.to_s
         @owner = owner
         @scopes = scopes
@@ -108,20 +122,22 @@ module RubyLLM
         @private_key = resolve.call(private_key)
         @assertion = assertion
         @identity_provider = identity_provider
+        @authorization_params = authorization_params
         @grant = grant || (assertion || identity_provider ? :jwt_bearer : :authorization_code)
         @resolve = resolve
         @config = config
       end
 
       def authorized?
-        credential&.key?('access_token')
+        @credential = store.read(key) unless @credential&.key?('access_token')
+        @credential.to_h.key?('access_token')
       end
 
       def access_token
         return unless authorized?
 
         renew if expiring?
-        credential['access_token']
+        credential.to_h['access_token']
       end
 
       # Returns the headers that authorize a +verb+ request to the server:
@@ -179,27 +195,44 @@ module RubyLLM
         verifier = SecureRandom.urlsafe_base64(64)
         state = SecureRandom.urlsafe_base64(32)
         pending = client.merge('state' => state, 'verifier' => verifier, 'redirect_uri' => redirect_uri,
-                               'issuer' => server['issuer'], 'scope' => scopes_for(server),
-                               'dpop_key' => binding_key, 'expires_at' => Time.now.to_i + PENDING_FOR)
-        write(credential.to_h.merge('pending' => pending.merge('server' => server.slice(*SERVER_FIELDS))))
+                               'issuer' => server['issuer'], 'scope' => scopes_for(server), 'resource' => resource,
+                               'dpop_key' => binding_key, 'expires_at' => Time.now.to_i + PENDING_FOR,
+                               'server' => server.slice(*SERVER_FIELDS))
+        synchronize { write(store.read(key).to_h.merge('pending' => pending)) }
 
         query = { response_type: 'code', client_id: client['client_id'], redirect_uri:, state:,
                   code_challenge: Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false),
                   code_challenge_method: 'S256', resource:, scope: pending['scope'] }.compact
-        "#{endpoint(server['authorization_endpoint'])}?#{URI.encode_www_form(query)}"
+        uri = URI(endpoint(server['authorization_endpoint']))
+        uri.query = URI.encode_www_form(URI.decode_www_form(uri.query.to_s) + extra_authorization_params + query.to_a)
+        uri.to_s
+      end
+
+      def self.check_authorization_params(params) # :nodoc:
+        reserved = params.keys.map(&:to_s) & RESERVED_AUTHORIZATION_PARAMS
+        return params if reserved.empty?
+
+        raise ArgumentError, "RubyLLM sets #{reserved.join(', ')} itself; remove it from authorization_params"
       end
 
       def authorize(params)
-        pending = credential&.fetch('pending', nil) or raise Error, 'No authorization in progress'
-        check_callback(pending, params)
-        tokens = token_request('authorization_code', code: value(params, :code), redirect_uri: pending['redirect_uri'],
-                                                     code_verifier: pending['verifier'], client: pending)
-        store_tokens(tokens, client: pending.slice(*CLIENT_FIELDS, 'scope'))
+        synchronize do
+          @credential = store.read(key)
+          pending = credential&.fetch('pending', nil) or raise Error, 'No authorization in progress'
+          check_callback(pending, params)
+          tokens = token_request('authorization_code', code: value(params, :code),
+                                                       redirect_uri: pending['redirect_uri'],
+                                                       code_verifier: pending['verifier'], client: pending)
+          @credential = credential.except('pending')
+          store_tokens(tokens, client: pending.slice(*CLIENT_FIELDS, 'scope'))
+        end
       end
 
       def deauthorize
-        @credential = nil
-        store.delete(key)
+        synchronize do
+          @credential = nil
+          store.delete(key)
+        end
       end
 
       private
@@ -208,6 +241,11 @@ module RubyLLM
         @credential ||= store.read(key)
       end
 
+      def extra_authorization_params
+        params = Hash(@resolve.call(@authorization_params))
+        self.class.check_authorization_params(params).map { |name, value| [name.to_s, @resolve.call(value).to_s] }
+      end
+
       def write(data)
         @credential = data
         store.write(key, data, owner: @owner)
@@ -218,7 +256,7 @@ module RubyLLM
       end
 
       def store_tokens(tokens, client: nil)
-        data = credential.to_h.except('pending')
+        data = credential.to_h
         data = data.except(*CLIENT_FIELDS).merge(client) if client
         data = data.merge('access_token' => tokens['access_token'], 'scope' => tokens['scope'] || data['scope'],
                           'expires_at' => (Time.now.to_i + tokens['expires_in'].to_i if tokens['expires_in']),
@@ -333,7 +371,10 @@ module RubyLLM
         check_issuer(pending, value(params, :iss))
         check_state(pending, value(params, :state).to_s)
         error = value(params, :error)
-        raise Error, "Authorization failed: #{value(params, :error_description) || error}" if error
+        return unless error
+
+        raise Error.new('Authorization failed', provider_message: value(params, :error_description) || error,
+                                                error_code: error)
       end
 
       def check_issuer(pending, issuer)
@@ -366,17 +407,25 @@ module RubyLLM
       # attempt signs a new proof and a new client assertion.
       def send_token_request(server, client, key, params, retried: false)
         url = server['token_endpoint']
-        form = params.merge(client_id: client['client_id'], resource:)
+        form = params.merge(client_id: client['client_id'], resource: resource(client))
         headers = { 'Content-Type' => 'application/x-www-form-urlencoded', 'Accept' => 'application/json' }
         authenticate(client, server, form, headers, key)
         headers['DPoP'] = proofs.sign(client['dpop_key'], url) if client['dpop_key']
-        post(url, URI.encode_www_form(form.compact), headers)
+        tokens = post(url, URI.encode_www_form(form.compact), headers)
+        return tokens if granted?(tokens)
+
+        # Keep only the error fields: a partial response may still carry a refresh or ID token.
+        raise rejection(url, tokens.slice('error', 'error_description', 'error_uri'))
       rescue Error => e
         raise if retried || !client['dpop_key'] || oauth_error(e) != 'use_dpop_nonce'
 
         send_token_request(server, client, key, params, retried: true)
       end
 
+      def granted?(tokens)
+        tokens['access_token'] && !tokens['error']
+      end
+
       def oauth_error(error)
         error.data['error'] if error.data.is_a?(Hash)
       end
@@ -394,6 +443,7 @@ module RubyLLM
         elsif client['client_secret']
           methods = server['token_endpoint_auth_methods_supported'] || ['client_secret_basic']
           if methods.include?('client_secret_basic')
+            form.delete(:client_id)
             headers['Authorization'] = "Basic #{basic_credentials(client['client_id'], client['client_secret'])}"
           else
             form[:client_secret] = client['client_secret']
@@ -483,19 +533,15 @@ module RubyLLM
         server.path == path || server.path.start_with?("#{path}/")
       end
 
+      # RFC 8414 section 3.3: metadata whose issuer is not the authorization
+      # server it was fetched for must not be used.
       def discover_authorization_server(issuer)
         server = authorization_server_metadata(issuer)
         return server if same_issuer?(server['issuer'], issuer)
 
-        named = server['issuer']
-        raise Error, "#{issuer} metadata names a different issuer" unless named.is_a?(String) && URI(named).host
-
-        server = authorization_server_metadata(named)
-        raise Error, "#{issuer} metadata names a different issuer" unless same_issuer?(server['issuer'], named)
-
-        server
-      rescue URI::InvalidURIError
         raise Error, "#{issuer} metadata names a different issuer"
+      rescue URI::InvalidURIError
+        raise Error, "#{issuer} is not a valid authorization server URL"
       end
 
       def authorization_server_metadata(issuer)
@@ -578,14 +624,14 @@ module RubyLLM
         @challenge.to_h.each_value.filter_map { |parameters| parameters[name] }.first
       end
 
-      def resource
-        @resource || @server_url.chomp('/')
+      def resource(client = nil)
+        client&.fetch('resource', nil) || @resource || @server_url.chomp('/')
       end
 
       def first_json(urls)
         urls.each do |url|
           return get_json(url)
-        rescue Faraday::Error, Error
+        rescue Error
           next
         end
         nil
@@ -593,6 +639,8 @@ module RubyLLM
 
       def get_json(url)
         parse(connection(url).get(url, nil, 'Accept' => 'application/json'))
+      rescue Faraday::Error => e
+        raise failure(url, e)
       end
 
       def post(url, body, headers)
@@ -600,8 +648,15 @@ module RubyLLM
         proofs.remember(url, response.headers['dpop-nonce'])
         parse(response)
       rescue Faraday::Error => e
-        raise refusal(url, e.response && Faraday::Response.new(status: e.response[:status], body: e.response[:body],
-                                                               response_headers: e.response[:headers]))
+        raise failure(url, e)
+      end
+
+      def failure(url, error)
+        response = error.response
+        return ConnectionError.new(error.message, provider: URI(url).host) unless response
+
+        refusal(url, Faraday::Response.new(status: response[:status], body: response[:body],
+                                           response_headers: response[:headers]))
       end
 
       def refusal(url, response)
@@ -611,15 +666,23 @@ module RubyLLM
         rescue JSON::ParserError
           {}
         end
+        rejection(url, details, response)
+      end
+
+      def rejection(url, details, response = nil)
         details = {} unless details.is_a?(Hash)
-        Error.new("#{URI(url).host} refused the request: #{details['error_description'] || details['error']}",
+        Error.new("#{URI(url).host} refused the request",
+                  provider_message: details['error_description'] || details['error'], error_code: details['error'],
                   data: details, response:)
       end
 
       def parse(response)
-        JSON.parse(response.body)
+        document = JSON.parse(response.body)
+        raise JSON::ParserError unless document.is_a?(Hash)
+
+        document
       rescue JSON::ParserError
-        raise Error, 'The authorization server did not answer with JSON'
+        raise Error, 'The authorization server did not answer with a JSON object'
       end
 
       def connection(url)

data/lib/ruby_llm/mcp/outages.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class MCP
+    # The servers that could not be reached lately, for this whole process.
+    # A server waits this long, or as long as its Retry-After asks, before
+    # anyone tries it again, since a server that never answers would
+    # otherwise hold up every request, and each request in a job builds its
+    # MCP objects anew. A server that answers that it is unavailable, with
+    # HTTP 429 or a 5xx status, counts as one that can't be reached; one
+    # that refuses the credentials or the request does not, since trying
+    # again won't fix that.
+    module Outages # :nodoc:
+      BACKOFF = 60
+      PARTLY_RUN = 'The call may have partly run, so check before trying it again.'
+
+      # The tool error of a call the server failed, which a chat gives the
+      # model like any tool error.
+      class Failure < Hash # :nodoc:
+      end
+      UNAVAILABLE = [ConnectionError, RateLimitError, ServerError, ServiceUnavailableError, OverloadedError,
+                     Stdio::Unavailable].freeze
+
+      @lock = Mutex.new
+      @retry_at = {}
+
+      class << self
+        def tools(server)
+          return [] if down?(server)
+
+          server.tools
+        rescue RubyLLM::Error => e
+          raise unless unavailable?(e)
+
+          report(server, e) if record(server, backoff(e))
+          []
+        end
+
+        # Yields to call one of +server+'s tools, and returns the tool error
+        # when the server fails the call, or right away while the server
+        # sits out. A handler declared on the server's class or on MCP::Tool
+        # takes the error instead, but not one every Tool inherits, so a
+        # catch-all on RubyLLM::Tool keeps the outage handling. Checking on
+        # a task still raises, since the task may still be running.
+        def calling(server, tool, input)
+          return yield if input&.key?('task')
+          return Failure[error: "The #{server.name} MCP server can't be reached right now"] if down?(server)
+
+          begin
+            yield
+          rescue StandardError => e
+            raise if server.class.rescue_handler_for(e) || tool.class.rescue_handler_for(e, within: MCP::Tool)
+
+            failed_call(server, tool, e) || raise
+          end
+        end
+
+        # Returns the tool error for a call +server+ failed, or +nil+ for an
+        # error the call should raise: one that is not the server's, or a
+        # refusal such as missing credentials or an unknown endpoint. A
+        # server that is unavailable sits out until its backoff ends. The
+        # model reads what the server wrote, even with redacted error
+        # messages, since it is the one deciding what to do next.
+        def failed_call(server, tool, error)
+          return unless error.is_a?(Error) || (error.is_a?(RubyLLM::Error) && unavailable?(error))
+          return if refused_status?(error.response&.status)
+
+          if unavailable?(error)
+            report(server, error) if record(server, backoff(error))
+            server.send(:forget_tools)
+          end
+          Failure[error: failure_text(server, tool, error)]
+        end
+
+        def down?(server)
+          return false if server.tools_listed?
+
+          key = key(server)
+          @lock.synchronize { (@retry_at[key] || 0) > monotonic_now }
+        end
+
+        def clear
+          @lock.synchronize { @retry_at.clear }
+        end
+
+        private
+
+        # Names the error by its class and status, never its message, since
+        # a connection error's message can carry the server's host or URL.
+        def report(server, error)
+          status = error.response&.status
+          RubyLLM.logger.warn("MCP server #{server.name} is unreachable, so its tools sit out: " \
+                              "#{[error.class, ("HTTP #{status}" if status)].compact.join(', ')}")
+          payload = { server: server.name, error: error.class.name, status: }.compact
+          RubyLLM.instrument('mcp_unreachable.ruby_llm', payload, config: server.send(:config))
+        end
+
+        # What the server wrote, or the error's own message when it wrote
+        # nothing, as an empty message would tell the model nothing.
+        def failure_text(server, tool, error)
+          detail = [error.provider_message, error.message].find { |candidate| candidate.to_s.strip != '' }
+          text = "The #{server.name} MCP server failed: #{detail}"
+          partly_run?(tool, error) ? "#{text.delete_suffix('.')}. #{PARTLY_RUN}" : text
+        end
+
+        # A call that broke off, or that the server failed with a 5xx
+        # status, may have done some of its work before it stopped, unless
+        # the tool says it has no effect or the same call again has none.
+        def partly_run?(tool, error)
+          return false if tool.read_only? || (tool.idempotent? && !tool.destructive?)
+
+          unavailable?(error) && error.response&.status != 429
+        end
+
+        def unavailable?(error)
+          UNAVAILABLE.any? { |kind| error.is_a?(kind) } || unavailable_status?(error.response&.status)
+        end
+
+        def refused_status?(status)
+          (400..499).cover?(status) && !unavailable_status?(status)
+        end
+
+        def unavailable_status?(status)
+          status == 429 || (500..599).cover?(status)
+        end
+
+        def backoff(error)
+          value = error.response&.headers&.[]('Retry-After').to_s
+          seconds = Float(value, exception: false) || seconds_until(value)
+          seconds&.positive? ? seconds : BACKOFF
+        end
+
+        def seconds_until(date)
+          Time.httpdate(date) - Time.now
+        rescue ArgumentError
+          nil
+        end
+
+        # Returns whether this caller started the backoff.
+        def record(server, backoff)
+          key = key(server)
+          @lock.synchronize do
+            now = monotonic_now
+            @retry_at.delete_if { |_key, retry_at| retry_at <= now }
+            next false if @retry_at.key?(key)
+
+            @retry_at[key] = now + backoff
+            true
+          end
+        end
+
+        # Settings, not classes, since RubyLLM.mcp builds a class per call.
+        # Settings that depend on runtime state can differ per object, and so
+        # can the connection settings of an object's context, so one tenant's
+        # server never sidelines another's.
+        def key(server)
+          settings = server.class
+          endpoint = [settings.url, *settings.command]
+          return server if settings.transport || !endpoint.compact.all?(String)
+
+          config = server.send(:config)
+          ssl = Transport::Connection.ssl_snapshot(config.ssl) if config.ssl
+          [*endpoint, config.http_proxy, ssl, config.faraday_adapter, config.request_timeout]
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end