ruby-mcp-client 1.0.1 → 1.1.0

data/lib/mcp_client/client.rb

@@ -27,9 +27,18 @@ module MCPClient
     # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18)
     # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-11-25)
     def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil, roots: nil, sampling_handler: nil)
-      @logger = logger || Logger.new($stdout, level: Logger::WARN)
-      @logger.progname = self.class.name
-      @logger.formatter = proc { |severity, _datetime, progname, msg| "#{severity} [#{progname}] #{msg}\n" }
+      # Preserve a caller-supplied logger's formatter (only tag progname), and
+      # install the default formatter solely on a logger we create ourselves.
+      # Overwriting the formatter of an application's logger would silently
+      # reformat every log line it emits elsewhere.
+      if logger
+        @logger = logger
+        @logger.progname = self.class.name
+      else
+        @logger = Logger.new($stdout, level: Logger::WARN)
+        @logger.progname = self.class.name
+        @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}")
         MCPClient::ServerFactory.create(config, logger: @logger)
@@ -281,6 +290,7 @@ module MCPClient
 
       # Validate parameters against tool schema
       validate_params!(tool, parameters)
+      reject_task_required!(tool, tool_name)
 
       # Use the tool's associated server
       server = tool.server
@@ -426,6 +436,7 @@ module MCPClient
 
       # Validate parameters against tool schema
       validate_params!(tool, parameters)
+      reject_task_required!(tool, tool_name)
 
       # Use the tool's associated server
       server = tool.server
@@ -497,32 +508,59 @@ module MCPClient
       srv.complete(ref: ref, argument: argument, context: context)
     end
 
-    # Create a new task on a server (MCP 2025-11-25)
-    # Tasks represent long-running operations that can report progress
-    # @param method [String] the method to execute as a task
-    # @param params [Hash] parameters for the task method
-    # @param progress_token [String, nil] optional token for receiving progress notifications
-    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the created task
-    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
-    # @raise [MCPClient::Errors::TaskError] if task creation fails
-    def create_task(method, params: {}, progress_token: nil, server: nil)
-      srv = select_server(server)
-      rpc_params = { method: method, params: params }
-      rpc_params[:progressToken] = progress_token if progress_token
+    # Call a tool as a task (task-augmented tools/call, MCP 2025-11-25).
+    #
+    # Instead of blocking for the result, the server accepts the request and
+    # immediately returns a task handle; the actual result is retrieved later
+    # via {#get_task_result} once the task reaches a terminal status. The server
+    # must advertise the tasks.requests.tools.call capability, and the tool must
+    # declare execution.taskSupport of 'optional' or 'required'.
+    # @param tool_name [String] the name of the tool to call
+    # @param parameters [Hash] the parameters to pass to the tool
+    # @param ttl [Integer, nil] optional requested task lifetime in milliseconds
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
+    # @return [MCPClient::Task] the created task (status typically 'working')
+    # @raise [MCPClient::Errors::ToolNotFound] if the tool is not found
+    # @raise [MCPClient::Errors::ValidationError] if required parameters are missing
+    # @raise [MCPClient::Errors::TaskError] if the server or tool does not support tasks, or creation fails
+    def call_tool_as_task(tool_name, parameters, ttl: nil, server: nil)
+      tool = resolve_tool(tool_name, server: server)
+      validate_params!(tool, parameters)
+
+      srv = tool.server
+      raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless srv
+
+      unless server_supports_task_tool_call?(srv)
+        raise MCPClient::Errors::TaskError,
+              'Server does not support task-augmented tools/call (no tasks.requests.tools.call capability)'
+      end
+      unless tool.supports_task?
+        raise MCPClient::Errors::TaskError,
+              "Tool '#{tool_name}' does not support task execution (execution.taskSupport is forbidden/unset)"
+      end
+
+      task_params = {}
+      task_params[:ttl] = ttl if ttl
+      # Keep _meta (string or symbol key) as a top-level request field rather
+      # than a tool argument, so request metadata is preserved and does not fail
+      # tool input-schema validation.
+      meta_key = [:_meta, '_meta'].find { |k| parameters.key?(k) }
+      arguments = meta_key ? parameters.reject { |k, _| k == meta_key } : parameters
+      rpc_params = { name: tool_name, arguments: arguments, task: task_params }
+      rpc_params[:_meta] = parameters[meta_key] if meta_key
 
       begin
