ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/server_stdio.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require_relative 'request_meta_scope'
 require 'open3'
+require 'monitor'
 require 'json'
 require_relative 'version'
 require 'logger'
@@ -8,9 +10,14 @@ require 'logger'
 module MCPClient
   # JSON-RPC implementation of MCP server over stdio.
   class ServerStdio < ServerBase
+    require_relative 'server_stdio/child_session'
     require_relative 'server_stdio/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
 
     # @!attribute [r] command
     #   @return [String, Array] the command used to launch the server
@@ -27,6 +34,12 @@ module MCPClient
     # for the server to exit, send SIGTERM, then SIGKILL if it still runs.
     SHUTDOWN_GRACE_PERIOD = 2
 
+    # Seconds a process must last after the open subscriptions were re-sent to
+    # it — counted from the moment it received them, not from the moment it
+    # was spawned — before another unexpected exit counts as a crash rather
+    # than a crash loop (see {JsonRpcTransport#reopen_subscriptions}).
+    SUBSCRIPTION_RESTART_MIN_INTERVAL = 5
+
     # Chunk size (bytes) used when draining the subprocess stderr pipe
     STDERR_READ_CHUNK_SIZE = 8192
 
@@ -35,6 +48,14 @@ module MCPClient
     # (e.g. progress output using carriage returns).
     STDERR_MAX_LINE_SIZE = 64 * 1024
 
+    # How the server's protocol era is established (MCP 2026-07-28
+    # basic/transports/stdio "Backward Compatibility"):
+    # - :auto   probe with server/discover, fall back to initialize on any
+    #           non-modern error or timeout (dual-era client, the default)
+    # - :modern probe with server/discover and fail if the server is legacy
+    # - :legacy skip the probe and run the initialize handshake
+    PROTOCOL_MODES = %i[auto modern legacy].freeze
+
     # Initialize a new ServerStdio instance
     # @param command [String, Array] the stdio command to launch the MCP JSON-RPC server
     #   For improved security, passing an Array is recommended to avoid shell injection issues
@@ -44,12 +65,28 @@ module MCPClient
     # @param name [String, nil] optional name for this server
     # @param logger [Logger, nil] optional logger
     # @param env [Hash] optional environment variables for the subprocess
-    def initialize(command:, retries: 0, retry_backoff: 1, read_timeout: READ_TIMEOUT, name: nil, logger: nil, env: {})
+    # @param protocol [Symbol] :auto (probe, fall back to initialize), :modern
+    #   (probe, no fallback) or :legacy (initialize handshake only)
+    # @param discover_timeout [Numeric, nil] seconds to wait for the
+    #   server/discover probe (default: read_timeout — a modern server that is
+    #   slow to start must not be misclassified as legacy)
+    def initialize(command:, retries: 0, retry_backoff: 1, read_timeout: READ_TIMEOUT, name: nil, logger: nil, env: {},
+                   protocol: :auto, discover_timeout: nil)
       super(name: name)
+      unless PROTOCOL_MODES.include?(protocol)
+        raise ArgumentError, "protocol must be one of #{PROTOCOL_MODES.inspect}, got #{protocol.inspect}"
+      end
+
+      @protocol_mode = protocol
+      @discover_timeout = discover_timeout || read_timeout
       @command_array = command.is_a?(Array) ? command : nil
       @command = command.is_a?(Array) ? command.join(' ') : command
       @mutex = Mutex.new
       @cond = ConditionVariable.new
+      # Serializes process start and protocol negotiation: two threads must
+      # not each spawn the server or run the probe and the fallback on the
+      # same pipes. Reentrant because negotiation waits on @mutex inside.
+      @init_lock = Monitor.new
       @next_id = 1
       @pending = {}
       # Ids of requests awaiting a response; used to drop late/unsolicited
@@ -68,6 +105,29 @@ module MCPClient
       @sampling_request_callback = nil # MCP 2025-11-25
       @reader_thread = nil
       @stderr_thread = nil
+      # Bumped whenever a subprocess is spawned or torn down, so a reader
+      # thread only ever speaks for the transport it was started for.
+      @transport_generation = 0
+      # Guards the pair (subprocess handles, generation) so that judging
+      # whether a request's transport is still current and writing it are
+      # one step: a restart cannot slip in between (see
+      # JsonRpcTransport#send_request).
+      @transport_lock = Mutex.new
+      @negotiating = false
+      @transport_retired = false
+      @modern_answer_received = false
+      # The record of the live child process, and of the one the open
+      # subscriptions were last re-sent to — the crash-loop bound is read from
+      # the latter (see ChildSession and JsonRpcTransport#reopen_subscriptions).
+      @session = nil
+      @subscription_carrier = nil
+      # The subscriptions waiting for a process, and the lock the two paths
+      # that write them share: a `cleanup` moving the open subscriptions onto
+      # the queue overlaps a hand-over whose listen write failed putting one
+      # back (JsonRpcTransport#enqueue_reconnecting_subscriptions). Made here
+      # so no two threads ever race to make it.
+      @reconnecting_mutex = Mutex.new
+      @reconnecting_subscriptions = []
     end
 
     # Server info from the initialize response
@@ -78,20 +138,35 @@ module MCPClient
     # @return [Hash, nil] Server capabilities
     attr_reader :capabilities
 
