ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/server_http.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'request_meta_scope'
 require 'uri'
 require 'json'
 require 'monitor'
@@ -16,14 +17,23 @@ module MCPClient
   # @note Elicitation Support (MCP 2025-06-18)
   #   This transport does NOT support server-initiated elicitation requests.
   #   The HTTP transport uses a pure request-response architecture where only the client
-  #   can initiate requests. For elicitation support, use one of these transports instead:
+  #   can initiate requests. A legacy server that sends one on an SSE response
+  #   stream is answered with JSON-RPC -32601 rather than left waiting (a
+  #   `ping` gets the empty result it requires). For elicitation support, use
+  #   one of these transports instead:
   #   - ServerStdio: Full bidirectional JSON-RPC over stdin/stdout
-  #   - ServerSSE: Server requests via SSE stream, client responses via HTTP POST
   #   - ServerStreamableHTTP: Server requests via SSE-formatted responses, client responses via HTTP POST
+  #   - ServerSSE: Server requests via SSE stream, client responses via HTTP POST — but the
+  #     HTTP+SSE transport is deprecated (SEP-2596; earliest removal three months after
+  #     SEP-2596 reaches Final), so prefer ServerStreamableHTTP for a new integration
   class ServerHTTP < ServerBase
     require_relative 'server_http/json_rpc_transport'
 
     include JsonRpcTransport
+    # Every operation that may weigh a cache decision runs inside a scope
+    # that reserves the host request_meta evaluation for the request it
+    # leads to, and drops it when the operation ends.
+    prepend MCPClient::RequestMetaScope
 
     # Default values for connection settings
     DEFAULT_READ_TIMEOUT = 30
@@ -93,13 +103,16 @@ module MCPClient
                   end
 
       # Set up headers for HTTP requests
+      # MCP 2026-07-28 Streamable HTTP: the client MUST list both content
+      # types and support either framing of the response.
       @headers = opts[:headers].merge({
                                         'Content-Type' => 'application/json',
-                                        'Accept' => 'application/json',
+                                        'Accept' => 'application/json, text/event-stream',
                                         'User-Agent' => "ruby-mcp-client/#{MCPClient::VERSION}"
                                       })
 
       @read_timeout = opts[:read_timeout]
+      configure_protocol_mode(opts[:protocol], opts[:discover_timeout])
       @faraday_config = opts[:faraday_config]
       @tools = nil
       @tools_data = nil
@@ -110,38 +123,43 @@ module MCPClient
       @http_conn = nil
       @session_id = nil
       @oauth_provider = opts[:oauth_provider]
+      @elicitation_request_callback = nil # MCP 2026-07-28 multi round-trip requests
+      @roots_list_request_callback = nil
+      @sampling_request_callback = nil
     end
 
     # Connect to the MCP server over HTTP
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     def connect
-      return true if @mutex.synchronize { @connection_established }
+      # Serialized: concurrent first requests must not each run the probe
+      # and possibly settle on different eras (the monitor is reentrant, so
+      # the request plumbing inside may take @mutex again).
+      @mutex.synchronize do
+        return true if @connection_established
 
-      begin
-        @mutex.synchronize do
+        begin
           @connection_established = false
           @initialized = false
-        end
 
-        # Test connectivity with a simple HTTP request
-        test_connection
+          # Test connectivity with a simple HTTP request
+          test_connection
 
-        # Perform MCP initialization handshake
-        perform_initialize
+          # Establish the protocol era: server/discover for a modern server,
+          # the initialize handshake for a legacy one.
+          negotiate_protocol
 
-        @mutex.synchronize do
           @connection_established = true
           @initialized = true
-        end
 
-        true
-      rescue MCPClient::Errors::ConnectionError => e
-        cleanup
-        raise e
-      rescue StandardError => e
-        cleanup
-        raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+          true
+        rescue MCPClient::Errors::ConnectionError => e
+          cleanup
+          raise e
+        rescue StandardError => e
+          cleanup
+          raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server at #{@base_url}: #{e.message}"
+        end
       end
     end
 