-        result = srv.rpc_request('tasks/create', rpc_params)
-        MCPClient::Task.from_json(result, server: srv)
+        result = srv.rpc_request('tools/call', rpc_params)
+        MCPClient::Task.from_create_result(result, server: srv)
       rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error creating task: #{e.message}"
+        raise MCPClient::Errors::TaskError, "Error creating task for tool '#{tool_name}': #{e.message}"
       end
     end
 
-    # Get the current state of a task (MCP 2025-11-25)
+    # 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 server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the task with current state
+    # @return [MCPClient::Task] the task with current status
     # @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
@@ -530,38 +568,75 @@ module MCPClient
       srv = select_server(server)
 
       begin
-        result = srv.rpc_request('tasks/get', { id: task_id })
+        result = srv.rpc_request('tasks/get', { taskId: task_id })
         MCPClient::Task.from_json(result, server: srv)
       rescue MCPClient::Errors::ServerError => e
-        if e.message.include?('not found') || e.message.include?('unknown task')
-          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
-        end
-
-        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
+        raise task_error_from(e, task_id, 'getting')
       rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
         raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
       end
     end
 
-    # Cancel a running task (MCP 2025-11-25)
+    # Retrieve the result of a completed task (tasks/result, MCP 2025-11-25).
+    # Returns exactly what the underlying request would have returned (e.g. a
+    # CallToolResult hash with 'content'/'isError'/'structuredContent'); it is
+    # NOT wrapped in a Task. Blocks on the server until the task is terminal.
+    # @param task_id [String] the ID of the task
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Object] the underlying task result
+    # @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)
+
+      begin
+        srv.rpc_request('tasks/result', { taskId: task_id })
+      rescue MCPClient::Errors::ServerError => e
+        raise task_error_from(e, task_id, 'getting result for')
+      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error getting result for task '#{task_id}': #{e.message}"
+      end
+    end
+
+    # List tasks known to a server (tasks/list, paginated, MCP 2025-11-25)
+    # @param cursor [String, nil] optional pagination cursor
+    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
+    # @return [Hash] { tasks: Array<MCPClient::Task>, next_cursor: String, nil }
+    # @raise [MCPClient::Errors::TaskError] if listing fails
+    def list_tasks(cursor: nil, server: nil)
+      srv = select_server(server)
+      params = cursor ? { cursor: cursor } : {}
+
+      begin
+        result = srv.rpc_request('tasks/list', params) || {}
+        tasks = (result['tasks'] || []).map { |t| MCPClient::Task.from_json(t, server: srv) }
+        { tasks: tasks, next_cursor: result['nextCursor'] }
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
+        raise MCPClient::Errors::TaskError, "Error listing tasks: #{e.message}"
+      end
+    end
+
+    # Cancel a task (tasks/cancel, MCP 2025-11-25)
     # @param task_id [String] the ID of the task to cancel
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the task with updated (cancelled) state
+    # @return [MCPClient::Task] the task with updated (cancelled) status
     # @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
+    # @raise [MCPClient::Errors::TaskError] if cancellation fails (including cancelling a terminal task)
     def cancel_task(task_id, server: nil)
       srv = select_server(server)
 
       begin
-        result = srv.rpc_request('tasks/cancel', { id: task_id })
+        result = srv.rpc_request('tasks/cancel', { taskId: task_id })
         MCPClient::Task.from_json(result, server: srv)
       rescue MCPClient::Errors::ServerError => e
-        if e.message.include?('not found') || e.message.include?('unknown task')
-          raise MCPClient::Errors::TaskNotFound, "Task '#{task_id}' not found"
+        # A terminal task cannot be cancelled (-32602); that is an error, not a
+        # missing task, so keep it as a TaskError.
+        if e.message.match?(/terminal/i)
+          raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
         end
 
