mcp 1.0.0 → 1.2.0

data/lib/mcp/client.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "client/elicitation"
+require_relative "client/mcp_param_headers"
+require_relative "client/modern_envelope"
 require_relative "client/oauth"
 require_relative "client/stdio"
 require_relative "client/http"
@@ -10,6 +12,12 @@ require_relative "result_type"
 
 module MCP
   class Client
+    # Upper bound on the number of pages the all-pages methods (`tools`, `resources`,
+    # `resource_templates`, `prompts`) will walk. The cursor guard in `fetch_all_pages` only
+    # stops a server that repeats or cycles cursors; one that returns a fresh `nextCursor` on
+    # every response would otherwise be followed indefinitely, growing the retained pages with it.
+    MAX_PAGES = 1_000
+
     class ServerError < StandardError
       attr_reader :code, :data
 
@@ -50,13 +58,19 @@ module MCP
     # server-returned JSON-RPC error, which is raised as `ServerError`.
     class ValidationError < StandardError; end
 
+    # Raised when an all-pages method reaches `max_pages` while the server is still offering
+    # another cursor. Use the single-page `list_*` methods to walk such a collection with
+    # a policy of your own.
+    class PaginationLimitError < StandardError; end
+
     # Raised when a server answers with a SEP-2322 Multi Round-Trip `input_required` result instead of
     # a final result. The result is not an error on the wire: it asks the client to fulfill the server's
     # `inputRequests` (a map of id => `{ "method" => ..., "params" => ... }` request objects with
     # `sampling/createMessage`, `roots/list`, or `elicitation/create` shapes) and re-issue
     # the original request with `inputResponses` plus the echoed opaque `requestState`.
-    # This SDK does not yet drive that resume loop automatically; callers can inspect `input_requests`
-    # and respond manually.
+    # With handlers registered through `on_elicitation`, `on_sampling`, or `on_roots`, the resume loop runs
+    # automatically; this error surfaces when no matching handler exists (manual driving via
+    # `input_requests` and the `input_responses:`/`request_state:` kwargs), or when the round cap is exhausted.
     # https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322
     class InputRequiredError < StandardError
       attr_reader :input_requests, :request_state, :result
@@ -79,30 +93,100 @@ module MCP
       end
     end
 
+    # The server's `DiscoverResult` (MCP 2026-07-28, SEP-2575): the modern protocol versions it serves,
+    # its capabilities and identity, optional instructions, and the REQUIRED `ttlMs`/`cacheScope` cache hints.
+    DiscoverResult = Struct.new(
+      :supported_versions,
+      :capabilities,
+      :server_info,
+      :instructions,
+      :ttl_ms,
+      :cache_scope,
+      keyword_init: true,
+    )
+
+    # Rounds the SEP-2322 driver runs before giving up, matching the TypeScript and
+    # Python SDK defaults. Every leg counts, including `requestState`-only retries.
+    DEFAULT_INPUT_REQUIRED_MAX_ROUNDS = 10
+
+    # Backoff for `requestState`-only (load shedding) legs: exponential from 50ms to
+    # a 250ms cap, matching the Python SDK (the TypeScript SDK uses a fixed 250ms).
+    STATE_ONLY_BACKOFF_INITIAL_SECONDS = 0.05
+    STATE_ONLY_BACKOFF_CAP_SECONDS = 0.25
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
     #   The transport should be a duck type that responds to `send_request`. See the README for more details.
+    # @param input_required_max_rounds [Integer] Cap on SEP-2322 driver rounds.
+    # @param max_pages [Integer] Maximum number of pages the all-pages methods ({#tools}, {#resources},
+    #   {#resource_templates}, {#prompts}) will walk before raising {MCP::Client::PaginationLimitError}.
+    #
+    # Once a handler is registered through `on_elicitation`, `on_sampling`, or `on_roots`, `call_tool`,
+    # `get_prompt`, and `read_resource` resume `input_required` results automatically; without handlers
+    # (or when a requested kind has no handler) they raise `InputRequiredError` for manual driving,
+    # exactly as before.
     #
     # @example
     #   transport = MCP::Client::HTTP.new(url: "http://localhost:3000")
     #   client = MCP::Client.new(transport: transport)