@@ -151,21 +169,18 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
     def list_tools
-      @mutex.synchronize do
-        return @tools if @tools
-      end
-
+      # MCP 2026-07-28 caching: a cached list is served only while fresh, and
+      # only from the entry that carries its hint.
+      cached = fresh_list_value(:tools) { @mutex.synchronize { @tools } }
+      return cached if cached
+
+      # Stale: the raw page cache must go too, or the re-fetch would be
+      # answered from memory.
+      @mutex.synchronize { @tools_data = nil }
       begin
         ensure_connected
 
-        tools_data = request_tools_list
-        @mutex.synchronize do
-          @tools = tools_data.map do |tool_data|
-            MCPClient::Tool.from_json(tool_data, server: self)
-          end
-        end
-
-        @mutex.synchronize { @tools }
+        refetch_or_serve_stale(:tools, stale_list_entry(:tools)) { fetch_tools_list }
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         # Re-raise these errors directly
         raise
@@ -184,9 +199,15 @@ module MCPClient
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
       rpc_request('tools/call', build_named_request_params(tool_name, parameters))
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ValidationError
       # Re-raise connection/transport errors directly to match test expectations
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     rescue StandardError => e
       # For all other errors, wrap in ToolCallError
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
@@ -196,6 +217,10 @@ module MCPClient
     def apply_request_headers(req, request)
       super
 
+      # Modern servers have no session; the base class added the 2026-07-28
+      # request metadata headers.
+      return if modern?
+
       # Add session and protocol version headers for non-initialize requests
       return unless request['method'] != 'initialize'
 
@@ -220,7 +245,7 @@ module MCPClient
       session_id = response.headers['mcp-session-id'] || response.headers['Mcp-Session-Id']
       if session_id
         if valid_session_id?(session_id)
-          @session_id = session_id
+          capture_session_id(session_id)
           @logger.debug("Captured session ID: #{@session_id}")
         else
           @logger.warn("Invalid session ID format received: #{session_id.inspect}")
@@ -236,23 +261,13 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt listing
     def list_prompts
-      @mutex.synchronize do
-        return @prompts if @prompts
-      end
+      cached = fresh_list_value(:prompts) { @mutex.synchronize { @prompts } }
+      return cached if cached
 
+      @mutex.synchronize { @prompts_data = nil }
       begin
         ensure_connected
-
-        # 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|
-            MCPClient::Prompt.from_json(prompt_data, server: self)
-          end
-        end
-
-        @mutex.synchronize { @prompts }
+        refetch_or_serve_stale(:prompts, stale_list_entry(:prompts)) { fetch_prompts_list }
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         raise
       rescue StandardError => e
@@ -260,6 +275,28 @@ module MCPClient
       end
     end
 
+    # Fetch and cache the prompt list.
+    # @return [Array<MCPClient::Prompt>]
+    def fetch_prompts_list
+      ensure_connected
+
+      # Follow nextCursor across pages so the full prompt list is returned.
+      prompts = request_paginated_list('prompts/list', 'prompts')
+
+      prompts = prompts.map { |prompt_data| MCPClient::Prompt.from_json(prompt_data, server: self) }
+      @mutex.synchronize do
+        @prompts = attach_list_value(:prompts, prompts) ? prompts : nil
+      end
+
+      # This request's own list, never a re-read of @prompts (another
+      # request may have stored its list in between).
+      prompts
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+    end
+
     # Get a prompt with the given parameters
     # @param prompt_name [String] the name of the prompt to get
     # @param parameters [Hash] the parameters to pass to the prompt
@@ -271,6 +308,12 @@ module MCPClient
       rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::PromptGetError, "Error getting prompt '#{prompt_name}': #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::PromptGetError, "Error getting prompt '#{prompt_name}': #{e.message}"
     end
@@ -280,28 +323,18 @@ module MCPClient
     # @return [Hash] result containing resources array and optional nextCursor
     # @raise [MCPClient::Errors::ResourceReadError] if resources list retrieval fails
     def list_resources(cursor: nil)