+    # @return [Symbol] the configured protocol mode (:auto, :modern or :legacy)
+    attr_reader :protocol_mode
+
+    # @return [Numeric] seconds allowed for the server/discover probe
+    attr_reader :discover_timeout
+
     # Connect to the MCP server by launching the command process via stdin/stdout
     # @return [Boolean] true if connection was successful
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     def connect
-      if @command_array
-        if @env.any?
-          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@env, *@command_array)
-        else
-          @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(*@command_array)
-        end
-      elsif @env.any?
-        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@env, @command)
-      else
-        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@command)
+      handles = spawn_server_process
+      # The handles and the generation change together: a request judged
+      # current against the old generation must not find the new stdin.
+      @transport_lock.synchronize do
+        @stdin, @stdout, @stderr, @wait_thread = handles
+        @transport_generation += 1
+        # A fresh process is not the one that exited: a restart made for the
+        # open subscriptions must not be torn down again by the next request.
+        @transport_retired = false
+        # A fresh process has said nothing yet: what the previous one wrote
+        # identifies nothing about this one, and what was negotiated WITH it
+        # binds nothing here. The era is per process (stdio "Backward
+        # Compatibility"), and the replacement's reader starts before the
+        # probe proposes anything: a 2025-11-25 replacement that pings at
+        # startup would otherwise be judged by the dead process's era, its
+        # ping dropped, and both the probe and the handshake left waiting on
+        # a server that answers nothing until its pong arrives.
+        @modern_answer_received = false
+        @protocol_version = nil
       end
       pin_pipe_encodings
       true
@@ -99,6 +174,19 @@ module MCPClient
       raise MCPClient::Errors::ConnectionError, "Failed to connect to MCP server: #{e.message}"
     end
 
+    # @return [Array] the stdin, stdout, stderr and wait thread of the spawned process
+    def spawn_server_process
+      if @command_array
+        return Open3.popen3(@env, *@command_array) if @env.any?
+
+        Open3.popen3(*@command_array)
+      elsif @env.any?
+        Open3.popen3(@env, @command)
+      else
+        Open3.popen3(@command)
+      end
+    end
+
     # Pin the subprocess pipe encodings to UTF-8 instead of inheriting the
     # process locale (Encoding.default_external). JSON-RPC messages MUST be
     # UTF-8 encoded (MCP 2025-11-25 basic/transports.mdx); under a non-UTF-8
@@ -115,13 +203,99 @@ module MCPClient
     # Spawn a reader thread to collect JSON-RPC responses
     # @return [Thread] the reader thread
     def start_reader
+      generation = @transport_generation
+      # The record of the process this reader belongs to, so an EOF can be
+      # told from the EOF of a process that has since been replaced.
+      session = @session
+      stdout = @stdout
       @reader_thread = Thread.new do
-        @stdout.each_line do |line|
+        stdout.each_line do |line|
           handle_line(line)
         end
+        handle_reader_eof(session, generation)
       rescue StandardError
         # Reader thread aborted unexpectedly
+      ensure
+        retire_transport(generation)
+      end
+    end
+
+    # The subprocess closed its stdout: it has exited (or its pipes were
+    # dropped), so no response will ever arrive on this transport again. MCP
+    # 2026-07-28 basic/transports/stdio ("Unexpected Termination") says a
+    # client SHOULD restart a server that terminated unexpectedly, so retire
+    # the handshake rather than let it describe a process that no longer
+    # exists: the next request releases these handles and negotiates again
+    # against a fresh subprocess.
+    #
+    # Nothing is restarted or replayed from here. A request that was in
+    # flight may already have been executed server-side, so it fails as it
+    # would on any other broken transport; only the session is recoverable.
+    # A deliberate shutdown bumps the generation first, so its own reader
+    # reaching EOF is not mistaken for an unexpected exit.
+    # @param generation [Integer] the transport this reader was started for
+    # @return [void]
+    def retire_transport(generation)
+      return unless generation == @transport_generation
+
+      # Waiters are woken: a request in flight on this transport will never
+      # be answered, and should fail now rather than wait out its timeout.
+      @mutex.synchronize do
+        @transport_retired = true
+        @cond.broadcast
       end
+      @logger.debug('Server stdout closed; the transport will be re-established on the next request')
+    end
+
+    # EOF on the process's stdout: unless the client closed its stdin, the
+    # server exited on its own.
+    #
+    # Waiting out an initialization still in flight is what makes an exit
+    # *during* one recoverable. The handling used to be skipped outright while
+    # `@initialized` was false — which is exactly the state a process that
+    # answered the discovery probe and then exited leaves behind. Nothing else
+    # noticed: {JsonRpcTransport#ensure_initialized} went on to mark the dead
+    # connection initialized and re-send the open subscriptions to it, the
+    # failed writes were deferred back onto the queue for "the next process",
+    # and with this reader already gone there was no one left to establish one.
+    # The subscriptions stayed :reconnecting for ever, with the host neither
+    # served nor told.
+    #
+    # The lock is that initialization finishing, and taking it cannot deadlock:
+    # the reader is never the thread inside it, and by the time it is waiting
+    # here it can deliver no further responses, so anything that thread is
+    # still waiting for is already bounded by its own timeout.
+    # @param session [MCPClient::ServerStdio::ChildSession, nil] the record of
+    #   the process this reader was started for
+    # @param generation [Integer] the transport generation this reader was
+    #   started for; an EOF on a generation that has since been torn down —
+    #   by the host's `cleanup`, or by another exit — is not an exit to handle
+    # @return [void]
+    def handle_reader_eof(session, generation = @transport_generation)
+      @init_lock.synchronize { nil } unless @initialized
+      return unless live_transport?(generation, session)
+
+      handle_server_exit(session, generation)
+    end
+
+    # Whether the process a reader was started for is still the live one: its
+    # transport generation has not been claimed for teardown, and its record
+    # is the current session. Read under the transport lock, since a teardown
+    # claims the generation under it.
+    # @param generation [Integer] the transport generation to check
+    # @param session [MCPClient::ServerStdio::ChildSession, nil]
+    # @return [Boolean]
+    def live_transport?(generation, session)
+      @transport_lock.synchronize { !@stdin.nil? && generation == @transport_generation } && current_session?(session)
+    end
+
+    # Whether the process a reader was started for is still the live one. A
+    # reader whose process has already been torn down and replaced must not
+    # tear down its successor.
+    # @param session [MCPClient::ServerStdio::ChildSession, nil]
+    # @return [Boolean]
+    def current_session?(session)
+      session.nil? || @session.equal?(session)
     end
 
     # Spawn a thread to continuously drain the subprocess stderr.
