ruby-mcp-client 1.0.1 → 2.0.0

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -16,16 +16,35 @@ module MCPClient
       # @raise [MCPClient::Errors::ServerError] if server returns an error
       # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
       # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
-      def rpc_request(method, params = {})
+      def rpc_request(method, params = {}, timeout: nil)
         ensure_initialized
 
         with_retry do
           request_id = @mutex.synchronize { @request_id += 1 }
           request = build_jsonrpc_request(method, params, request_id)
-          send_jsonrpc_request(request)
+          begin
+            send_jsonrpc_request(request, timeout: timeout)
+          rescue MCPClient::Errors::RequestTimeoutError
+            # MCP lifecycle: on timeout the sender SHOULD issue a cancellation
+            # notification for the abandoned request and stop waiting.
+            send_cancellation_notification(request_id) if cancellable_request?(method, params)
+            raise
+          end
         end
       end
 
+      # Best-effort notifications/cancelled for a request the client stopped
+      # waiting on. Failures are swallowed.
+      # @param request_id [Integer] id of the abandoned request
+      # @return [void]
+      def send_cancellation_notification(request_id)
+        notif = build_jsonrpc_notification('notifications/cancelled',
+                                           { 'requestId' => request_id, 'reason' => 'Request timed out' })
+        post_json_rpc_request(notif)
+      rescue StandardError => e
+        @logger.debug("Failed to send cancellation notification: #{e.message}")
+      end
+
       # Send a JSON-RPC notification (no response expected)
       # @param method [String] JSON-RPC method name
       # @param params [Hash] parameters for the notification
@@ -62,15 +81,28 @@ module MCPClient
 
       # Perform JSON-RPC initialize handshake with the MCP server
       # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if the initialize result is malformed
       def perform_initialize
         request_id = @mutex.synchronize { @request_id += 1 }
         json_rpc_request = build_jsonrpc_request('initialize', initialization_params, request_id)
         @logger.debug("Performing initialize RPC: #{json_rpc_request}")
         result = send_jsonrpc_request(json_rpc_request)
-        return unless result.is_a?(Hash)
+        unless result.is_a?(Hash)
+          # A non-object initialize result means the handshake did not succeed.
+          # Continuing would enter the Operation phase without ever sending the
+          # mandatory notifications/initialized (MCP lifecycle "Initialization":
+          # "After successful initialization, the client MUST send an
+          # `initialized` notification"), so fail the connection instead.
+          cleanup
+          raise MCPClient::Errors::ConnectionError,
+                "Invalid initialize response from server: expected an object, got #{result.inspect}"
+        end
 
+        # Disconnects if the server negotiated a version we cannot speak.
+        @protocol_version = validate_protocol_version!(result)
         @server_info = result['serverInfo']
         @capabilities = result['capabilities']
+        @instructions = result['instructions']
 
         # Send initialized notification to acknowledge completion of initialization
         initialized_notification = build_jsonrpc_notification('notifications/initialized', {})
@@ -86,7 +118,7 @@ module MCPClient
       # @raise [MCPClient::Errors::ConnectionError] if connection fails
       # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
       # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
-      def send_jsonrpc_request(request)
+      def send_jsonrpc_request(request, timeout: nil)
         @logger.debug("Sending JSON-RPC request: #{request.to_json}")
         record_activity
 
@@ -94,7 +126,7 @@ module MCPClient
           response = post_json_rpc_request(request)
 
           if @use_sse
-            wait_for_sse_result(request)
+            wait_for_sse_result(request, timeout: timeout)
           else
             parse_direct_response(response)
           end
@@ -126,10 +158,15 @@ 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
+        rescue Faraday::TimeoutError => e
+          raise MCPClient::Errors::RequestTimeoutError, "Request timed out: #{e.message}"
         rescue Faraday::ConnectionFailed => e
           raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
         end