-      @mutex.synchronize do
-        return @resources_result if @resources_result && !cursor
-      end
+      cached = cursor ? nil : fresh_list_value(:resources) { @mutex.synchronize { @resources_result } }
+      return cached if cached
 
       begin
         ensure_connected
-
-        params = {}
-        params['cursor'] = cursor if cursor
-        result = rpc_request('resources/list', params)
-
-        resources = (result['resources'] || []).map do |resource_data|
-          MCPClient::Resource.from_json(resource_data, server: self)
-        end
-
-        resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
-
-        @mutex.synchronize do
-          @resources_result = resources_result unless cursor
+        unless cursor
+          return refetch_or_serve_stale(:resources, stale_list_entry(:resources)) do
+            fetch_resources_list(nil)
+          end
         end
 
-        resources_result
+        fetch_resources_list(cursor)
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         raise
       rescue StandardError => e
@@ -309,14 +342,52 @@ module MCPClient
       end
     end
 
+    # Fetch one page of resources/list, caching the first page.
+    # @param cursor [String, nil]
+    # @return [Hash]
+    def fetch_resources_list(cursor)
+      params = {}
+      params['cursor'] = cursor if cursor
+      epoch = cache_epoch(:resources)
+      answer = fetching_list_page(:resources, cursor) { rpc_request('resources/list', params) }
+      result = require_complete_result!(answer, 'resources/list')
+      record_cache_hint(:resources, result, epoch: epoch) unless cursor
+
+      resources = (result['resources'] || []).map do |resource_data|
+        MCPClient::Resource.from_json(resource_data, server: self)
+      end
+
+      resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+
+      # A list invalidated while in flight is returned but not cached.
+      @mutex.synchronize do
+        unless cursor
+          @resources_result = attach_list_value(:resources, resources_result) ? resources_result : nil
+        end
+      end
+
+      resources_result
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+      raise
+    rescue StandardError => e
+      raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
+    end
+
     # Read a resource by its URI
     # @param uri [String] the URI of the resource to read
     # @return [Array<MCPClient::ResourceContent>] array of resource contents
     # @raise [MCPClient::Errors::ResourceReadError] if resource reading fails
     def read_resource(uri)
-      result = rpc_request('resources/read', { uri: uri })
-      contents = result['contents'] || []
-      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
+      # The session exists before the cache epoch is snapshotted: a
+      # reconnect inside the request would otherwise advance it and drop
+      # the first read's entry.
+      ensure_connected
+      read_resource_with_cache(uri) { |sent| rpc_request('resources/read', { uri: sent }) }
+    rescue MCPClient::Errors::ServerError => e
+      raise if e.protocol_error?
+      raise resource_not_found_error(uri, e) if resource_not_found_response?(e)
+
+      raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise
     rescue StandardError => e
@@ -334,11 +405,17 @@ module MCPClient
       require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
-      result = rpc_request('completion/complete', params)
+      result = require_complete_result!(rpc_request('completion/complete', params), 'completion/complete')
       result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
            MCPClient::Errors::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
     end
@@ -348,13 +425,31 @@ module MCPClient
     #   'critical', 'alert', 'emergency')
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
+    # @deprecated Logging is deprecated since MCP 2026-07-28 (SEP-2577);
+    #   earliest removal is the first revision released on or after
+    #   2027-07-28. Have the server log to stderr (stdio) or use
+    #   OpenTelemetry instead.
     def log_level=(level)
+      MCPClient::Deprecations.warn(:logging, @logger)
       ensure_connected
+      # MCP 2026-07-28 removed logging/setLevel: the level travels per request
+      # in _meta["io.modelcontextprotocol/logLevel"].
+      if modern?
+        @log_level = validate_log_level!(level)
+        return
+      end
+
       require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
-           MCPClient::Errors::CapabilityError
+           MCPClient::Errors::CapabilityError, ArgumentError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors (typed -3202x, invalid result) carry
+      # actionable data such as requiredCapabilities; keep them intact.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
     end
@@ -364,19 +459,52 @@ module MCPClient
     # @return [Hash] result containing resourceTemplates array and optional nextCursor
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource template listing
     def list_resource_templates(cursor: nil)