@@ -138,10 +312,11 @@ module MCPClient
     # STDERR_MAX_LINE_SIZE is flushed rather than retained.
     # @return [Thread] the stderr reader thread
     def start_stderr_reader
+      stderr = @stderr
       @stderr_thread = Thread.new do
         buffer = +''
         loop do
-          buffer << @stderr.readpartial(STDERR_READ_CHUNK_SIZE)
+          buffer << stderr.readpartial(STDERR_READ_CHUNK_SIZE)
           flush_stderr_lines(buffer)
           flush_stderr_overflow(buffer)
         end
@@ -159,6 +334,9 @@ module MCPClient
     # @param line [String] line of output to parse
     # @return [void]
     def handle_line(line)
+      # The response is dated from the arrival of its line, before it is
+      # decoded: parsing time is not freshness.
+      arrived = respond_to?(:monotonic_now, true) ? monotonic_now : nil
       msg = JSON.parse(line)
       @logger.debug("Received line: #{describe_jsonrpc_message(msg)}")
 
@@ -171,34 +349,91 @@ module MCPClient
 
       # Dispatch JSON-RPC requests from server (has id AND method) - MCP 2025-06-18
       if msg['method'] && msg.key?('id')
-        handle_server_request(msg)
+        if modern_peer?
+          # MCP 2026-07-28 stdio: "The server MUST NOT write JSON-RPC requests
+          # to stdout" and "The client MUST NOT write JSON-RPC responses" —
+          # server-to-client interactions travel in InputRequiredResult.
+          @logger.warn("Ignoring server-initiated request #{msg['method']}: " \
+                       'a modern MCP server MUST NOT write JSON-RPC requests to stdout')
+        else
+          handle_server_request(msg)
+        end
         return
       end
 
       # Dispatch JSON-RPC notifications (no id, has method)
       if msg['method'] && !msg.key?('id')
-        @notification_callback&.call(msg['method'], msg['params'])
+        route_notification(msg['method'], msg['params'])
         return
       end
 
       # Handle standard JSON-RPC responses (has id, no method)
       id = msg['id']
       return unless id
+      # A response to a subscriptions/listen request ends that subscription
+      # (no caller is waiting on it).
+      return if handle_subscription_response(msg)
+
+      record_response(id, msg, arrived)
+    rescue JSON::ParserError, EncodingError
+      # Skip non-JSONRPC or undecodable lines in the output stream so a single
+      # bad line cannot kill the reader thread
+    end
 
+    # Queue a response for the caller waiting on it.
+    # @param id [Integer, String] the response's request id
+    # @param msg [Hash] the decoded response
+    # @param arrived [Float, nil] when its line arrived (monotonic seconds)
+    # @return [void]
+    def record_response(id, msg, arrived)
       @mutex.synchronize do
         # Only retain a response that corresponds to an outstanding request.
         # Late responses (arriving after the caller timed out) and unsolicited
         # responses are dropped so @pending cannot grow without bound.
         if @awaiting.key?(id)
+          # The answer is recorded as identifying the peer BEFORE it is
+          # queued and before the next line is read: the thread waiting for
+          # it may not run until after the server has written its next line,
+          # and if that line is a request a modern server MUST NOT have
+          # written, it must already be known as prohibited traffic — a
+          # legacy accommodation is only owed while the probe is unanswered.
+          # Only an OUTSTANDING request's answer says anything, though: the
+          # response to a probe that timed out (and was cancelled) SHOULD be
+          # ignored, and the session it fell back to is a 2025-11-25 one
+          # whose server requests are still owed their responses. And only
+          # while the era is being negotiated: an answer on an established
+          # 2025-11-25 session renegotiates nothing, however modern its
+          # shape, and that session's ping, roots, sampling and elicitation
+          # requests stay owed their responses.
+          @modern_answer_received = true if era_probe_in_flight? && identifies_modern_server?(msg)
           @pending[id] = msg
+          # Dated from arrival: the waiter may wake much later.
+          (@response_arrivals ||= {})[id] = arrived || monotonic_now if respond_to?(:monotonic_now, true)
           @cond.broadcast
         else
           @logger.debug("Discarding response for unknown or expired request id=#{id}")
         end
       end
-    rescue JSON::ParserError, EncodingError
-      # Skip non-JSONRPC or undecodable lines in the output stream so a single
-      # bad line cannot kill the reader thread
+    end
+
+    # Whether a server-initiated request is prohibited traffic.
+    #
+    # Judged by the ESTABLISHED era, not by protocol_version: during the
+    # server/discover probe the latter is only the version this client
+    # proposed. A legacy server MAY ping while the probe is unanswered and
+    # then wait for the response before doing anything else, so treating its
+    # request as prohibited modern traffic deadlocks the negotiation.
+    #
+    # Two exceptions. A client configured protocol: :modern has already
+    # ruled out the legacy fallback that the accommodation exists for: it
+    # will never speak legacy, so it never runs a host callback for a server
+    # request nor writes the response back — not even while its own probe is
+    # still in flight. And once the reader has seen an answer only a modern
+    # server could have written, the server is modern whatever the
+    # negotiating thread has got round to applying.
+    # @return [Boolean]
+    def modern_peer?
+      protocol_era == :modern || @protocol_mode == :modern || @modern_answer_received
     end
 
     # List all prompts available from the MCP server