-        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+        raise task_error_from(e, task_id, 'cancelling')
       rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
         raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
       end
@@ -601,6 +676,9 @@ module MCPClient
       when 'notifications/message'
         # MCP 2025-06-18: Handle logging messages from server
         handle_log_message(server_id, params)
+      when 'notifications/tasks/status'
+        # MCP 2025-11-25: task status update (params are a flat Task)
+        handle_task_status_notification(server_id, params)
       else
         # Log unknown notification types for debugging purposes
         logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
@@ -700,6 +778,91 @@ module MCPClient
       end
     end
 
+    # Resolve a tool by name (optionally scoped to a server), raising the same
+    # not-found / ambiguity errors as call_tool.
+    # @param tool_name [String] the tool name
+    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server selector
+    # @return [MCPClient::Tool] the resolved tool
+    # @raise [MCPClient::Errors::ToolNotFound, MCPClient::Errors::AmbiguousToolName]
+    def resolve_tool(tool_name, server: nil)
+      tools = list_tools
+
+      if server
+        srv = select_server(server)
+        tool = tools.find { |t| t.name == tool_name && t.server == srv }
+        unless tool
+          raise MCPClient::Errors::ToolNotFound,
+                "Tool '#{tool_name}' not found on server '#{srv.name || srv.class.name}'"
+        end
+        return tool
+      end
+
+      matching_tools = tools.select { |t| t.name == tool_name }
+      if matching_tools.empty?
+        raise MCPClient::Errors::ToolNotFound, "Tool '#{tool_name}' not found"
+      elsif matching_tools.size > 1
+        server_names = matching_tools.map { |t| t.server&.name || 'unnamed' }
+        raise MCPClient::Errors::AmbiguousToolName,
+              "Multiple tools named '#{tool_name}' found across servers (#{server_names.join(', ')}). " \
+              "Please specify a server using the 'server' parameter."
+      end
+
+      matching_tools.first
+    end
+
+    # Reject a plain (synchronous) call for a tool whose execution.taskSupport is
+    # 'required'. A compliant server would reject a non-task-augmented tools/call
+    # for such a tool, so fail fast and point the caller at call_tool_as_task.
+    # @param tool [MCPClient::Tool] the resolved tool
+    # @param tool_name [String] the tool name (for the message)
+    # @raise [MCPClient::Errors::ToolCallError] if the tool requires task execution
+    def reject_task_required!(tool, tool_name)
+      return unless tool.task_required?
+
+      raise MCPClient::Errors::ToolCallError,
+            "Tool '#{tool_name}' requires task-augmented execution; call it with call_tool_as_task instead"
+    end
+
+    # Whether a server advertised support for task-augmented tools/call, i.e.
+    # capabilities.tasks.requests.tools.call.
+    # @param srv [MCPClient::ServerBase] the server
+    # @return [Boolean]
+    def server_supports_task_tool_call?(srv)
+      caps = srv.respond_to?(:capabilities) ? srv.capabilities : nil
+      return false unless caps.is_a?(Hash)
+
+      tasks = caps['tasks'] || caps[:tasks]
+      requests = tasks && (tasks['requests'] || tasks[:requests])
+      tools = requests && (requests['tools'] || requests[:tools])
+      call = tools && (tools['call'] || tools[:call])
+      !call.nil?
+    end
+
+    # Map a ServerError from a task operation to TaskNotFound or TaskError.
+    # @param error [MCPClient::Errors::ServerError] the server error
+    # @param task_id [String] the task id
+    # @param action [String] a verb phrase for the error message (e.g. 'getting')
+    # @return [MCPClient::Errors::TaskNotFound, MCPClient::Errors::TaskError]
+    def task_error_from(error, task_id, action)
+      if error.message.match?(/not found|unknown task|expired/i)
+        return MCPClient::Errors::TaskNotFound.new("Task '#{task_id}' not found")
+      end
+
+      MCPClient::Errors::TaskError.new("Error #{action} task '#{task_id}': #{error.message}")
+    end
+
+    # Handle a notifications/tasks/status notification (MCP 2025-11-25).
+    # The params are a flat Task.
+    # @param server_id [String] server identifier for the log prefix
+    # @param params [Hash] the flat task params
+    # @return [void]
+    def handle_task_status_notification(server_id, params)
+      task = MCPClient::Task.from_json(params)
+      logger.info("[#{server_id}] Task #{task.task_id} status: #{task.status}")
+    rescue StandardError => e
+      logger.debug("[#{server_id}] Failed to parse task status notification: #{e.message}")
+    end
+
     # Generate a cache key for server-specific items
     # @param server [MCPClient::ServerBase] the server
     # @param item_id [String] the item identifier (name or URI)