-    def initialize(transport:)
+    def initialize(transport:, input_required_max_rounds: DEFAULT_INPUT_REQUIRED_MAX_ROUNDS, max_pages: MAX_PAGES)
+      # `nil` or a non-positive value would make the pagination unbounded and silently
+      # disable the protection, so reject it up front.
+      unless max_pages.is_a?(Integer) && max_pages > 0
+        raise ArgumentError, "max_pages must be a positive Integer"
+      end
+
       @transport = transport
+      @max_pages = max_pages
+      # Populated by `on_elicitation`, `on_sampling`, and `on_roots`. The same handler answers both ways
+      # the server can ask for input: a real server-to-client request, and an embedded request inside
+      # a SEP-2322 `input_required` result.
+      @input_required_handlers = {}
+      @input_required_max_rounds = input_required_max_rounds
     end
 
     # The user may want to access additional transport-specific methods/attributes
     # So keeping it public
     attr_reader :transport
 
-    # The server's `InitializeResult` (protocol version, capabilities, server info,
-    # instructions), as reported by the transport after a successful `connect`.
-    # Returns `nil` before `connect`, after `close`, or when the transport does
-    # not expose a cached handshake result.
+    # The raw handshake result exactly as the server returned it, so its shape depends on the connection's era (SEP-2575):
+    # after the legacy handshake it is an `InitializeResult` (`protocolVersion`, top-level `serverInfo`), after modern adoption
+    # it is a `DiscoverResult` (`supportedVersions`, `ttlMs`/`cacheScope`, `serverInfo` optionally under `_meta`).
+    # Code that must work against both eras should prefer the era-independent readers {#protocol_version}, {#server_capabilities},
+    # {#instructions}, and {#server_implementation}; this raw form remains the window to everything they do not cover
+    # (`supportedVersions`, cache hints, `_meta`, extension data). Returns `nil` before `connect`, after `close`,
+    # or when the transport does not expose a cached handshake result.
     def server_info
       transport.server_info if transport.respond_to?(:server_info)
     end
 
+    # The protocol version in use on this connection, independent of its era:
+    # the version negotiated by `initialize` (legacy) or adopted via `server/discover` (modern).
+    # Returns `nil` before `connect`.
+    def protocol_version
+      return transport.protocol_version if transport.respond_to?(:protocol_version)
+
+      server_info&.dig("protocolVersion")
+    end
+
+    # The server's capabilities Hash, present in both eras. Returns `nil` before `connect`.
+    def server_capabilities
+      server_info&.dig("capabilities")
+    end
+
+    # The server's instructions text, present in both eras when provided.
+    def instructions
+      server_info&.dig("instructions")
+    end
+
+    # The server's identity (`name`/`version`), independent of where the era puts it: top-level `serverInfo`
+    # on legacy results, the optional `_meta` `io.modelcontextprotocol/serverInfo` stamp on modern results.
+    # Returns `nil` when a modern server does not identify itself.
+    def server_implementation
+      server_info&.dig("_meta", RequestEnvelope::SERVER_INFO_META_KEY) || server_info&.dig("serverInfo")
+    end
+
     # Performs the MCP `initialize` handshake by delegating to the transport
     # (e.g. `MCP::Client::HTTP`, `MCP::Client::Stdio`). Returns the server's
     # `InitializeResult`.
@@ -115,16 +199,62 @@ module MCP
     # @param capabilities [Hash] Capabilities advertised by the client. May include
     #   an `extensions` member per SEP-2133, keyed by reverse-DNS extension identifiers,
     #   e.g. `{ extensions: { "com.example/feature" => {} } }`.
-    # @return [Hash, nil] The server's `InitializeResult`, or `nil` when the transport
-    #   does not expose an explicit handshake.
+    # @param mode [Symbol, nil] Lifecycle selection (SEP-2575). When omitted, transports whose
+    #   `connect` declares `mode:` (the bundled `MCP::Client::HTTP` and `MCP::Client::Stdio`)
+    #   negotiate with `:auto`: probe `server/discover` first and fall back to the legacy handshake
+    #   when the server does not serve a mutually supported modern version. Transports without `mode:`
+    #   keep receiving the historical legacy call shape. `:legacy` forces the `initialize` handshake
+    #   exactly as before; `:modern` requires the modern lifecycle and fails without a mutual modern version.
+    #   Passing an explicit `protocol_version` from a legacy generation (e.g. `"2025-11-25"`) pins
+    #   the legacy handshake without a probe, so an explicitly requested version is never overridden
+    #   by the default negotiation.
+    # @return [Hash, nil] The server's `InitializeResult` (legacy) or `DiscoverResult` (modern),
+    #   or `nil` when the transport does not expose an explicit handshake.
+    #   Prefer the era-independent readers over inspecting this Hash directly.
     # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
