ruby-mcp-client 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5687a9c54b7e5c4814e80bd2e5e97d2072dd0f994e3bebe680259a1a9db64c25
-  data.tar.gz: 05b3bce582f21e57ae07ac862daf6a74812f3ba79f6e4b806868850686c33467
+  metadata.gz: 0705c6df1b589bdf048b8922a92c957125f75afd0ce3ba832ef71b99a9cbe87a
+  data.tar.gz: 486d2c9891e107acaf545a62d1845e0f3d843c634d526d80ee8d12c8f9e3bde7
 SHA512:
-  metadata.gz: 3aef7d0842eab30de7e84a5507298efd30ae78de3ea3223cc8f00bd31892e7665f55f533952df771a2d3ab38f874d3905e029b0d19b8147d07ffd030772106fe
-  data.tar.gz: 324f5121352512f827f05fa55f78917b3218b7d031c418cfa884a8718b2b06fda027b8b811df2083361200ff17682dbfea8998505db0e2932db3a545f605c35a
+  metadata.gz: f766e8b97d5d6ec634fb2e95b000b154e0ce00a0f25011de9a33bd40531d2151ce727e5c3958894f1f79cab8294242441020b6f9184dd8ddf4df828430d4ad2d
+  data.tar.gz: 4a9bf198454ce1d8a9cb4b8940551faf7ddaac5962248b10b20e5b095bb46d32c1a1a642042da70b98d47a5832c3eb22aa09f9df05d54c40cf3ca1003e92824d

data/README.md