data/lib/mcp_client/errors.rb

@@ -33,6 +33,15 @@ module MCPClient
     # Raised when the MCP server returns an error response
     class ServerError < MCPError; end
 
+    # Raised for a server-side failure that is plausibly transient and safe to
+    # retry — chiefly HTTP 5xx responses, where the request likely did not
+    # complete at the application layer. It is a subclass of ServerError so that
+    # existing `rescue MCPClient::Errors::ServerError` handlers keep catching it,
+    # while the retry logic can single it out. Application-level failures
+    # (JSON-RPC error responses, HTTP 4xx) use plain ServerError and are NOT
+    # retried, since the server already processed/rejected the request.
+    class TransientServerError < ServerError; end
+
     # Raised when there's an error in the MCP server transport
     class TransportError < MCPError; end
 

data/lib/mcp_client/http_transport_base.rb

@@ -243,9 +243,13 @@ module MCPClient
       when 401, 403
         raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{response.status}"
       when 400..499
+        # Deterministic client errors: the request was processed/rejected and
+        # will not succeed on retry, so raise a plain (non-retryable) ServerError.
         raise MCPClient::Errors::ServerError, "Client error: HTTP #{response.status}#{reason_text}"
       when 500..599
-        raise MCPClient::Errors::ServerError, "Server error: HTTP #{response.status}#{reason_text}"
+        # Server-side failures are plausibly transient: raise the retryable
+        # subclass so with_retry can re-attempt them.
+        raise MCPClient::Errors::TransientServerError, "Server error: HTTP #{response.status}#{reason_text}"
       else
         raise MCPClient::Errors::ServerError, "HTTP error: #{response.status}#{reason_text}"
       end

data/lib/mcp_client/json_rpc_common.rb

@@ -3,16 +3,26 @@
 module MCPClient
   # Shared retry/backoff logic for JSON-RPC transports
   module JsonRpcCommon
-    # Execute the block with retry/backoff for transient errors
+    # Execute the block with retry/backoff for transient errors only.
+    #
+    # Retries genuinely transient failures where the request most likely did not
+    # complete at the server: transport/network errors (TransportError, IOError,
+    # Errno::ETIMEDOUT/ECONNRESET/EPIPE) and TransientServerError (HTTP 5xx).
+    #
+    # It deliberately does NOT retry a plain ServerError. A plain ServerError is
+    # raised for a JSON-RPC error response or an HTTP 4xx — cases where the
+    # server received and processed (or deterministically rejected) the request.
+    # Re-sending those would silently re-execute a non-idempotent operation
+    # (e.g. a tools/call), which JSON-RPC provides no way to make safe.
     # @yield block to execute
     # @return [Object] result of block
-    # @raise original exception if max retries exceeded
+    # @raise original exception if max retries exceeded or the error is not retryable
     def with_retry
       attempts = 0
       begin
         yield
-      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, IOError, Errno::ETIMEDOUT,
-             Errno::ECONNRESET => e
+      rescue MCPClient::Errors::TransientServerError, MCPClient::Errors::TransportError, IOError,
+             Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EPIPE => e
         attempts += 1
         if attempts <= @max_retries
           delay = @retry_backoff * (2**(attempts - 1))