-    def connect(client_info: nil, protocol_version: nil, capabilities: {})
+    def connect(client_info: nil, protocol_version: nil, capabilities: {}, mode: nil)
       return unless transport.respond_to?(:connect)
 
-      transport.connect(
-        client_info: client_info,
-        protocol_version: protocol_version,
-        capabilities: capabilities,
+      effective_mode = resolve_connect_mode(mode, protocol_version)
+
+      if effective_mode == :legacy
+        transport.connect(
+          client_info: client_info,
+          protocol_version: protocol_version,
+          capabilities: capabilities,
+        )
+      else
+        transport.connect(
+          client_info: client_info,
+          protocol_version: protocol_version,
+          capabilities: capabilities,
+          mode: effective_mode,
+        )
+      end
+    end
+
+    # Sends `server/discover` (MCP 2026-07-28, SEP-2575): sessionless capability discovery
+    # that works before (or instead of) `connect`.
+    #
+    # @param meta [Hash, nil] Additional `_meta` entries to send with the request.
+    # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
+    # @return [MCP::Client::DiscoverResult]
+    # @raise [ServerError] If the server returns a JSON-RPC error.
+    # @raise [ValidationError] If the response `result` is missing or not a Hash.
+    def discover(meta: nil, cancellation: nil)
+      response = request(method: Methods::SERVER_DISCOVER, meta: meta, cancellation: cancellation)
+      result = response.is_a?(Hash) ? response["result"] : nil
+      raise ValidationError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
+
+      DiscoverResult.new(
+        supported_versions: result["supportedVersions"],
+        capabilities: result["capabilities"],
+        # The finalized spec (PR #3002) stamps the server identity into the result `_meta`;
+        # the top-level fallback tolerates servers built against the frozen SEP text.
+        server_info: result.dig("_meta", RequestEnvelope::SERVER_INFO_META_KEY) || result["serverInfo"],
+        instructions: result["instructions"],
+        ttl_ms: result["ttlMs"],
+        cache_scope: result["cacheScope"],
       )
     end
 
@@ -160,12 +290,15 @@ module MCP
       response = request(method: "tools/list", params: params, meta: meta, cancellation: cancellation)
       result = response["result"] || {}
 
-      tools = (result["tools"] || []).map do |tool|
+      tools = (result["tools"] || []).filter_map do |tool|
+        next if exclude_invalid_x_mcp_header?(tool)
+
         Tool.new(
           name: tool["name"],
           description: tool["description"],
           input_schema: tool["inputSchema"],
           output_schema: tool["outputSchema"],
+          annotations: tool["annotations"],
         )
       end
 
@@ -188,6 +321,7 @@ module MCP
     #   Cancelling it aborts whichever page is currently in flight; pages already returned are kept,
     #   but the call raises `MCP::CancelledError` instead of returning the partial set.
     # @return [Array<MCP::Client::Tool>] An array of available tools.
+    # @raise [MCP::Client::PaginationLimitError] If the server offers more than `max_pages` pages.
     #
     # @example
     #   tools = client.tools
@@ -229,6 +363,7 @@ module MCP
     #
     # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available resources.
+    # @raise [MCP::Client::PaginationLimitError] See {#tools}.
     def resources(cancellation: nil)
       # TODO: consider renaming to `list_all_resources`.
       fetch_all_pages { |cursor| list_resources(cursor: cursor, cancellation: cancellation) }.flat_map(&:resources)
@@ -264,6 +399,7 @@ module MCP
     #
     # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available resource templates.
+    # @raise [MCP::Client::PaginationLimitError] See {#tools}.
     def resource_templates(cancellation: nil)
       # TODO: consider renaming to `list_all_resource_templates`.
       fetch_all_pages { |cursor| list_resource_templates(cursor: cursor, cancellation: cancellation) }.flat_map(&:resource_templates)
@@ -299,6 +435,7 @@ module MCP
     #
     # @param cancellation [MCP::Cancellation, nil] Optional cancellation token (see {#tools}).
     # @return [Array<Hash>] An array of available prompts.
+    # @raise [MCP::Client::PaginationLimitError] See {#tools}.
     def prompts(cancellation: nil)
       # TODO: consider renaming to `list_all_prompts`.
       fetch_all_pages { |cursor| list_prompts(cursor: cursor, cancellation: cancellation) }.flat_map(&:prompts)
@@ -339,7 +476,10 @@ module MCP
     # @note
     #   The exact requirements for `arguments` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
-    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil, cancellation: nil)
+    # @param input_responses [Hash, nil] SEP-2322 answers to a previous `input_required` result's `inputRequests`,
+    #   keyed identically (manual retry legs).
+    # @param request_state [String, nil] The opaque `requestState` echoed back byte-exactly.
+    def call_tool(name: nil, tool: nil, arguments: nil, progress_token: nil, meta: nil, cancellation: nil, input_responses: nil, request_state: nil)
       tool_name = name || tool&.name
       raise ArgumentError, "Either `name:` or `tool:` must be provided." unless tool_name
 