@@ -47,6 +47,10 @@ with a revision it cannot speak (supported: `2025-11-25`, `2025-06-18`,
 - **Metadata**: `icons`, `title` and `_meta` parsed on tools, prompts and resources
 - **OAuth 2.1**: PKCE (S256 required), RFC 8414/9728 discovery, dynamic registration, Client ID Metadata Documents, scope step-up challenges
 
+Transports treat the server as untrusted input — see
+[Treating the Server as Untrusted](#treating-the-server-as-untrusted) for the
+limits applied to peer-controlled data.
+
 ## Quick Connect API (Recommended)
 
 The simplest way to connect to an MCP server:
@@ -327,15 +331,24 @@ task = client.call_tool_as_task('long_job', { input: 'data' }, ttl: 60_000)
 # honoring the server's suggested poll interval
 until task.terminal? || task.input_required?
   sleep((task.poll_interval || 1000) / 1000.0)
-  task = client.get_task(task.task_id)   # tasks/get
+  task = client.get_task(task)          # tasks/get, routed to the task's own server
 end
 
 # Retrieve the underlying result (e.g. a CallToolResult) via tasks/result
-result = client.get_task_result(task.task_id)
+result = client.get_task_result(task)
 
 # List and cancel tasks
 page = client.list_tasks               # { tasks: [...], next_cursor: ... }
-client.cancel_task(task.task_id)       # tasks/cancel
+client.cancel_task(task)               # tasks/cancel
+```
+
+Task IDs are only unique within the server that issued them, so pass the `Task`
+returned by `call_tool_as_task` — it carries its own server. A bare task ID also
+works when the client has a single server; with several servers configured it
+raises `ArgumentError` rather than guessing, so name the server explicitly:
+
+```ruby
+client.get_task('task-123', server: 'my-server')
 
 # React to server-pushed status updates
 client.on_notification do |server, method, params|
@@ -392,12 +405,49 @@ The `retries:` option controls automatic retry with exponential backoff. Only
 failures where the request most likely did **not** complete at the server are
 retried: transport/network errors and HTTP **5xx** responses. Application-level
 failures — a JSON-RPC error response or an HTTP **4xx** — are **never** retried,
-because the server already processed or rejected the request and re-sending
-would risk re-executing a non-idempotent `tools/call`. Retryable server failures
-raise `MCPClient::Errors::TransientServerError`, a subclass of
+because the server already processed or rejected the request. Retryable server
+failures raise `MCPClient::Errors::TransientServerError`, a subclass of
 `MCPClient::Errors::ServerError`, so existing `rescue ServerError` handlers are
 unaffected.
 
+**`tools/call` is never retried automatically.** Even a "transient" failure can
+arrive *after* the server executed the request, and JSON-RPC has no idempotency
+key that would make a replay safe — so a retry could run a side effect twice.
+Retry a tool call explicitly if your application knows it is safe to repeat, and
+treat the raised error as *outcome unknown* rather than *not executed*:
+
+```ruby
+begin
+  client.call_tool('send_invoice', { customer: 'acme' })
+rescue MCPClient::Errors::TransportError => e
+  # The server may or may not have sent the invoice. Check before retrying.
+end
+```
+
+The same reasoning excludes `RequestTimeoutError` and `ResponseTooLargeError`
+from retries, and applies to session recovery: if a `tools/call` comes back with
+an expired-session 404, the client starts a fresh session but does **not** re-send
+the call — it raises so you can decide. Idempotent requests are re-sent against
+the new session as before.
+
+### Response Size Limits (Streamable HTTP)
+
+A gzip-encoded response is decompressed incrementally and abandoned once it
+expands past `max_decompressed_body_bytes` (default **64 MiB**), so a small
+highly-compressed body cannot exhaust memory. Exceeding it raises
+`MCPClient::Errors::ResponseTooLargeError`.
+
+Raise the limit if you legitimately exchange very large payloads — base64
+resource blobs or audio — so that whether a response is accepted does not depend
+on the server's choice to compress it:
+
+```ruby
+MCPClient.streamable_http_config(
+  base_url: 'https://api.example.com/mcp',
+  max_decompressed_body_bytes: 256 * 1024 * 1024
+)
+```
+
 ### Faraday Customization
 
 ```ruby
@@ -637,10 +687,48 @@ tools = client.list_tools
 result = client.call_tool('echo', { message: 'Hello!' })
 ```
 
+## Treating the Server as Untrusted
+
+A connected MCP server controls everything it sends you, and the transports are
+written on that assumption. You do not need to configure any of this — it is the
+default behaviour — but it is worth knowing what the client will refuse:
+
+| Peer-controlled input | What the client does |
+|---|---|
+| Compressed response bodies (**Streamable HTTP only** — the only transport that requests gzip) | Decompressed incrementally, abandoned past `max_decompressed_body_bytes` (64 MiB default) |
+| SSE streams | Per-connection buffer cap; events scanned incrementally, so an unterminated event costs bounded memory *and* CPU |
+| `retry:` directives | Honored, but floored so `retry: 0` cannot drive a reconnect loop |
+| SSE event IDs | Bounded length, printable ASCII only (they are echoed in `Last-Event-ID`) |
+| Legacy SSE `endpoint` events | Must stay on the connection's origin; off-origin redirects are refused, so configured credential headers never reach another host |
+| OAuth discovery URLs from a peer | Must be HTTPS, and rejected when the host is a *literal* loopback/private/link-local address (unless the configured server is itself local); a refused challenge fails closed. Hostnames are not resolved, so a public name pointing at a private address is not caught — see the note below |
+| Unsolicited JSON-RPC responses | Discarded — only IDs with an outstanding request are accepted |
+| Server-initiated requests | Replies are bounded by a concurrency budget rather than spawning unbounded threads |
+| Schema `pattern` values | Matched under a whole-operation time budget; a timeout fails validation rather than silently passing |
+| Log messages (`notifications/message`) | Control characters escaped and length-capped, so a server cannot forge log lines |
+
+**Known limit:** the OAuth check is textual. A peer can still advertise a public
+hostname whose DNS record points inside your network; catching that needs
+resolution-time filtering in the HTTP layer, which this gem does not do. If you
+run in an environment where that matters, restrict egress at the network layer.
+
+Two related defaults worth calling out because they affect *your* data rather
+than the peer's:
+
+- **Payloads are never written to logs.** At DEBUG the client logs a method/id
+  summary and a byte count, not request params, response bodies or raw SSE
+  chunks. Server configurations are logged with credential-bearing keys redacted.
+- **Host exceptions are not reflected to the server.** A raising elicitation,
+  sampling or roots handler yields a constant JSON-RPC error message; the detail
+  stays in your local log.
+
 ## Requirements
 
 - Ruby >= 3.2.0
-- No runtime dependencies
+- Runtime dependencies: `faraday` (~> 2.0) with `faraday-follow_redirects` and
+  `faraday-retry`, plus `base64` — all pulled in automatically by the gem
+
+Development uses Ruby 4.0.6 (see `.ruby-version`). CI runs the suite on 4.0.6
+plus the supported floor, 3.2 and 3.3.
 
 ## License
 

data/lib/mcp_client/auth/oauth_provider.rb

@@ -68,6 +68,8 @@ module MCPClient
         # separately so a failed fetch is retried authoritatively by discovery.
         @challenge_resource_metadata = nil
         @challenge_metadata_url = nil
+        # Why a peer-advertised challenge URL was refused, if one was
+        @challenge_error = nil
       end
 
       # @param url [String] Server URL to normalize
@@ -189,9 +191,16 @@ module MCPClient
         # challenge as authoritative for satisfying the current request" —
         # including resetting a previously challenged scope when the current
         # challenge carries none.
-        @challenge_scope = bearer_params && extract_challenge_param(bearer_params, 'scope')
-
         url = extract_resource_metadata_url(www_authenticate)
+
+        # The challenge header is peer-controlled input: validate the
+        # advertised URL BEFORE storing, fetching, or recording any challenge
+        # state, so a malicious challenge cannot pivot this host into requests
+        # against internal services (SSRF) and cannot leave the provider
+        # holding half of a rejected challenge.
+        validate_peer_advertised_url!(url, 'resource metadata URL (from WWW-Authenticate challenge)') if url
+
+        @challenge_scope = bearer_params && extract_challenge_param(bearer_params, 'scope')
         return nil unless url
 
         # Remember the advertised URL even if the fetch below fails, so a
@@ -414,6 +423,12 @@ module MCPClient
       # @return [ServerMetadata] Authorization server metadata
       # @raise [MCPClient::Errors::ConnectionError] if discovery fails
       def discover_authorization_server
+        # A challenge we refused is still authoritative: it says the cached
+        # authorization server is no longer the right one. Falling back to
+        # that cache (or to speculative well-known probing) would quietly
+        # undo the rejection, so surface it instead.
+        raise MCPClient::Errors::ConnectionError, @challenge_error if @challenge_error
+
         # A fresh 401 challenge is authoritative and overrides any cached
         # (possibly stale or direct-discovered) authorization server metadata —
         # whether the challenge-advertised PRM was already fetched or only its
@@ -453,6 +468,7 @@ module MCPClient
         storage.set_server_metadata(server_url, server_metadata)
         @challenge_resource_metadata = nil # consumed
         @challenge_metadata_url = nil # consumed
+        @challenge_error = nil
         server_metadata
       end
 
@@ -506,6 +522,13 @@ module MCPClient
                 'Protected resource metadata does not advertise any authorization_servers'
         end
 
+        # authorization_servers is untrusted PRM content: validate the
+        # advertised origin BEFORE constructing and fetching well-known URLs
+        # on it, so a malicious protected resource cannot drive discovery GETs
+        # against internal services (SSRF).
+        validate_peer_advertised_url!(auth_server_url,
+                                      'authorization server (advertised by protected resource metadata)')
+
         server_metadata = fetch_first_server_metadata(authorization_server_metadata_urls(auth_server_url))
         unless server_metadata
           raise MCPClient::Errors::ConnectionError,
@@ -612,6 +635,71 @@ module MCPClient
         enforce_https!(server_metadata.registration_endpoint, 'registration endpoint')
       end
 
+      # Validate a URL that a peer advertised to us (a 401 challenge's
+      # resource_metadata, or PRM authorization_servers).
+      #
+      # Stricter than enforce_https!, which exists for URLs the OPERATOR
+      # configured and therefore tolerates plain-HTTP loopback for local
+      # development. Applying that exception to peer-supplied input would
+      # leave the reported SSRF intact against the most sensitive targets of
+      # all — services listening only on localhost. The loopback exception is
+      # honored here only when the configured MCP server is itself loopback,
+      # i.e. the developer is already pointed at a local stack.
+      #
+      # The rejection is recorded so a later discovery fails closed instead of
+      # silently reusing cached authorization-server metadata.
+      #
+      # NOTE: hostnames are checked literally. This does not resolve DNS, so a
+      # public name that resolves to a private address is not caught here;
+      # that needs resolution-time checking in the HTTP layer.
+      # @param url [String] the peer-advertised URL
+      # @param label [String] human-readable name for errors
+      # @raise [MCPClient::Errors::ConnectionError] if the URL is not acceptable
+      def validate_peer_advertised_url!(url, label)
+        uri = URI.parse(url)
+        host = uri.hostname.to_s.downcase
+
+        if uri.scheme != 'https' && !(uri.scheme == 'http' && local_development?)
+          reject_challenge!("OAuth #{label} must use HTTPS: #{url}")
+        end
+        reject_challenge!("OAuth #{label} must not target a loopback or private address: #{url}") if
+          local_address?(host) && !local_development?
+      rescue URI::InvalidURIError
+        reject_challenge!("OAuth #{label} is not a valid URL: #{url}")
+      end
+
+      # @param message [String] why the challenge was refused
+      # @raise [MCPClient::Errors::ConnectionError] always
+      def reject_challenge!(message)
+        # Drop every scrap of the refused challenge so nothing half-applied
+        # survives, and remember why for the next discovery attempt.
+        @challenge_scope = nil
+        @challenge_metadata_url = nil
+        @challenge_resource_metadata = nil
+        @challenge_error = message
+        raise MCPClient::Errors::ConnectionError, message
+      end
+
+      # @return [Boolean] whether the configured MCP server is itself local,
+      #   in which case local discovery targets are expected
+      def local_development?
+        local_address?(URI.parse(server_url).hostname.to_s.downcase)
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # @param host [String] a downcased hostname
+      # @return [Boolean] whether it names a loopback, private or link-local address
+      def local_address?(host)
+        return true if %w[localhost 127.0.0.1 ::1 0.0.0.0].include?(host)
+        return true if host.end_with?('.localhost', '.local', '.internal')
+        return true if host.start_with?('127.', '10.', '192.168.', '169.254.')
+        return true if host.match?(/\A172\.(1[6-9]|2\d|3[01])\./)
+        return true if host.match?(/\A\[?(fc|fd|fe80)/)
+
+        false
+      end
+
       # @param url [String, nil] endpoint URL
       # @param label [String] human-readable endpoint name for errors
       # @raise [MCPClient::Errors::ConnectionError] if the URL is not HTTPS (non-localhost)
@@ -1055,7 +1143,7 @@ module MCPClient
         storage.set_token(server_url, new_token)
         new_token
       rescue JSON::ParserError => e
-        logger.warn("Invalid token refresh response: #{e.message}")
+        logger.warn("Invalid token refresh response: #{describe_parse_error(e)}")
         nil
       rescue Faraday::Error => e
         logger.warn("Network error during token refresh: #{e.message}")

data/lib/mcp_client/auth.rb

@@ -100,13 +100,11 @@ module MCPClient
       # @param tos_uri [String, nil] URL of the client terms of service
       # @param policy_uri [String, nil] URL of the client privacy policy
       # @param contacts [Array<String>, nil] List of contact emails for the client
-      # rubocop:disable Metrics/ParameterLists
       def initialize(redirect_uris:, token_endpoint_auth_method: 'none',
                      grant_types: %w[authorization_code refresh_token],
                      response_types: ['code'], scope: nil,
                      client_name: nil, client_uri: nil, logo_uri: nil,
                      tos_uri: nil, policy_uri: nil, contacts: nil)
-        # rubocop:enable Metrics/ParameterLists
         @redirect_uris = redirect_uris
         @token_endpoint_auth_method = token_endpoint_auth_method
         @grant_types = grant_types
@@ -238,11 +236,9 @@ module MCPClient
       # @param code_challenge_methods_supported [Array<String>, nil] Supported PKCE code challenge methods (RFC 8414)
       # @param client_id_metadata_document_supported [Boolean, nil] Whether the server accepts
       #   Client ID Metadata Document client IDs (MCP 2025-11-25 / SEP-991)
-      # rubocop:disable Metrics/ParameterLists
       def initialize(issuer:, authorization_endpoint:, token_endpoint:, registration_endpoint: nil,
                      scopes_supported: nil, response_types_supported: nil, grant_types_supported: nil,
                      code_challenge_methods_supported: nil, client_id_metadata_document_supported: nil)
-        # rubocop:enable Metrics/ParameterLists
         @issuer = issuer
         @authorization_endpoint = authorization_endpoint
         @token_endpoint = token_endpoint

data/lib/mcp_client/client.rb

@@ -29,6 +29,20 @@ module MCPClient
     # :warn logs a warning on mismatch, :strict raises a ValidationError.
     STRUCTURED_CONTENT_MODES = %i[warn strict].freeze
 
+    # Server-config keys whose values carry credentials (HTTP headers, the
+    # subprocess environment, inline tokens). Their values are replaced before
+    # a config is written to the log.
+    SENSITIVE_CONFIG_KEYS = %i[headers env token access_token api_key auth authorization
+                               password secret client_secret oauth_provider].freeze
+
+    # Placeholder written in place of a redacted value.
+    REDACTED = '[REDACTED]'
+
+    # Maximum characters of a peer-supplied log message written to the host
+    # log. The remote server controls this content, so an unbounded message
+    # would let it inflate log storage at will.
+    MAX_PEER_LOG_MESSAGE_LENGTH = 4096
+
     # Initialize a new MCPClient::Client
     # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
     # @param logger [Logger, nil] optional logger, defaults to STDOUT
@@ -65,7 +79,7 @@ module MCPClient
         @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
       end
       @servers = mcp_server_configs.map do |config|
-        @logger.debug("Creating server with config: #{config.inspect}")
+        @logger.debug("Creating server with config: #{redact_config(config).inspect}")
         MCPClient::ServerFactory.create(config, logger: @logger)
       end
       @tool_cache = {}
@@ -562,14 +576,17 @@ module MCPClient
     end
 
     # Get the current state of a task (tasks/get, MCP 2025-11-25)
-    # @param task_id [String] the ID of the task to query
+    # @param task_id [String, MCPClient::Task] the task to query; passing the
+    #   Task handle returned by #call_tool_as_task routes to its own server
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::Task] the task with current status
+    # @raise [ArgumentError] if the server is ambiguous in a multi-server client
     # @raise [MCPClient::Errors::ServerNotFound] if no server is available
     # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
     # @raise [MCPClient::Errors::TaskError] if retrieving the task fails
     def get_task(task_id, server: nil)
-      srv = select_server(server)
+      srv = select_task_server(task_id, server, 'get_task')
+      task_id = task_identifier(task_id)
 
       begin
         result = srv.rpc_request('tasks/get', { taskId: task_id })
@@ -591,13 +608,16 @@ module MCPClient
     # identify which tool (and therefore which outputSchema) produced the
     # result, and the client keeps no task-to-tool registry. Callers who need
     # validation here can run MCPClient::SchemaValidator.validate themselves.
-    # @param task_id [String] the ID of the task
+    # @param task_id [String, MCPClient::Task] the task; passing the Task
+    #   handle returned by #call_tool_as_task routes to its own server
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [Object] the underlying task result
+    # @raise [ArgumentError] if the server is ambiguous in a multi-server client
     # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
     # @raise [MCPClient::Errors::TaskError] if retrieval fails
     def get_task_result(task_id, server: nil)
-      srv = select_server(server)
+      srv = select_task_server(task_id, server, 'get_task_result')
+      task_id = task_identifier(task_id)
 
       begin
         srv.rpc_request('tasks/result', { taskId: task_id })
@@ -629,14 +649,17 @@ module MCPClient
     end
 
     # Cancel a task (tasks/cancel, MCP 2025-11-25)
-    # @param task_id [String] the ID of the task to cancel
+    # @param task_id [String, MCPClient::Task] the task to cancel; passing the
+    #   Task handle returned by #call_tool_as_task routes to its own server
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::Task] the task with updated (cancelled) status
+    # @raise [ArgumentError] if the server is ambiguous in a multi-server client
     # @raise [MCPClient::Errors::ServerNotFound] if no server is available
     # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
     # @raise [MCPClient::Errors::TaskError] if cancellation fails (including cancelling a terminal task)
     def cancel_task(task_id, server: nil)
-      srv = select_server(server)
+      srv = select_task_server(task_id, server, 'cancel_task')
+      task_id = task_identifier(task_id)
       ensure_task_capability!(srv, 'cancel')
 
       begin
@@ -823,9 +846,10 @@ module MCPClient
       logger_name = params['logger']
       data = params['data']
 
-      # Format the message
-      prefix = logger_name ? "[#{server_id}:#{logger_name}]" : "[#{server_id}]"
-      message = data.is_a?(String) ? data : data.inspect
+      # Format the message. Both the logger name and the payload come from the
+      # remote server, so both are sanitized before they reach the host log.
+      prefix = logger_name ? "[#{server_id}:#{sanitize_peer_log_text(logger_name.to_s)}]" : "[#{server_id}]"
+      message = sanitize_peer_log_text(data.is_a?(String) ? data : data.inspect)
 
       # Map MCP log levels to Ruby Logger levels
       case level.to_s.downcase
@@ -838,10 +862,75 @@ module MCPClient
       when 'error', 'critical', 'alert', 'emergency'
         logger.error("#{prefix} #{message}")
       else
-        logger.info("#{prefix} [#{level}] #{message}")
+        # An out-of-enum level is peer-controlled text like any other: it must
+        # be sanitized and capped, or it becomes the log-forging vector the
+        # sanitizing of `data` was added to close.
+        logger.info("#{prefix} [#{sanitize_peer_log_text(level.to_s)}] #{message}")
       end
     end
 
+    # Make peer-supplied log text safe to write to the host log: control
+    # characters (notably newlines, which would let a server forge additional
+    # log entries) are escaped, and the result is capped.
+    # @param text [String] the peer-supplied text
+    # @return [String] sanitized, length-bounded text
+    def sanitize_peer_log_text(text)
+      escaped = text.gsub(/[-]/) { |c| format('\\x%02X', c.ord) }
+      return escaped if escaped.length <= MAX_PEER_LOG_MESSAGE_LENGTH
+
+      "#{escaped[0, MAX_PEER_LOG_MESSAGE_LENGTH]}... (truncated from #{escaped.length} chars)"
+    end
+
+    # Copy of a server config with credential-bearing values replaced, for
+    # safe logging. Nested hashes (headers, env) have every value redacted;
+    # sensitive scalars are replaced outright.
+    # @param config [Hash, Object] a server configuration
+    # @return [Hash, Object] a redacted copy (non-Hash input is returned as-is)
+    def redact_config(config)
+      return config unless config.is_a?(Hash)
+
+      config.to_h do |key, value|
+        next [key, value] unless SENSITIVE_CONFIG_KEYS.include?(key.to_s.downcase.to_sym)
+
+        redacted = value.is_a?(Hash) ? value.transform_values { REDACTED } : REDACTED
+        [key, redacted]
+      end
+    end
+
+    # Resolve which server a task operation targets.
+    #
+    # Task IDs are only unique within the server that issued them, so silently
+    # defaulting to the first configured server can poll, read or cancel an
+    # unrelated task on the wrong server. Resolution order:
+    #   1. an explicit server: argument wins;
+    #   2. a Task handle carries the server that issued it;
+    #   3. a bare ID with exactly one configured server is unambiguous;
+    #   4. anything else is ambiguous and fails closed.
+    # @param task [String, MCPClient::Task] the task or its ID
+    # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] explicit selector
+    # @param operation [String] calling method name, for the error message
+    # @return [MCPClient::ServerBase]
+    # @raise [ArgumentError] when the target server cannot be determined
+    def select_task_server(task, server_arg, operation)
+      # nil, not falsiness: `server: false` is an invalid selector that
+      # select_server rejects with ArgumentError, and treating it as "omitted"
+      # would silently route a read or a cancel somewhere instead of failing.
+      return select_server(server_arg) unless server_arg.nil?
+      return task.server if task.is_a?(MCPClient::Task) && task.server
+      return select_server(nil) if @servers.size <= 1
+
+      raise ArgumentError,
+            "#{operation} is ambiguous with multiple servers configured: task IDs are only unique per server. " \
+            'Pass the Task returned by call_tool_as_task, or name the server explicitly ' \
+            "(e.g. #{operation}(id, server: 'name'))."
+    end
+
+    # @param task [String, MCPClient::Task] a task or its ID
+    # @return [String] the task ID
+    def task_identifier(task)
+      task.is_a?(MCPClient::Task) ? task.task_id : task
+    end
+
     # Select a server based on index, name, type, or instance
     # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::ServerBase]
@@ -1161,9 +1250,13 @@ module MCPClient
 
         format_elicitation_response(result, params)
       rescue StandardError => e
+        # Same reasoning as the sampling path: the handler's exception text is
+        # host-internal and must not cross to the server. Because this rescue
+        # runs inside the client, the transports' constant-message rescues
+        # never see it — so it has to be constant here.
         @logger.error("Elicitation handler error: #{e.message}")
         @logger.debug(e.backtrace.join("\n"))
-        jsonrpc_error_result(-32_603, "Elicitation handler error: #{e.message}")
+        jsonrpc_error_result(-32_603, 'Elicitation handler error')
       end
     end
 
@@ -1387,8 +1480,10 @@ module MCPClient
         @logger.debug(e.backtrace.join("\n"))
         # A handler exception is an internal client failure (-32603), not a
         # user rejection: sampling.mdx § Error Handling reserves -1 for
-        # "User rejected sampling request".
-        jsonrpc_error_result(-32_603, "Sampling error: #{e.message}")
+        # "User rejected sampling request". The exception message itself is
+        # host-internal (file paths, connection strings, library internals)
+        # and stays in the local log rather than crossing to the server.
+        jsonrpc_error_result(-32_603, 'Sampling error')
       end
     end
 

data/lib/mcp_client/elicitation_validator.rb

@@ -18,6 +18,18 @@ module MCPClient
     # Allowed string formats per MCP spec
     STRING_FORMATS = %w[email uri date date-time].freeze
 
+    # Wall-clock budget for ALL pattern matching in a single validate_content
+    # call. The requestedSchema comes from the remote server, so an expensive
+    # expression must not be able to monopolize the calling thread.
+    #
+    # The budget covers the whole operation, not each match: a per-match limit
+    # multiplies, since the server also controls how many fields it declares.
+    PATTERN_MATCH_TIMEOUT = 1.0
+
+    # Floor for an individual match, so a nearly-exhausted budget still makes
+    # progress rather than failing every remaining field.
+    MIN_PATTERN_MATCH_TIMEOUT = 0.01
+
     # Validate that a requestedSchema conforms to MCP elicitation constraints.
     # Returns an array of error messages (empty if valid).
     # @param schema [Hash] the requestedSchema
@@ -118,6 +130,9 @@ module MCPClient
       errors = []
       return errors unless content.is_a?(Hash) && schema.is_a?(Hash)
 
+      # One deadline covers every field's pattern in this call.
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PATTERN_MATCH_TIMEOUT
+
       properties = schema['properties'] || {}
       required = Array(schema['required'])
 
@@ -132,7 +147,7 @@ module MCPClient
         prop = properties[field.to_s]
         next unless prop.is_a?(Hash)
 
-        errors.concat(validate_value(field.to_s, value, prop))
+        errors.concat(validate_value(field.to_s, value, prop, deadline))
       end
 
       errors
@@ -143,13 +158,13 @@ module MCPClient
     # @param value [Object] the value to validate
     # @param prop [Hash] property schema
     # @return [Array<String>] validation errors
-    def self.validate_value(field, value, prop)
+    def self.validate_value(field, value, prop, deadline = nil)
       errors = []
       type = prop['type']
 
       case type
       when 'string'
-        errors.concat(validate_string_value(field, value, prop))
+        errors.concat(validate_string_value(field, value, prop, deadline))
       when 'number', 'integer'
         errors.concat(validate_number_value(field, value, prop))
       when 'boolean'
@@ -166,7 +181,7 @@ module MCPClient
     # @param value [Object] the value
     # @param prop [Hash] property schema
     # @return [Array<String>] validation errors
-    def self.validate_string_value(field, value, prop)
+    def self.validate_string_value(field, value, prop, deadline = nil)
       errors = []
 
       unless value.is_a?(String)
@@ -183,15 +198,7 @@ module MCPClient
         errors << "Field '#{field}' must be one of: #{allowed.join(', ')}" unless allowed.include?(value)
       end
 
-      if prop['pattern']
-        begin
-          unless value.match?(Regexp.new(prop['pattern']))
-            errors << "Field '#{field}' must match pattern '#{prop['pattern']}'"
-          end
-        rescue RegexpError
-          # Skip pattern validation if the pattern is invalid
-        end
-      end
+      errors.concat(validate_string_pattern(field, value, prop['pattern'], deadline)) if prop['pattern']
 
       if prop['minLength'] && value.length < prop['minLength']
         errors << "Field '#{field}' must be at least #{prop['minLength']} characters"
@@ -206,6 +213,42 @@ module MCPClient
       errors
     end
 
+    # Validate a string value against the schema's regular-expression pattern.
+    # An invalid pattern is not enforced (unchanged behavior), but matching
+    # runs under PATTERN_MATCH_TIMEOUT because the pattern comes from the
+    # remote server. A match that exceeds the budget is reported as a
+    # validation error rather than silently accepted — the value was never
+    # shown to satisfy the constraint.
+    # @param field [String] field name
+    # @param value [String] the value
+    # @param pattern [String] the declared pattern
+    # @return [Array<String>] validation errors
+    def self.validate_string_pattern(field, value, pattern, deadline = nil)
+      remaining = pattern_budget_remaining(deadline)
+      return ["Field '#{field}' pattern matching budget exhausted"] if remaining.zero?
+
+      return [] if value.match?(Regexp.new(pattern, timeout: remaining))
+
+      ["Field '#{field}' must match pattern '#{pattern}'"]
+    rescue Regexp::TimeoutError
+      ["Field '#{field}' pattern '#{pattern}' exceeded the #{PATTERN_MATCH_TIMEOUT}s matching budget"]
+    rescue RegexpError
+      # Skip pattern validation if the pattern is invalid
+      []
+    end
+
+    # Time left in the validation-wide pattern budget.
+    # @param deadline [Float, nil] monotonic deadline, or nil for a lone match
+    # @return [Float] seconds available for the next match; 0.0 when exhausted
+    def self.pattern_budget_remaining(deadline)
+      return PATTERN_MATCH_TIMEOUT unless deadline
+
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return 0.0 if remaining <= 0
+
+      [remaining, MIN_PATTERN_MATCH_TIMEOUT].max
+    end
+
     # Validate a string value against the schema's format constraint.
     # The MCP elicitation schema supports email, uri, date, and date-time.
     # @param field [String] field name

data/lib/mcp_client/errors.rb

@@ -77,6 +77,14 @@ module MCPClient
     # sender SHOULD cancel and stop waiting, not re-send).
     class RequestTimeoutError < TransportError; end
 
+    # Raised when a response body exceeded the configured size limit (e.g. a
+    # gzip payload that expands past the decompression ceiling). A subclass of
+    # TransportError so existing rescues keep working, but deliberately
+    # excluded from automatic retries: the server already received and
+    # processed the request, so re-sending it could run a non-idempotent
+    # operation again — and would decompress the oversized body each time.
+    class ResponseTooLargeError < TransportError; end
+
     # Raised when tool parameters fail validation against the tool's input
     # schema, or (in strict mode) when a tool result's structuredContent fails
     # validation against the tool's output schema