@@ -66,6 +76,11 @@ module MCPClient
         'elicitation' => {}, # MCP 2025-11-25: Support for server-initiated user interactions
         'roots' => { 'listChanged' => true }, # MCP 2025-11-25: Support for roots
         'sampling' => {} # MCP 2025-11-25: Support for server-initiated LLM sampling
+        # NOTE: we intentionally do NOT declare a client `tasks` capability. That
+        # capability marks the client as a RECEIVER of task-augmented
+        # sampling/elicitation requests, which is not implemented here — this
+        # client only acts as a task REQUESTOR for tools/call (see
+        # Client#call_tool_as_task), which requires no client-side declaration.
       }
 
       {

data/lib/mcp_client/server_base.rb

@@ -133,8 +133,81 @@ module MCPClient
       @notification_callback = block
     end
 
+    # Safety bound on the number of pages followed when auto-paginating a
+    # cursor-based list operation, to protect against a server that returns
+    # a nextCursor indefinitely.
+    MAX_LIST_PAGES = 1000
+
     protected
 
+    # Follow cursor-based pagination across pages, collecting every item.
+    #
+    # Yields the current cursor (nil for the first page) and expects the block
+    # to return a two-element array: [items_for_this_page, next_cursor]. The
+    # loop stops when next_cursor is nil or empty, when a cursor repeats
+    # (malformed server), or when MAX_LIST_PAGES pages have been fetched.
+    #
+    # @param kind [String] label used in diagnostic log messages
+    # @yieldparam cursor [String, nil] cursor for the page to fetch
+    # @yieldreturn [Array(Array, String), Array(Array, nil)] page items and next cursor
+    # @return [Array] all items collected across pages
+    def collect_paginated(kind = 'items')
+      items = []
+      cursor = nil
+      seen_cursors = {}
+      pages = 0
+
+      loop do
+        page_items, next_cursor = yield(cursor)
+        items.concat(Array(page_items))
+        pages += 1
+
+        break if next_cursor.nil? || next_cursor.to_s.empty?
+
+        if seen_cursors[next_cursor]
+          @logger.warn("Pagination for #{kind} stopped: server returned a repeated cursor #{next_cursor.inspect}")
+          break
+        end
+        if pages >= MAX_LIST_PAGES
+          @logger.warn("Pagination for #{kind} stopped after #{pages} pages (safety bound reached)")
+          break
+        end
+
+        seen_cursors[next_cursor] = true
+        cursor = next_cursor
+      end
+
+      items
+    end
+
+    # Fetch a full, cursor-paginated list result via rpc_request, following
+    # nextCursor across pages until the server stops returning one.
+    #
+    # Accepts either a spec-shaped Hash ({ key => [...], 'nextCursor' => ... })
+    # or, leniently, a bare Array (a single unpaginated page). A response that
+    # is neither (e.g. a null/missing result or a scalar) is a malformed list
+    # response and raises, rather than being silently treated as an empty list.
+    #
+    # @param method [String] the list method, e.g. 'tools/list'
+    # @param key [String] the result array key, e.g. 'tools'
+    # @return [Array<Hash>] all raw item hashes collected across pages
+    # @raise [MCPClient::Errors::TransportError] if a page result is not a Hash or Array
+    def request_paginated_list(method, key)
+      collect_paginated(key) do |cursor|
+        params = cursor ? { cursor: cursor } : {}
+        result = rpc_request(method, params)
+        case result
+        when Hash
+          [result[key] || [], result['nextCursor']]
+        when Array
+          [result, nil]
+        else
+          raise MCPClient::Errors::TransportError,
+                "Invalid #{method} response: expected an object or array, got #{result.class}"
+        end
+      end
+    end
+
     # Initialize logger with proper formatter handling
     # Preserves custom formatter if logger is provided, otherwise sets a default formatter
     # @param logger [Logger, nil] custom logger to use, or nil to create a default one

data/lib/mcp_client/server_http.rb

@@ -246,8 +246,8 @@ module MCPClient
       begin
         ensure_connected
 
-        prompts_data = rpc_request('prompts/list')
-        prompts = prompts_data['prompts'] || []
+        # Follow nextCursor across pages so the full prompt list is returned.
+        prompts = request_paginated_list('prompts/list', 'prompts')
 
         @mutex.synchronize do
           @prompts = prompts.map do |prompt_data|
@@ -448,6 +448,25 @@ module MCPClient
 
     private
 
+    # Perform the MCP initialize handshake, then announce readiness.
+    #
+    # The base handshake sends the initialize request and captures
+    # serverInfo/capabilities. Per the MCP lifecycle the client MUST send an
+    # `initialized` notification after a successful initialize before issuing
+    # any other requests; the plain HTTP transport previously skipped it.
+    # @return [void]
+    # @raise [MCPClient::Errors::TransportError] if the notification fails to send
+    def perform_initialize
+      super
+
+      notification = build_jsonrpc_notification('notifications/initialized', {})
+      begin
+        send_http_request(notification)
+      rescue MCPClient::Errors::ServerError, MCPClient::Errors::ConnectionError, Faraday::ConnectionFailed => e
+        raise MCPClient::Errors::TransportError, "Failed to send initialized notification: #{e.message}"
+      end
+    end
+
     # Default options for server initialization
     # @return [Hash] Default options
     def default_options
@@ -497,24 +516,15 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] if tools list retrieval fails
     def request_tools_list
       @mutex.synchronize do