@@ -157,6 +194,11 @@ module MCPClient
         response = conn.post(endpoint) do |req|
           req.headers['Content-Type'] = 'application/json'
           req.headers['Accept'] = 'application/json'
+          # MCP lifecycle "Version Negotiation": the client MUST include the
+          # MCP-Protocol-Version header on all requests after the initialize
+          # handshake. The guard naturally skips the initialize POST itself,
+          # since the negotiated version is only known from its result.
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           (@headers.dup.tap do |h|
             h.delete('Accept')
             h.delete('Cache-Control')
@@ -174,10 +216,10 @@ module MCPClient
       # @param request [Hash] the original JSON-RPC request
       # @return [Hash] the result data
       # @raise [MCPClient::Errors::ConnectionError, MCPClient::Errors::ToolCallError] on errors
-      def wait_for_sse_result(request)
+      def wait_for_sse_result(request, timeout: nil)
         request_id = request['id']
         start_time = Time.now
-        timeout = @read_timeout || 10
+        timeout ||= @read_timeout || 10
 
         ensure_sse_connection_active
 
@@ -219,12 +261,13 @@ module MCPClient
           sleep 0.1
         end
 
-        raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
+        raise MCPClient::Errors::RequestTimeoutError, "Timeout waiting for SSE result for request #{request_id}"
       end
 
       # Check if a result is available for the given request ID
       # @param request_id [Integer] the request ID to check
       # @return [Hash, nil] the result if available, nil otherwise
+      # @raise [MCPClient::Errors::ServerError] if the stored result is a JSON-RPC error response
       def check_for_result(request_id)
         result = nil
         @mutex.synchronize do
@@ -233,12 +276,27 @@ module MCPClient
 
         if result
           record_activity
+          # SseParser#process_response? stores JSON-RPC error responses under
+          # the Symbol :error key; deliver them to the caller as ServerError
+          # (MCP lifecycle "Error Handling") instead of timing out.
+          raise_sse_error_response(result[:error]) if result.is_a?(Hash) && result.key?(:error)
           return result
         end
 
         nil
       end
 
+      # Raise a ServerError for a JSON-RPC error response received over SSE,
+      # mirroring JsonRpcCommon#process_jsonrpc_response for the other transports.
+      # @param error [Hash, nil] the JSON-RPC error object ('code', 'message', 'data')
+      # @raise [MCPClient::Errors::ServerError] always
+      def raise_sse_error_response(error)
+        error ||= {}
+        message = error['message'] || 'Unknown server error'
+        message = "#{message} (code #{error['code']})" if error['code']
+        raise MCPClient::Errors::ServerError, message
+      end
+
       # Parse a direct (non-SSE) JSON-RPC response
       # @param response [Faraday::Response] the HTTP response
       # @return [Hash] the parsed result

data/lib/mcp_client/server_sse/reconnect_monitor.rb

@@ -88,6 +88,14 @@ module MCPClient
 
             cleanup
 
+            # Clear any stale auth/connection error from the previous connection
+            # so it does not spuriously abort this reconnect via
+            # wait_for_connection.
+            @mutex.synchronize do
+              @auth_error = nil
+              @connection_error = nil
+            end
+
             connect
             @logger.info('Successfully reconnected after ping failures')
 
@@ -165,11 +173,14 @@ module MCPClient
           deadline = Time.now + timeout
 
           until @connection_established
+            break if @connection_error
+
             remaining = [1, deadline - Time.now].min
             break if remaining <= 0 || @connection_cv.wait(remaining) { @connection_established }
           end
 
           raise MCPClient::Errors::ConnectionError, @auth_error if @auth_error
+          raise MCPClient::Errors::ConnectionError, @connection_error if @connection_error
 
           unless @connection_established
             cleanup

data/lib/mcp_client/server_sse/sse_parser.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module MCPClient
   class ServerSSE
@@ -30,7 +31,7 @@ module MCPClient
         begin
           data = JSON.parse(event[:data])
 
-          return if process_error_in_message(data)
+          return if process_error_in_message?(data)
           return if process_server_request?(data)
           return if process_notification?(data)
 
@@ -44,11 +45,17 @@ module MCPClient
         end
       end
 
-      # Process a JSON-RPC error() in the SSE stream.
+      # Process a connection-level JSON-RPC error payload in the SSE stream.
+      # Error RESPONSES (id-bearing) belong to a pending request and are
+      # delivered to the waiting caller via process_response? instead, per the
+      # MCP lifecycle "Error Handling" section (implementations SHOULD handle
+      # error cases such as protocol version mismatch), so they must not be
+      # swallowed here.
       # @param data [Hash] the parsed JSON payload
-      # @return [Boolean] true if we saw & handled an error
-      def process_error_in_message(data)
-        return unless data['error']
+      # @return [Boolean] true if we saw & handled an id-less error
+      def process_error_in_message?(data)
+        return false unless data['error']
+        return false if data['id']
 
         error_message = data['error']['message'] || 'Unknown server error'
         error_code    = data['error']['code']
@@ -85,13 +92,18 @@ 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,
-                'content' => [{ 'type' => 'text', 'text' => data['error'].to_json }] }
+              # JSON-RPC error response: store the error under a Symbol key
+              # (JSON.parse only produces String keys, so this cannot collide
+              # with a success result) for the waiter to raise ServerError.
+              { error: data['error'] }
             else
               data['result']
             end