@@ -206,24 +441,50 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt listing
     def list_prompts
+      cached = hinted_list_value(:prompts)
+      return cached if cached
+
       ensure_initialized
-      collect_paginated('prompts') do |cursor|
+      # A cursor the server rejects restarts the list from its first page,
+      # exactly as it does on the HTTP transports (MCP pagination).
+      page = { cursor: nil }
+      prompts = restarting_rejected_cursor('prompts', page) { collect_prompt_pages(page) }
+      attach_list_value(:prompts, prompts)
+      prompts
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+    rescue StandardError => e
+      raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+    end
+
+    # Collect every page of prompts/list, recording what each page was
+    # answered under so the cache can bind the combined list to it.
+    # @param page [Hash] holds the cursor of the request in flight
+    # @return [Array<MCPClient::Prompt>]
+    def collect_prompt_pages(page)
+      pages = []
+      received_ats = []
+      fingerprints = []
+      epoch = cache_epoch(:prompts)
+      prompts = collect_paginated('prompts') do |cursor|
         params = {}
         params['cursor'] = cursor if cursor
-        req_id = next_id
-        req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'prompts/list', 'params' => params }
-        send_request(req)
-        res = wait_response(req_id)
-        if (err = res['error'])
-          raise MCPClient::Errors::ServerError, err['message']
-        end
-
-        result = res['result'] || {}
+        started = monotonic_now
+        page[:cursor] = cursor
+        page_result = fetch_list_page(:prompts, cursor) { rpc_request('prompts/list', params) } || {}
+        result = require_complete_result!(page_result, 'prompts/list')
+        pages << result
+        received_ats << response_received_at(since: started)
+        fingerprints << request_params_fingerprint
         prompts = (result['prompts'] || []).map { |td| MCPClient::Prompt.from_json(td, server: self) }
         [prompts, result['nextCursor']]
       end
-    rescue StandardError => e
-      raise MCPClient::Errors::PromptGetError, "Error listing prompts: #{e.message}"
+      record_list_cache_hint('prompts/list', pages, received_ats, params: fingerprints, epoch: epoch)
+      prompts
     end
 
     # Get a prompt with the given parameters
@@ -234,21 +495,13 @@ module MCPClient
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
     def get_prompt(prompt_name, parameters)
       ensure_initialized
-      req_id = next_id
-      # JSON-RPC method for getting a prompt
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'prompts/get',
-        'params' => build_named_request_params(prompt_name, parameters)
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
+      rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
 
-      res['result']
+      raise MCPClient::Errors::PromptGetError, "Error calling prompt '#{prompt_name}': #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::PromptGetError, "Error calling prompt '#{prompt_name}': #{e.message}"
     end
@@ -259,20 +512,26 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource listing
     def list_resources(cursor: nil)
+      cached = cursor ? nil : hinted_list_value(:resources)
+      return cached if cached
+
       ensure_initialized
-      req_id = next_id
       params = {}
       params['cursor'] = cursor if cursor
-      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/list', 'params' => params }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
-
-      result = res['result'] || {}
+      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 { |td| MCPClient::Resource.from_json(td, server: self) }
-      { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+      resources_result = { 'resources' => resources, 'nextCursor' => result['nextCursor'] }
+      attach_list_value(:resources, resources_result) unless cursor
+      resources_result
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error listing resources: #{e.message}"
     end
@@ -284,23 +543,16 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during resource reading
     def read_resource(uri)
       ensure_initialized
-      req_id = next_id
-      # JSON-RPC method for reading a resource
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'resources/read',
-        'params' => { 'uri' => uri }
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
+      # A null result reaches the shared guard as-is: it is a malformed
+      # response, not an empty resource.
+      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)
 
-      result = res['result'] || {}
-      contents = result['contents'] || []
-      contents.map { |content| MCPClient::ResourceContent.from_json(content) }
+      raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
+    rescue MCPClient::Errors::TransportError
+      raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error reading resource '#{uri}': #{e.message}"
     end
@@ -311,20 +563,30 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @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
+
       ensure_initialized
-      req_id = next_id
       params = {}
       params['cursor'] = cursor if cursor