@@ -350,8 +490,10 @@ module MCP
         meta_entries[:progressToken] = progress_token
       end
       params[:_meta] = meta_entries unless meta_entries.empty?
+      params[:inputResponses] = input_responses if input_responses
+      params[:requestState] = request_state if request_state
 
-      request(method: "tools/call", params: params, cancellation: cancellation)
+      drive_input_required(method: "tools/call", params: params, cancellation: cancellation)
     end
 
     # Reads a resource from the server by URI and returns the contents.
@@ -361,8 +503,13 @@ module MCP
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Array<Hash>] An array of resource contents (text or blob).
-    def read_resource(uri:, meta: nil, cancellation: nil)
-      response = request(method: "resources/read", params: { uri: uri }, meta: meta, cancellation: cancellation)
+    def read_resource(uri:, meta: nil, cancellation: nil, input_responses: nil, request_state: nil)
+      params = { uri: uri }
+      params = params.merge(_meta: meta) if meta && !meta.empty?
+      params[:inputResponses] = input_responses if input_responses
+      params[:requestState] = request_state if request_state
+
+      response = drive_input_required(method: "resources/read", params: params, cancellation: cancellation)
 
       response.dig("result", "contents") || []
     end
@@ -374,8 +521,13 @@ module MCP
     #   e.g. SEP-414 trace context (see {MCP::TraceContext}).
     # @param cancellation [MCP::Cancellation, nil] Optional cancellation token.
     # @return [Hash] A hash containing the prompt details.
-    def get_prompt(name:, meta: nil, cancellation: nil)
-      response = request(method: "prompts/get", params: { name: name }, meta: meta, cancellation: cancellation)
+    def get_prompt(name:, meta: nil, cancellation: nil, input_responses: nil, request_state: nil)
+      params = { name: name }
+      params = params.merge(_meta: meta) if meta && !meta.empty?
+      params[:inputResponses] = input_responses if input_responses
+      params[:requestState] = request_state if request_state
+
+      response = drive_input_required(method: "prompts/get", params: params, cancellation: cancellation)
 
       response.fetch("result", {})
     end
@@ -404,8 +556,11 @@ module MCP
     # (message and `requestedSchema`, string keys) and must return an `ElicitResult`-shaped Hash:
     # `{ action: "accept" | "decline" | "cancel", content: { ... } }`.
     #
-    # Requires a transport that supports server-to-client requests (e.g. `MCP::Client::HTTP`);
-    # pass `capabilities: { elicitation: {} }` to `connect` so the server knows it may send them.
+    # The same handler answers both ways a server can ask: a real request mid-call, which needs a transport that
+    # carries server-to-client requests (e.g. `MCP::Client::HTTP`); and an `elicitation/create` embedded in a SEP-2322
+    # `input_required` result, which needs no server-to-client route, and is how the modern lifecycle asks now that it
+    # forbids server-to-client requests. Both routes need `capabilities: { elicitation: {} }` passed to `connect`: per SEP-2322,
+    # a server MUST NOT embed input requests of a kind the client has not declared.
     #
     # @example Accept with schema defaults applied (SEP-1034)
     #   client.on_elicitation do |params|