@@ -127,16 +139,44 @@ module MCPClient
         has_content ? event : nil
       end
 
-      # Handle the special "endpoint" control frame (for SSE handshake)
+      # Handle the special "endpoint" control frame (for SSE handshake).
+      # The event data is a URI reference (MCP 2024-11-05 HTTP with SSE: the
+      # server sends "an `endpoint` event containing a URI for the client to
+      # use for sending messages") which must be resolved against the SSE
+      # connection URL per RFC 3986 section 5.1.3, so relative endpoint URIs
+      # POST to the URL the server actually designated.
       # @param data [String] the raw endpoint payload
       def handle_endpoint_event(data)
+        endpoint = resolve_endpoint_uri(data)
         @mutex.synchronize do
-          @rpc_endpoint = data
+          @rpc_endpoint = endpoint
           @sse_connected = true
           @connection_established = true
           @connection_cv.broadcast
         end
       end
+
+      # Resolve an endpoint URI reference against the SSE connection URL
+      # @param data [String] the endpoint event payload (absolute or relative URI)
+      # @return [String] the absolute endpoint URL
+      def resolve_endpoint_uri(data)
+        URI.join(@base_url, data).to_s
+      rescue URI::Error => e
+        # The endpoint event is the handshake's core payload; an unresolvable
+        # URI must fail the handshake rather than deferring a broken POST
+        # target to the first request.
+        @logger.error("Failed to resolve endpoint URI #{data.inspect} against #{@base_url}: #{e.message}")
+        message = "Invalid endpoint URI in SSE endpoint event: #{data.inspect} (#{e.message})"
+        # The SSE worker thread swallows this exception with a generic rescue,
+        # so also record the failure cause (mirroring @auth_error) for the
+        # connect caller blocked in wait_for_connection to surface promptly.
+        @mutex.synchronize do
+          @connection_error = message
+          @connection_established = false
+          @connection_cv.broadcast
+        end
+        raise MCPClient::Errors::TransportError, message
+      end
     end
   end
 end

data/lib/mcp_client/server_sse.rb

@@ -97,7 +97,13 @@ module MCPClient
       @connection_established = false
       @connection_cv = @mutex.new_cond
       @initialized = false
+      # Negotiated protocol version captured from the initialize result
+      # (sent as the MCP-Protocol-Version header on post-initialize requests)
+      @protocol_version = nil
       @auth_error = nil