-      req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'resources/templates/list', 'params' => params }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
-
-      result = res['result'] || {}
+      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 { |td| MCPClient::ResourceTemplate.from_json(td, server: self) }
-      { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+      templates_result = { 'resourceTemplates' => templates, 'nextCursor' => result['nextCursor'] }
+      attach_list_value(:templates, templates_result) unless cursor
+      templates_result
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error listing resource templates: #{e.message}"
     end
@@ -337,22 +599,23 @@ module MCPClient
     def subscribe_resource(uri)
       ensure_initialized
       require_capability!('resources', 'subscribe', method: 'resources/subscribe')
-      req_id = next_id
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'resources/subscribe',
-        'params' => { 'uri' => uri }
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
+      # 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::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
     end
@@ -365,22 +628,21 @@ module MCPClient
     def unsubscribe_resource(uri)
       ensure_initialized
       require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
-      req_id = next_id
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'resources/unsubscribe',
-        'params' => { 'uri' => uri }
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
+      if modern?
+        unsubscribe_resource_via_listen(uri)
+        return true
       end
 
+      rpc_request('resources/unsubscribe', { 'uri' => uri })
       true
     rescue MCPClient::Errors::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
     end
@@ -390,25 +652,53 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool listing
     def list_tools
+      # MCP 2026-07-28 caching: a list the server put a positive ttlMs on is
+      # served here while it is still fresh, so a host reaching for the
+      # transport directly does not re-list on every call.
+      cached = hinted_list_value(:tools)
+      return cached if cached
+
       ensure_initialized
-      collect_paginated('tools') do |cursor|
+      # A cursor the server rejects restarts the list from its first page,
+      # exactly as it does on the HTTP transports (MCP pagination).
+      page = { cursor: nil }
+      tools = restarting_rejected_cursor('tools', page) { collect_tool_pages(page) }
+      attach_list_value(:tools, tools)
+      tools
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
+
+      raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
+    rescue StandardError => e
+      raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
+    end
+
+    # Collect every page of tools/list, recording what each page was answered
+    # under so the cache can bind the combined list to it.
+    # @param page [Hash] holds the cursor of the request in flight
+    # @return [Array<MCPClient::Tool>]
+    def collect_tool_pages(page)
+      pages = []
+      received_ats = []
+      fingerprints = []
+      epoch = cache_epoch(:tools)
+      tools = collect_paginated('tools') do |cursor|
         params = {}
         params['cursor'] = cursor if cursor
-        req_id = next_id
-        # JSON-RPC method for listing tools
-        req = { 'jsonrpc' => '2.0', 'id' => req_id, 'method' => 'tools/list', 'params' => params }
-        send_request(req)
-        res = wait_response(req_id)
-        if (err = res['error'])
-          raise MCPClient::Errors::ServerError, err['message']
-        end
-
-        result = res['result'] || {}
+        started = monotonic_now
+        page[:cursor] = cursor
+        page_result = fetch_list_page(:tools, cursor) { rpc_request('tools/list', params) } || {}
+        result = require_complete_result!(page_result, 'tools/list')
+        pages << result
+        received_ats << response_received_at(since: started)
+        fingerprints << request_params_fingerprint
         tools = (result['tools'] || []).map { |td| MCPClient::Tool.from_json(td, server: self) }
         [tools, result['nextCursor']]
       end
-    rescue StandardError => e
-      raise MCPClient::Errors::ToolCallError, "Error listing tools: #{e.message}"
+      record_list_cache_hint('tools/list', pages, received_ats, params: fingerprints, epoch: epoch)
+      tools
     end
 
     # Call a tool with the given parameters
@@ -419,21 +709,13 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     def call_tool(tool_name, parameters)
       ensure_initialized
-      req_id = next_id
-      # JSON-RPC method for calling a tool
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'tools/call',
-        'params' => build_named_request_params(tool_name, parameters)
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
+      rpc_request('tools/call', build_named_request_params(tool_name, parameters))
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      raise if e.protocol_error?
 
-      res['result']
+      raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     rescue StandardError => e
       raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message}"
     end
@@ -447,24 +729,18 @@ module MCPClient
     def complete(ref:, argument:, context: nil)
       ensure_initialized
       require_capability!('completions', method: 'completion/complete')
-      req_id = next_id
       params = { 'ref' => ref, 'argument' => argument }
       params['context'] = context if context
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'completion/complete',
-        'params' => params
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
-      end
-
-      res.dig('result', 'completion') || { 'values' => [] }
+      result = require_complete_result!(rpc_request('completion/complete', params) || {}, 'completion/complete')
+      result['completion'] || { 'values' => [] }
     rescue MCPClient::Errors::CapabilityError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      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
@@ -474,25 +750,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_initialized
-      require_capability!('logging', method: 'logging/setLevel')
-      req_id = next_id
-      req = {
-        'jsonrpc' => '2.0',
-        'id' => req_id,
-        'method' => 'logging/setLevel',
-        'params' => { 'level' => level }
-      }
-      send_request(req)
-      res = wait_response(req_id)
-      if (err = res['error'])
-        raise MCPClient::Errors::ServerError, err['message']
+      # MCP 2026-07-28 removed logging/setLevel: the level is declared per
+      # request in _meta["io.modelcontextprotocol/logLevel"], so store it
+      # and let every subsequent request carry it.
+      if modern?
+        @log_level = validate_log_level!(level)
+        return
       end
 
-      res['result'] || {}
-    rescue MCPClient::Errors::CapabilityError
+      require_capability!('logging', method: 'logging/setLevel')
+      rpc_request('logging/setLevel', { 'level' => level }) || {}
+    rescue MCPClient::Errors::CapabilityError, ArgumentError
       raise
+    rescue MCPClient::Errors::ServerError => e
+      # 2026-07-28 protocol errors carry actionable data (requiredCapabilities,
+      # supported versions); keep them intact instead of wrapping.
+      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
@@ -505,6 +787,13 @@ module MCPClient
     end
 
     # Register a callback for roots/list requests (MCP 2025-06-18)
+    #
+    # @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 (request_id, params) and returns response hash
     # @return [void]
     def on_roots_list_request(&block)
@@ -512,6 +801,11 @@ module MCPClient
     end
 
     # Register a callback for sampling requests (MCP 2025-11-25)
+    #
+    # @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 (request_id, params) and returns response hash
     # @return [void]
     def on_sampling_request(&block)
@@ -596,6 +890,10 @@ module MCPClient
 
       # Call the registered callback
       result = @roots_list_request_callback.call(request_id, params)
+      # Serving a roots/list answer that carries a root means this host
+      # declared, and is using, the deprecated Roots capability (SEP-2577) —
+      # with or without a Client. An empty answer is not use of it.
+      warn_roots_deprecated(result)
 
       # Send the response back to the server (echoing related-task _meta)
       send_roots_list_response(request_id, merge_related_task_meta(result, params))
@@ -609,10 +907,18 @@ module MCPClient
       # If no callback is registered, return error
       unless @sampling_request_callback
         @logger.warn('Received sampling request but no callback registered, returning error')