-        return @tools_data if @tools_data
+        return @tools_data.dup if @tools_data
       end
 
-      result = rpc_request('tools/list')
-
-      if result && result['tools']
-        @mutex.synchronize do
-          @tools_data = result['tools']
-        end
-        return @mutex.synchronize { @tools_data.dup }
-      elsif result
-        @mutex.synchronize do
-          @tools_data = result
-        end
-        return @mutex.synchronize { @tools_data.dup }
-      end
+      # Follow nextCursor across pages so the full tool list is returned even
+      # when the server paginates.
+      tools = request_paginated_list('tools/list', 'tools')
 
-      raise MCPClient::Errors::ToolCallError, 'Failed to get tools list from JSON-RPC request'
+      @mutex.synchronize { @tools_data = tools }
+      @mutex.synchronize { @tools_data.dup }
     end
   end
 end

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -126,7 +126,10 @@ module MCPClient
           record_activity
 
           unless response.success?
-            raise MCPClient::Errors::ServerError, "Server returned error: #{response.status} #{response.reason_phrase}"
+            # 5xx failures are plausibly transient (retryable); 4xx and other
+            # statuses are deterministic and raise a plain (non-retryable) error.
+            error_class = (500..599).cover?(response.status) ? MCPClient::Errors::TransientServerError : MCPClient::Errors::ServerError
+            raise error_class, "Server returned error: #{response.status} #{response.reason_phrase}"
           end
 
           response

data/lib/mcp_client/server_sse/reconnect_monitor.rb

@@ -88,6 +88,10 @@ module MCPClient
 
             cleanup
 
+            # Clear any stale auth error from the previous connection so it does
+            # not spuriously abort this reconnect via wait_for_connection.
+            @mutex.synchronize { @auth_error = nil }
+
             connect
             @logger.info('Successfully reconnected after ping failures')
 

data/lib/mcp_client/server_sse/sse_parser.rb

@@ -85,9 +85,12 @@ module MCPClient
       def process_response?(data)
         return false unless data['id']
 
+        # Deliver the response to the waiting caller via @sse_results only.
+        # We intentionally do NOT write @tools_data here: request_tools_list is
+        # the sole writer of that cache and sets it to the COMPLETE, fully
+        # paginated list. Writing each page as it arrives would let a concurrent
+        # list_tools observe a partial (page-1-only) cache mid-pagination.
         @mutex.synchronize do
-          @tools_data = data['result']['tools'] if data['result'] && data['result']['tools']
-
           @sse_results[data['id']] =
             if data['error']
               { 'isError' => true,