@@ -416,11 +571,7 @@ module MCP
     #   end
     # https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation
     def on_elicitation(&handler)
-      unless transport.respond_to?(:on_server_request)
-        raise ArgumentError, "The transport does not support server-to-client requests"
-      end
-
-      transport.on_server_request(Methods::ELICITATION_CREATE, &handler)
+      register_input_handler(Methods::ELICITATION_CREATE, &handler)
     end
 
     # Registers a handler for `sampling/createMessage` requests the server sends while one of this client's requests is in flight.
@@ -431,8 +582,11 @@ module MCP
     # For trust and safety, the spec recommends a human in the loop able to review, edit, or reject the request and the generated response
     # before it is returned to the server. To reject, raise `ServerRequestError` with the spec's user-rejection code `-1`.
     #
-    # Requires a transport that supports server-to-client requests (e.g. `MCP::Client::HTTP`); pass `capabilities: { sampling: {} }` to
-    # `connect` (or `{ sampling: { tools: {} } }` to receive tool-enabled sampling requests) so the server knows it may send them.
+    # The same handler answers both ways a server can ask: a real request mid-call, which needs a transport that
+    # carries server-to-client requests (e.g. `MCP::Client::HTTP`); and a `sampling/createMessage` embedded in a SEP-2322
+    # `input_required` result, which needs no server-to-client route. Both routes need `capabilities: { sampling: {} }` passed to
+    # `connect` (or `{ sampling: { tools: {} } }` for tool-enabled requests): per SEP-2322, a server MUST NOT embed input requests of
+    # a kind the client has not declared.
     #
     # @example Forward the request to an LLM and return its completion
     #
@@ -454,11 +608,23 @@ module MCP
     #   Register this handler only to interoperate with servers that still send sampling requests during the deprecation window;
     #   new servers should call LLM provider APIs directly.
     def on_sampling(&handler)
-      unless transport.respond_to?(:on_server_request)
-        raise ArgumentError, "The transport does not support server-to-client requests"
-      end
+      register_input_handler(Methods::SAMPLING_CREATE_MESSAGE, &handler)
+    end
 
-      transport.on_server_request(Methods::SAMPLING_CREATE_MESSAGE, &handler)
+    # Registers a handler for `roots/list`, answering both a server-to-client request on transports that
+    # support one and an embedded `roots/list` inside a SEP-2322 `input_required` result. The handler
+    # receives the request `params` (`nil` for `roots/list`) and must return a `ListRootsResult`-shaped Hash:
+    # `{ roots: [{ uri: "file:///project", name: "Project" }] }`.
+    #
+    # @example
+    #   client.on_roots { { roots: [{ uri: "file:///project", name: "Project" }] } }
+    #
+    # @deprecated MCP Roots (`roots/list`) is deprecated as of MCP protocol version 2026-07-28 (SEP-2577).
+    #   Register this handler only to interoperate with servers that still ask for roots.
+    #
+    # https://modelcontextprotocol.io/specification/2025-11-25/client/roots
+    def on_roots(&handler)
+      register_input_handler(Methods::ROOTS_LIST, &handler)
     end
 
     # Sends a `ping` request to the server to verify the connection is alive.
@@ -484,9 +650,77 @@ module MCP
 
     private
 