-        send_error_response(request_id, -1, 'Sampling not supported')
+        # sampling.mdx § Error Handling reserves -1 for "User rejected sampling
+        # request"; a capability this client never declared is an unsupported
+        # method (-32601, Method not found), as Client#handle_sampling_request answers.
+        send_error_response(request_id, -32_601, 'Sampling not supported')
         return
       end
 
+      # Sampling, and the includeContext values it may carry, are deprecated
+      # (SEP-2577, SEP-2596) — with or without a Client.
+      warn_sampling_deprecated(params)
+      return if refused_undeclared_sampling_tools?(request_id, params)
+
       # Call the registered callback
       result = @sampling_request_callback.call(request_id, params)
 
@@ -723,30 +1029,252 @@ module MCPClient
       buffer.clear
     end
 
+    # Whether #cleanup ends a session: only a 2025-11-25 handshake opens
+    # one, and only once it completed. A stateless 2026-07-28 peer, a
+    # process that never got through its handshake and a probe still in
+    # flight leave nothing session-scoped behind — task ids and their
+    # bookkeeping stay what they are for the process that comes next.
+    # @return [Boolean]
+    def ending_session?
+      @initialized && !modern_peer?
+    end
+
     # Clean up the server connection
     # Closes all stdio handles and terminates any running processes and threads
     # following the MCP 2025-11-25 stdio shutdown sequence (basic/lifecycle.mdx):
     # close stdin, wait for the server to exit, send SIGTERM if it does not exit
     # within a reasonable time, then SIGKILL if it still does not exit.
+    #
+    # Tears down the process the transport holds *now*: a `cleanup` that
+    # finds the process already claimed by another teardown — the reader of a
+    # process that exited, dismantling it while the host got here — has
+    # nothing to do, and never touches a replacement the host established in
+    # the meantime (see {#teardown_transport}).
     # @return [void]
     def cleanup