+      # Only a list the server itself bounded is served from here: a
+      # positive ttlMs means no second request, while a list with no hint
+      # (a 2025-11-25 server) is asked for again, as it was before this
+      # transport cached anything (MCP 2026-07-28 caching).
+      cached = cursor ? nil : hinted_list_value(:templates)
+      return cached if cached
+
+      begin
+        ensure_connected
+        unless cursor
+          return refetch_or_serve_stale(:templates, stale_list_entry(:templates)) do
+            fetch_templates_list(nil)
+          end
+        end
+
+        fetch_templates_list(cursor)
+      rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+        raise
+      rescue StandardError => e
+        raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+      end
+    end
+
+    # Fetch one page of resources/templates/list, caching the first page.
+    # @param cursor [String, nil]
+    # @return [Hash]
+    def fetch_templates_list(cursor)
       params = {}
       params['cursor'] = cursor if cursor
-      result = rpc_request('resources/templates/list', params)
+      epoch = cache_epoch(:templates)
+      answer = fetching_list_page(:templates, cursor) { rpc_request('resources/templates/list', params) }
+      result = require_complete_result!(answer, 'resources/templates/list')
+      record_cache_hint(:templates, result, epoch: epoch) unless cursor
 
       templates = (result['resourceTemplates'] || []).map do |template_data|
         MCPClient::ResourceTemplate.from_json(template_data, server: self)
       end
+      templates_result = { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
 
-      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
-      raise
-    rescue StandardError => e
-      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
+      @mutex.synchronize do
+        unless cursor
+          @templates_result = attach_list_value(:templates, templates_result) ? templates_result : nil
+        end
+      end
+
+      templates_result
     end
 
     # Subscribe to resource updates
@@ -386,6 +514,13 @@ module MCPClient
     def subscribe_resource(uri)
       ensure_connected
       require_capability!('resources', 'subscribe', method: 'resources/subscribe')
+      # MCP 2026-07-28 replaced resources/subscribe with a subscriptions/listen
+      # stream carrying resourceSubscriptions.
+      if modern?
+        subscribe_resource_via_listen(uri)
+        return true
+      end
+
       rpc_request('resources/subscribe', { uri: uri })
       true
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
@@ -402,6 +537,11 @@ module MCPClient
     def unsubscribe_resource(uri)
       ensure_connected
       require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
+      if modern?
+        unsubscribe_resource_via_listen(uri)
+        return true
+      end
+
       rpc_request('resources/unsubscribe', { uri: uri })
       true
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
@@ -421,6 +561,53 @@ module MCPClient
       end
     end
 
+    # Register a handler for elicitation input requests (MCP 2026-07-28 multi
+    # round-trip requests; there is no server-initiated request channel on
+    # this transport, so these only serve InputRequiredResult round trips).
+    # @param block [Proc] callback that receives (key, params) and returns an ElicitResult
+    # @return [void]
+    def on_elicitation_request(&block)
+      @elicitation_request_callback = block
+    end
+
+    # Register a handler for roots/list input requests (MCP 2026-07-28).
+    #
+    # @deprecated Roots is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Registering
+    #   a handler is not itself use of Roots — a handler that answers with no root
+    #   exposes nothing deprecated — but a handler that answers with a root adopts
+    #   the deprecated feature and raises the notice. Pass directories or files
+    #   through tool parameters, resource URIs or server configuration instead.
+    # @param block [Proc] callback that receives (key, params) and returns a ListRootsResult
+    # @return [void]
+    def on_roots_list_request(&block)
+      @roots_list_request_callback = block
+    end
+
+    # Register a handler for sampling input requests (MCP 2026-07-28).
+    #
+    # @deprecated Sampling is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Integrate
+    #   directly with the LLM provider API instead of serving
+    #   sampling/createMessage.
+    # @param block [Proc] callback that receives (key, params) and returns a CreateMessageResult
+    # @return [void]
+    def on_sampling_request(&block)
+      @sampling_request_callback = block
+    end
+
+    # This transport has no legacy server-request channel (server requests on
+    # a response stream are dropped), so on a legacy session it must not
+    # advertise roots, elicitation or sampling: the handlers above only serve
+    # the modern multi round-trip pattern.
+    # @return [Hash]
+    def client_capabilities
+      capabilities = super
+      return capabilities if modern?
+
+      capabilities.except('roots', 'elicitation', 'sampling')
+    end
+
     # Terminate the current session (if any)
     # @return [Boolean] true if termination was successful or no session exists
     def terminate_session
@@ -434,12 +621,18 @@ module MCPClient
     # Clean up the server connection
     # Properly closes HTTP connections and clears cached state
     def cleanup
+      # Only an established session ends a task's namespace; a sessionless
+      # (MCP 2026-07-28) connection is merely closed, and a connection that
+      # never came up has nothing to end — see #ending_session?.
+      bump_session_epoch if ending_session?
       @mutex.synchronize do
         # Attempt to terminate session before cleanup
         terminate_session if @session_id
 
         @connection_established = false
         @initialized = false
+        # Subscription streams (MCP 2026-07-28) end with the connection
+        close_listen_streams
 
         @logger.debug('Cleaning up HTTP connection')
 
@@ -449,7 +642,26 @@ module MCPClient
 
         @tools = nil
         @tools_data = nil
+        @prompts = nil
+        @prompts_data = nil
+        @resources_result = nil
+        @resources_data = nil
+        @templates_result = nil
       end
+      # Cached results and their hints belong to the connection (and its
+      # authorization context) that was just torn down; outside @mutex, as
+      # the cache has its own lock.
+      clear_result_cache
+    ensure
+      # Everything this transport left on this thread — the notes of the
+      # entries it served and recorded, the credentials, parameters and
+      # metadata of its requests — describes a slice that will never be
+      # tagged and a request that will never be made. Dropped after the
+      # session was terminated, never before: the DELETE that terminates it
+      # is a request of this transport's own, and the recorder on its
+      # connection would put its Authorization fingerprint straight back on
+      # this thread.
+      forget_transport_thread_state
     end
 
     private
@@ -485,7 +697,9 @@ module MCPClient
         name: nil,
         logger: nil,
         oauth_provider: nil,
-        faraday_config: nil
+        faraday_config: nil,
+        protocol: :auto,
+        discover_timeout: nil
       }
     end
 