+    # Records a handler for one of the three kinds of input a server can ask this client for, and wires it to
+    # the transport when the transport can carry server-to-client requests. One registration serves both routes:
+    # the real request a 2025-11-25 server sends mid-call, and the request embedded in a SEP-2322
+    # `input_required` result, which is how the modern lifecycle asks now that it forbids server-to-client
+    # requests outright. Registering is therefore valid on a transport with no `on_server_request` (stdio,
+    # and every modern-lifecycle connection); only the wire route is skipped there.
+    def register_input_handler(method, &handler)
+      @input_required_handlers[method] = handler
+      transport.on_server_request(method, &handler) if transport.respond_to?(:on_server_request)
+
+      handler
+    end
+
+    # SEP-2243: on the modern lifecycle, a tool definition whose `x-mcp-header` annotations violate
+    # the spec constraints MUST be excluded from `tools/list` results, so one malformed definition
+    # does not block the valid tools. The TypeScript and Python SDKs filter their listings the same way.
+    # Legacy connections, and transports without a lifecycle notion, list everything as before.
+    def exclude_invalid_x_mcp_header?(tool)
+      return false unless transport.respond_to?(:modern?) && transport.modern?
+
+      scan = McpParamHeaders.scan(tool["inputSchema"])
+      return false if scan[:valid]
+
+      warn("MCP::Client: excluding tool #{tool["name"].inspect} from tools/list: #{scan[:reason]}")
+      true
+    end
+
+    # Resolves the effective SEP-2575 lifecycle mode for `connect`:
+    #
+    # - An explicit `protocol_version` from a legacy generation pins the legacy handshake without a probe,
+    #   so the default negotiation can never override a version the caller asked for.
+    # - Absent an explicit mode, transports declaring `mode:` negotiate with `:auto`; other transports keep
+    #   the historical legacy call shape.
+    # - An explicit `:modern`/`:auto` on a transport without `mode:` raises, rather than silently downgrading to
+    #   a lifecycle the caller did not ask for.
+    def resolve_connect_mode(mode, protocol_version)
+      unless [nil, :legacy, :modern, :auto].include?(mode)
+        raise ArgumentError, "mode must be :legacy, :modern, or :auto"
+      end
+
+      return :legacy if mode == :legacy
+      return :legacy if mode.nil? && protocol_version && !Configuration.modern_protocol_version?(protocol_version)
+
+      if transport_connect_accepts_mode?
+        mode || :auto
+      elsif mode.nil?
+        :legacy
+      else
+        raise ArgumentError, "transport does not support mode: #{mode.inspect}"
+      end
+    end
+
+    # `mode:` is forwarded only when the transport's `connect` declares it as a keyword.
+    # A bare `**kwargs` deliberately does not count, so wrappers and test doubles that
+    # absorb arbitrary keywords keep the historical legacy call shape. Objects that
+    # dispatch `connect` through `method_missing` (e.g. mocks) may not support `method`,
+    # which reads as not declaring `mode:`.
+    def transport_connect_accepts_mode?
+      connect_method = begin
+        transport.method(:connect)
+      rescue NameError
+        return false
+      end
+
+      connect_method.parameters.any? { |type, name| [:key, :keyreq].include?(type) && name == :mode }
+    end
+
     # Walks every page of a list endpoint, following `next_cursor`, and returns
     # the page results. The `seen` set guards against a server that repeats or
-    # cycles cursors, so the loop always terminates.
+    # cycles cursors, and `@max_pages` bounds one that returns a fresh cursor every
+    # time, so the loop always terminates.
     def fetch_all_pages
       pages = []
       seen = Set.new
@@ -498,6 +732,11 @@ module MCP
         next_cursor = page.next_cursor
         break if next_cursor.nil? || seen.include?(next_cursor)
 
+        if pages.size >= @max_pages
+          raise PaginationLimitError, "Server returned more than #{@max_pages} pages; pass a larger `max_pages:` to " \
+                                      "`MCP::Client.new` if this is expected."
+        end
+
         seen << next_cursor
         cursor = next_cursor
       end
@@ -509,7 +748,7 @@ module MCP
     # without mutating the caller's hashes. Per SEP-414, `_meta` carries
     # request-specific metadata such as W3C trace context (`traceparent`,
     # `tracestate`, `baggage`); see {MCP::TraceContext}.