-      return unless @stdin
-
-      @stdin.close unless @stdin.closed?
-      terminate_server_process
-      @stdout.close unless @stdout.closed?
-      @stderr.close unless @stderr.closed?
-      @reader_thread&.kill
-      @stderr_thread&.kill
-    rescue StandardError
-      # Clean up resources during unexpected termination
-    ensure
-      # Release any buffered responses / awaiting markers
-      @mutex.synchronize do
-        @pending.clear
-        @awaiting.clear
+      # 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.
+      forget_transport_thread_state
+      teardown_transport(@transport_lock.synchronize { @transport_generation })
+    end
+
+    # What one teardown claimed: the handles of one process, and the
+    # generation the transport moved on to when it claimed them. Torn down
+    # from the record, not from the transport, so a teardown that finishes
+    # late — after a host request has already established the next process
+    # — dismantles only what it claimed.
+    TornDownTransport = Struct.new(:generation, :stdin, :stdout, :stderr, :wait_thread, :reader_thread,
+                                   :stderr_thread, :session, keyword_init: true)
+
+    # Tear down the process of one transport generation.
+    #
+    # The teardown claims the process under the transport lock — the handles
+    # come off the transport and the generation moves on, so a request judged
+    # current is written before this or not at all, and a second teardown of
+    # the same process (the host's `cleanup` racing the reader's own, or the
+    # reverse) finds nothing to claim. Everything after the claim works on the
+    # claimed handles alone: a `cleanup` that ran ahead of it may already have
+    # let the host establish a replacement, and a reader whose teardown
+    # finishes only now used to clear that replacement's session, handles,
+    # reader and handshake on its way out — leaving a live, re-sent
+    # subscription registered on a transport that had just forgotten its
+    # process.
+    # @param generation [Integer] the transport generation to tear down; a
+    #   generation that has moved on is not this teardown's to touch
+    # @return [void]
+    def teardown_transport(generation)
+      claimed = claim_transport(generation)
+      return unless claimed
+
+      begin
+        park_open_subscriptions(claimed)
+        terminate_server_process(claimed.wait_thread)
+        claimed.stdout.close unless claimed.stdout.nil? || claimed.stdout.closed?
+        claimed.stderr.close unless claimed.stderr.nil? || claimed.stderr.closed?
+        # The reader calls this itself when the process exits on its own, and a
+        # thread that kills itself here would abandon the rest of the shutdown —
+        # including the restart that a live subscription depends on. It is at
+        # EOF by then and returns on its own.
+        claimed.reader_thread&.kill unless claimed.reader_thread.equal?(Thread.current)
+        claimed.stderr_thread&.kill
+      rescue StandardError
+        # Clean up resources during unexpected termination
+      ensure
+        forget_torn_down_transport(claimed)
+      end
+    end
+
+    # Take the process of a transport generation off the transport, for one
+    # teardown to dismantle. Under the transport lock: the handles and the
+    # generation change together, and closing stdin here is what makes a
+    # request judged current either already written or never written.
+    # @param generation [Integer] the transport generation to claim
+    # @return [TornDownTransport, nil] the claim, or nil when that generation
+    #   is not the live one (already claimed, or replaced)
+    def claim_transport(generation)
+      @transport_lock.synchronize do
+        return nil unless @stdin && generation == @transport_generation
+
+        # Past this point the reader threads speak for a transport that is
+        # being dismantled on purpose: their EOF must not retire whatever
+        # replaces it. A 2025-11-25 handshake opened a session that ends
+        # with the process. A stateless 2026-07-28 peer holds none: a task it
+        # created outlives the connection exactly as it does over sessionless
+        # HTTP, so the process that replaces this one is asked about it
+        # rather than the task being written off as gone with a session that
+        # never existed.
+        bump_session_epoch if ending_session?
+        @transport_generation += 1
+        claimed = TornDownTransport.new(generation: @transport_generation, stdin: @stdin, stdout: @stdout,
+                                        stderr: @stderr, wait_thread: @wait_thread, reader_thread: @reader_thread,
+                                        stderr_thread: @stderr_thread, session: @session)
+        @stdin.close unless @stdin.closed?
+        @stdin = @stdout = @stderr = @wait_thread = @reader_thread = @stderr_thread = nil
+        # The ids still outstanding went out on the process just claimed and
+        # will never be answered. They are recorded as dropped here, at the
+        # claim, so their waiters fail on that record — promptly, woken here —
+        # even when a replacement is established before this teardown
+        # finishes and {#forget_torn_down_transport} therefore leaves the
+        # replacement's bookkeeping alone.
+        @mutex.synchronize do
+          dropped_requests.merge(@awaiting.keys)
+          @cond.broadcast
+        end
+        claimed
+      end
+    end
+
+    # Subscriptions do not survive the process: keep the ones the host still
+    # wants so they are re-sent once the process is re-established
+    # (basic/patterns/subscriptions "Graceful Closure"). They are moved to
+    # the pending list outside the registry lock, since a subscription being
+    # opened holds its own lock while taking that one.
+    #
+    # Only the claimed process's, the way the pipe teardown is. Draining the
+    # registry took whatever it held at that moment, and a teardown that got
+    # here after a host request had established the replacement parked the
+    # streams that replacement was already serving: their outstanding listen
+    # ids were discarded with the dead process's, so `close` had nothing left
+    # to cancel and the server went on serving a stream this client could no
+    # longer name. A subscription carries the generation its listen went out
+    # on ({MCPClient::Subscription#with_open_id}), which is the same question
+    # the pipe asks, asked of the registry.
+    #
+    # Enqueued through the one lock a deferred hand-over writes under too,
+    # since a listen write failing on the process being torn down lands in
+    # the window between the snapshot and the write
+    # (JsonRpcTransport#queue_subscriptions_of_ended_process, which also
+    # forgets the listen ids this process was holding).
+    # @param claimed [TornDownTransport] what this teardown claimed
+    # @return [void]
+    def park_open_subscriptions(claimed)
+      open_subscriptions = subscriptions_mutex.synchronize do
+        mine, theirs = subscriptions.values.partition { |subscription| claimed_subscription?(subscription, claimed) }
+        subscriptions.keep_if { |_, subscription| theirs.include?(subscription) }
+        mine
+      end
+      open_subscriptions.each(&:mark_reconnecting)
+      queue_subscriptions_of_ended_process(open_subscriptions.select(&:reconnectable?))
+    end
+
+    # Whether a registered subscription belongs to the process a teardown
+    # claimed. The claim's generation is the one the transport moved *to*, so
+    # the process it took is everything below it; a subscription opened on the
+    # replacement carries a higher one. One that never recorded a generation
+    # is treated as the claim's, which is what a registry entry was before
+    # the stamp existed.
+    # @param subscription [MCPClient::Subscription]
+    # @param claimed [TornDownTransport] what this teardown claimed
+    # @return [Boolean]
+    def claimed_subscription?(subscription, claimed)
+      generation = subscription.open_generation
+      generation.nil? || generation < claimed.generation
+    end
+
+    # The last word of a teardown, whatever else went wrong: the record of the
+    # process it claimed is ended, and — only if no process has been
+    # established since the claim — the transport forgets its session and its
+    # handshake, and wakes the requests that will never be answered.
+    #
+    # No further response can arrive on a transport that is being dismantled,
+    # so nothing is outstanding any more. Responses that already arrived are
+    # kept: they are answers this client received and has not handed to their
+    # caller yet, and a restart happening in that window must not turn a
+    # completed request into a timeout. Each one belongs to a caller that is
+    # about to take it out of the map, so keeping them cannot accumulate.
+    # Waiters are woken so a request that will never be answered re-checks its
+    # deadline rather than blocking on a reader thread that has been killed.
+    # A replacement established meanwhile owns whatever is outstanding now,
+    # and its handshake and session are its own.
+    # @param claimed [TornDownTransport] what this teardown claimed
+    # @return [void]
+    def forget_torn_down_transport(claimed)
+      # The process this session was is gone, whatever else went wrong above.
+      # Its record outlives it: it is what the next session's re-send of the
+      # open subscriptions asks about (JsonRpcTransport#reopen_subscriptions).
+      claimed.session&.ended
+      # Asked and acted on in one step, under the lock a replacement is
+      # established through. Asking first and writing afterwards let the
+      # answer go stale in between: a host request that established the
+      # replacement in that window did so *after* both checks passed, and
+      # this teardown then marked its outstanding requests dropped and left
+      # it uninitialized with no session — a live process the transport could
+      # no longer name.
+      @transport_lock.synchronize do
+        # Either signal says a process has been established since the claim:
+        # `connect` moves the generation on, and the handshake that follows
+        # records a new session.
+        next if @transport_generation != claimed.generation
+        next unless @session.equal?(claimed.session)
+
+        @mutex.synchronize do
+          # The ids still outstanding are recorded as dropped: their waiters
+          # fail on that record, whenever they next run, rather than wait out
+          # their timeouts because the restart cleared the retirement first.
+          dropped_requests.merge(@awaiting.keys)
+          @response_arrivals&.clear
+          @awaiting.clear
+          @cond.broadcast
+        end
+        @session = nil
+        # Cached results belong to the process that just ended.
+        clear_result_cache
+        # The next request re-establishes the process and, on a modern
+        # server, re-sends the subscriptions the host still holds.
+        @initialized = false
       end