@@ -510,27 +724,30 @@ module MCPClient
     # @return [void]
     # @raise [MCPClient::Errors::ConnectionError] if connection is not established
     def ensure_connected
-      return if @mutex.synchronize { @connection_established && @initialized }
+      # Serialized on the transport monitor (reentrant, so the nested
+      # cleanup/connect may take it again): checking the flags and acting on
+      # them must be one step. Otherwise a caller that observed "disconnected"
+      # can be overtaken by one that reconnects, and then tear that fresh
+      # connection down — terminating its session and re-running the era
+      # probe.
+      @mutex.synchronize do
+        return if @connection_established && @initialized
 
-      @logger.debug('Connection not active, attempting to reconnect before request')
-      cleanup
-      connect
+        @logger.debug('Connection not active, attempting to reconnect before request')
+        cleanup
+        connect
+      end
     end
 
     # Request the tools list using JSON-RPC
     # @return [Array<Hash>] the tools data
     # @raise [MCPClient::Errors::ToolCallError] if tools list retrieval fails
     def request_tools_list
-      @mutex.synchronize do
-        return @tools_data.dup if @tools_data
-      end
-
       # Follow nextCursor across pages so the full tool list is returned even
-      # when the server paginates.
-      tools = request_paginated_list('tools/list', 'tools')
-
-      @mutex.synchronize { @tools_data = tools }
-      @mutex.synchronize { @tools_data.dup }
+      # when the server paginates. The raw pages are this fetch's own: a
+      # shared copy could answer a concurrent caller under other
+      # credentials with a privately scoped list (MCP 2026-07-28 caching).
+      request_paginated_list('tools/list', 'tools')
     end
   end
 end