+      # Non-auth connection failure cause (e.g. invalid endpoint event URI)
+      # recorded by the SSE worker for wait_for_connection to surface
+      @connection_error = nil
       # Whether to use SSE transport; may disable if handshake fails
       @use_sse = true
 
@@ -157,10 +163,7 @@ module MCPClient
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def get_prompt(prompt_name, parameters)
-      rpc_request('prompts/get', {
-                    name: prompt_name,
-                    arguments: parameters
-                  })
+      rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -254,9 +257,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
     def subscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/subscribe')
       rpc_request('resources/subscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
@@ -269,9 +274,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
     def unsubscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
       rpc_request('resources/unsubscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
@@ -315,10 +322,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
-      rpc_request('tools/call', {
-                    name: tool_name,
-                    arguments: parameters
-                  })
+      rpc_request('tools/call', build_named_request_params(tool_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -334,11 +338,14 @@ module MCPClient
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def complete(ref:, argument:, context: nil)
+      ensure_initialized
+      require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
       result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
@@ -350,8 +357,11 @@ module MCPClient
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
+      ensure_initialized
+      require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
@@ -369,6 +379,8 @@ module MCPClient
       begin
         # Don't reset auth error if it's pre-existing
         @mutex.synchronize { @auth_error = nil } unless pre_existing_auth_error
+        # Clear any stale connection failure cause from a previous attempt
+        @mutex.synchronize { @connection_error = nil }
 
         start_sse_thread
         effective_timeout = [@read_timeout || 30, 30].min
@@ -404,29 +416,47 @@ module MCPClient
         @connection_established = false
         @sse_connected = false
         @initialized = false # Reset initialization state for reconnection
+        # A fresh session negotiates its own protocol version; keeping the old
+        # one would leak the previous session's version into the next
+        # initialize POST's MCP-Protocol-Version header.
+        @protocol_version = nil
+
+        # Reset the SSE parse buffer so a reconnect never inherits a leftover
+        # partial event from the previous connection.
+        @buffer = ''
 
         # Log cleanup for debugging
         @logger.debug('Cleaning up SSE connection')
 
         # Store threads locally to avoid race conditions
         sse_thread = @sse_thread
+
+        # The activity monitor drives reconnection, and reconnection calls this
+        # method FROM that thread. Killing the current thread here would abort
+        # the reconnect before connect() runs (the historical dead-code bug), so
+        # never kill/clear the activity thread when we are running on it. Leaving
+        # @activity_timer_thread referenced also makes start_activity_monitor
+        # short-circuit, preventing a duplicate monitor after reconnect.
         activity_thread = @activity_timer_thread
+        kill_activity_thread = activity_thread && activity_thread != Thread.current
 
         # Clear thread references first
         @sse_thread = nil
-        @activity_timer_thread = nil
+        @activity_timer_thread = nil if kill_activity_thread
 
-        # Kill threads outside the critical section
+        # Kill threads
         begin
           sse_thread&.kill
         rescue StandardError => e
           @logger.debug("Error killing SSE thread: #{e.message}")
         end
 
-        begin
-          activity_thread&.kill
-        rescue StandardError => e
-          @logger.debug("Error killing activity thread: #{e.message}")
+        if kill_activity_thread
+          begin
+            activity_thread.kill
+          rescue StandardError => e
+            @logger.debug("Error killing activity thread: #{e.message}")
+          end
         end
 
         if @http_client
@@ -476,6 +506,8 @@ module MCPClient
       @logger.debug("Received server request: #{method} (id: #{request_id})")
 
       case method
+      when 'ping'
+        handle_ping(request_id)
       when 'elicitation/create'
         handle_elicitation_create(request_id, params)
       when 'roots/list'
@@ -491,23 +523,39 @@ module MCPClient
       send_error_response(request_id, -32_603, "Internal error: #{e.message}")
     end
 
+    # Handle a server-initiated ping request (MCP ping utility)
+    # The receiver MUST respond promptly with an empty result.
+    # @param request_id [String, Integer] the JSON-RPC request ID
+    # @return [void]
+    def handle_ping(request_id)
+      response = {
+        'jsonrpc' => '2.0',
+        'id' => request_id,
+        'result' => {}
+      }
+      post_jsonrpc_response(response)
+    rescue StandardError => e
+      @logger.error("Error sending ping response: #{e.message}")
+    end
+
     # Handle elicitation/create request from server (MCP 2025-06-18)
     # @param request_id [String, Integer] the JSON-RPC request ID
     # @param params [Hash] the elicitation parameters
     # @return [void]
     def handle_elicitation_create(request_id, params)
-      # If no callback is registered, decline the request
+      # Without a callback there is no user to interact with: answer with a
+      # JSON-RPC error rather than fabricating a user "decline".
       unless @elicitation_request_callback
-        @logger.warn('Received elicitation request but no callback registered, declining')
-        send_elicitation_response(request_id, { 'action' => 'decline' })
+        @logger.warn('Received elicitation request but no callback registered')
+        send_error_response(request_id, -32_601, 'Elicitation not supported: no handler configured')
         return
       end
 
       # Call the registered callback
       result = @elicitation_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_elicitation_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_elicitation_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Handle roots/list request from server (MCP 2025-06-18)
@@ -525,8 +573,8 @@ module MCPClient
       # Call the registered callback
       result = @roots_list_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_roots_list_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_roots_list_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Send roots/list response back to server via HTTP POST (MCP 2025-06-18)
@@ -563,8 +611,8 @@ module MCPClient
       # Call the registered callback
       result = @sampling_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_sampling_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_sampling_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Send sampling response back to server via HTTP POST (MCP 2025-11-25)
@@ -597,6 +645,14 @@ module MCPClient
     # @param result [Hash] the elicitation result (action and optional content)
     # @return [void]
     def send_elicitation_response(request_id, result)
+      # Error-shaped results become JSON-RPC error responses (e.g. -32602 for
+      # an undeclared elicitation mode), mirroring the sampling error path.
+      if result.is_a?(Hash) && result['error']
+        send_error_response(request_id, result['error']['code'] || -32_603,
+                            result['error']['message'] || 'Elicitation error')
+        return
+      end
+
       ensure_initialized
 
       response = {
@@ -654,6 +710,9 @@ module MCPClient
       @rpc_conn.post do |req|
         req.url @rpc_endpoint
         req.headers['Content-Type'] = 'application/json'
+        # MCP lifecycle "Version Negotiation": include the MCP-Protocol-Version
+        # header on all HTTP requests after the initialize handshake.
+        req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         @headers.each { |k, v| req.headers[k] = v }
         req.body = json_body
       end
@@ -889,24 +948,14 @@ module MCPClient
     # @private
     def request_prompts_list
       @mutex.synchronize do
-        return @prompts_data if @prompts_data
+        return @prompts_data.dup if @prompts_data
       end
 
-      result = rpc_request('prompts/list')
+      # Follow nextCursor across pages so the full prompt list is returned.
+      prompts = request_paginated_list('prompts/list', 'prompts')
 
-      if result && result['prompts']
-        @mutex.synchronize do
-          @prompts_data = result['prompts']
-        end
-        return @mutex.synchronize { @prompts_data.dup }
-      elsif result
-        @mutex.synchronize do
-          @prompts_data = result
-        end
-        return @mutex.synchronize { @prompts_data.dup }
-      end
-
-      raise MCPClient::Errors::PromptGetError, 'Failed to get prompts list from JSON-RPC request'
+      @mutex.synchronize { @prompts_data = prompts }
+      @mutex.synchronize { @prompts_data.dup }
     end
 
     # Request the resources list using JSON-RPC
@@ -941,24 +990,16 @@ module MCPClient
     # @private
     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. The
+      # SSE parser no longer writes @tools_data per page, so this method is the
+      # sole writer and only ever caches the COMPLETE list.
+      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