-      @stdin = @stdout = @stderr = @wait_thread = @reader_thread = @stderr_thread = nil
+    end
+
+    # The server process ended on its own (its stdout reached EOF). MCP
+    # 2026-07-28 stdio "Unexpected Termination": the client SHOULD restart
+    # it; in-flight requests are lost and subscriptions must be
+    # re-established. Marking the session uninitialized makes the next
+    # request spawn a fresh process and re-open live subscriptions — and a
+    # host that is only waiting for notifications makes no such request, so
+    # an open subscription restarts the process here instead.
+    # @param session [MCPClient::ServerStdio::ChildSession, nil] the record of
+    #   the process that exited; the crash-loop bound only counts an exit this
+    #   path recorded, never a teardown the host asked for
+    #   (see {JsonRpcTransport#crash_looping?})
+    # @param generation [Integer] the transport generation of the process
+    #   that exited; a generation the host has already torn down or replaced
+    #   is not this exit's to handle
+    # @return [void]
+    def handle_server_exit(session = @session, generation = @transport_generation)
+      return unless live_transport?(generation, session)
+
+      @logger.warn('MCP server process ended unexpectedly')
+      # Stamped before the teardown, on the record the teardown retires: this
+      # is the one path that knows the process was not asked to go.
+      session&.exited_unexpectedly
+      # Retired before the teardown bumps the generation past this reader's,
+      # so the exit stays observable the way any other unexpected exit is:
+      # the next request releases the dead handles and negotiates again.
+      retire_transport(generation)
+      teardown_transport(generation)
+      restart_for_open_subscriptions
     end
 
     # Terminate the spawned server process per the MCP 2025-11-25 stdio
@@ -754,23 +1282,84 @@ module MCPClient
     # so wait for the process to exit on its own; if it does not exit within
     # the grace period send SIGTERM, wait again, and finally send SIGKILL.
     # @return [void]
-    def terminate_server_process
-      return unless @wait_thread
-      return if @wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+    # @param wait_thread [Process::Waiter, nil] the process to wait for; the
+    #   one a teardown claimed, since the transport may hold a replacement by now
+    # @return [void]
+    def terminate_server_process(wait_thread = @wait_thread)
+      return unless wait_thread
+      return if wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+
+      signal_server_process('TERM', wait_thread)
+      return if wait_thread.join(SHUTDOWN_GRACE_PERIOD)
 
-      signal_server_process('TERM')
-      return if @wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+      signal_server_process('KILL', wait_thread)
+      wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+    end
 
-      signal_server_process('KILL')
-      @wait_thread.join(SHUTDOWN_GRACE_PERIOD)
+    # Cancel a subscription: on stdio there is no per-request stream to
+    # close, so the client sends notifications/cancelled referencing the
+    # subscriptions/listen request id.
+    # @param subscription [MCPClient::Subscription]
+    # @return [void]
+    def cancel_subscription(subscription)
+      # Closed first: a re-open in flight holds the subscription's lock until
+      # it has taken its new id, so the id unregistered and cancelled below is
+      # the one the server was actually sent.
+      subscription.finish(by_client: true)
+      unregister_subscription(subscription)
+      subscriptions_mutex.synchronize { resource_subscriptions.delete_if { |_uri, sub| sub.equal?(subscription) } }
+      cancel_outstanding_listens(subscription)
+    end
+
+    # Tell the server the client has stopped reading every listen request it
+    # wrote for this subscription on the process this pipe belongs to.
+    #
+    # Not just the one the subscription is on: a second listen written for it
+    # on one process — a hand-over the queue duplicated, say — leaves the
+    # server serving the first stream, and naming only the newest id left that
+    # one open with the client no longer able to refer to it.
+    #
+    # The subscription's *current* id is not named on top of those. It used to
+    # be, so that a handle closed between taking an id and writing its request
+    # was cancelled anyway — but that cancellation named a request the server
+    # had not been sent, and reached the pipe ahead of it. Every id this
+    # client wrote is recorded ({MCPClient::Subscription#record_outstanding_listen}),
+    # so a written id is here already; an id that is only assigned is the
+    # opener's to cancel, once it has actually written it.
+    #
+    # Ids written to a pipe other than this one are left where they are: the
+    # process reading this one was never sent those requests, and naming them
+    # on it would cancel requests it has never seen
+    # ({MCPClient::Subscription#take_outstanding_listens}).
+    # @param subscription [MCPClient::Subscription]
+    # @param io [IO, nil] the pipe to cancel on; defaults to the live process's
+    #   stdin, and is pinned by a caller that is cancelling ids it wrote to one
+    #   particular process (see {JsonRpcTransport#open_subscription})
+    # @return [void]
+    def cancel_outstanding_listens(subscription, io: @stdin)
+      subscription.take_outstanding_listens(io).each { |id| send_subscription_cancellation(id, io: io) }
+    end
+
+    # Tell the server the client closed a subscriptions/listen request.
+    # @param id [Integer, String, nil] the listen request id
+    # @param io [IO, nil] the pipe to write the cancellation to
+    # @return [void]
+    def send_subscription_cancellation(id, io: @stdin)
+      return unless io && id
+
+      notif = build_jsonrpc_notification('notifications/cancelled',
+                                         { 'requestId' => id, 'reason' => 'Client closed subscription' })
+      io.puts(notif.to_json)
+    rescue StandardError => e
+      @logger.debug("Failed to send subscription cancellation: #{e.message}")
     end
 
     # Send a signal to the server process, tolerating a process that has
     # already exited or cannot be signalled.
     # @param signal [String] signal name, e.g. 'TERM' or 'KILL'
     # @return [void]
-    def signal_server_process(signal)
-      Process.kill(signal, @wait_thread.pid)
+    def signal_server_process(signal, wait_thread = @wait_thread)
+      Process.kill(signal, wait_thread.pid)
     rescue Errno::ESRCH, Errno::EPERM => e
       @logger.debug("Could not send SIG#{signal} to server process: #{e.class}")
     end