-    def request(method:, params: nil, meta: nil, cancellation: nil)
+    def request(method:, params: nil, meta: nil, cancellation: nil, raise_on_input_required: true)
       params = (params || {}).merge(_meta: meta) if meta && !meta.empty?
 
       request_body = {
@@ -531,20 +770,104 @@ module MCP
         raise ServerError.new(error["message"], code: error["code"], data: error["data"])
       end
 
-      raise_on_input_required(response)
+      raise_on_input_required(response) if raise_on_input_required
 
       response
     end
 
+    # Drives the SEP-2322 multi round-trip loop for `tools/call`, `prompts/get`, and `resources/read`.
+    # With no configured handlers this degrades to the plain request (an `input_required` result raises
+    # `InputRequiredError` for manual driving). Otherwise each `inputRequests` entry is fulfilled by
+    # the matching handler and the ORIGINAL request is re-issued with `inputResponses` under
+    # the same keys plus the byte-exact echoed `requestState`, on a fresh JSON-RPC id per leg.
+    # A `requestState`-only result (load shedding) retries after an exponential backoff.
+    # Every leg counts against `input_required_max_rounds`.
+    def drive_input_required(method:, params:, cancellation:)
+      response = request(
+        method: method,
+        params: params,
+        cancellation: cancellation,
+        raise_on_input_required: @input_required_handlers.empty?,
+      )
+      return response unless input_required?(response)
+
+      original_params = params.dup
+      original_params.delete(:inputResponses)
+      original_params.delete(:requestState)
+      rounds = 0
+      backoff = STATE_ONLY_BACKOFF_INITIAL_SECONDS
+
+      loop do
+        result = response["result"]
+        rounds += 1
+        if rounds > @input_required_max_rounds
+          raise InputRequiredError.new(
+            "Server still returned `input_required` after #{@input_required_max_rounds} rounds (SEP-2322).",
+            input_requests: result["inputRequests"] || {},
+            request_state: result["requestState"],
+            result: result,
+          )
+        end
+
+        input_requests = result["inputRequests"] || {}
+        responses = nil
+        if input_requests.empty?
+          sleep(backoff)
+          backoff = [backoff * 2, STATE_ONLY_BACKOFF_CAP_SECONDS].min
+        else
+          backoff = STATE_ONLY_BACKOFF_INITIAL_SECONDS
+          responses = fulfill_input_requests(input_requests, result)
+        end
+
+        retry_params = original_params.dup
+        retry_params[:inputResponses] = responses if responses
+        retry_params[:requestState] = result["requestState"] if result["requestState"]
+
+        response = request(
+          method: method,
+          params: retry_params,
+          cancellation: cancellation,
+          raise_on_input_required: false,
+        )
+        return response unless input_required?(response)
+      end
+    end
+
+    # Dispatches every embedded request to its configured handler and collects
+    # the answers under the same keys. A kind without a handler falls back to
+    # the manual path by raising `InputRequiredError` with the full result.
+    def fulfill_input_requests(input_requests, result)
+      input_requests.each_with_object({}) do |(key, entry), responses|
+        entry_method = entry.is_a?(Hash) ? entry["method"] || entry[:method] : nil
+        handler = @input_required_handlers[entry_method]
+        unless handler
+          raise InputRequiredError.new(
+            "Server requested #{entry_method.inspect} input (key #{key.inspect}) but no matching handler " \
+              "is configured; inspect `input_requests` to respond manually (SEP-2322).",
+            input_requests: input_requests,
+            request_state: result["requestState"],
+            result: result,
+          )
+        end
+
+        responses[key] = handler.call(entry.is_a?(Hash) ? entry["params"] || entry[:params] : nil)
+      end
+    end
+
+    def input_required?(response)
+      result = response.is_a?(Hash) ? response["result"] : nil
+      result.is_a?(Hash) && result["resultType"] == ResultType::INPUT_REQUIRED
+    end
+
     # Recognizes a SEP-2322 `input_required` result and raises rather than returning it as if it were a final result.
     # Servers on stable protocol versions never emit `resultType`, so this is a no-op for them.
     def raise_on_input_required(response)
-      result = response.is_a?(Hash) ? response["result"] : nil
-      return unless result.is_a?(Hash) && result["resultType"] == ResultType::INPUT_REQUIRED
+      return unless input_required?(response)
 
+      result = response["result"]
       raise InputRequiredError.new(
-        "Server returned `input_required`; this SDK does not yet resume multi-round-trip requests (SEP-2322). " \
-          "Inspect `input_requests` to respond manually.",
+        "Server returned `input_required` (SEP-2322). Register a handler with `on_elicitation`, " \
+          "`on_sampling`, or `on_roots` to resume automatically, or inspect `input_requests` to respond manually.",
         input_requests: result["inputRequests"] || {},
         request_state: result["requestState"],
         result: result,