mcp 1.1.0 → 1.3.0

data/lib/mcp/client/oauth/flow.rb

@@ -33,9 +33,15 @@ module MCP
         def run!(server_url:, resource_metadata_url: nil, scope: nil)
           # The `resource_metadata` URL ships in `WWW-Authenticate` and is the very
           # first thing we contact in the OAuth flow, so it has to clear the same
-          # Communication Security bar as the OAuth endpoints downstream.
+          # Communication Security bar as the OAuth endpoints downstream, and it has to
+          # point back at the server that issued the challenge.
           if resource_metadata_url
             ensure_secure_url!(resource_metadata_url, label: "WWW-Authenticate resource_metadata URL")
+            ensure_same_origin!(
+              resource_metadata_url,
+              label: "WWW-Authenticate resource_metadata URL",
+              server_url: server_url,
+            )
           end
 
           prm, authorization_server = locate_authorization_server(
@@ -49,7 +55,11 @@ module MCP
           # being redirected to credentials minted for a different audience.
           resource = canonical_resource(server_url: server_url, prm_resource: prm&.dig("resource"))
 
-          as_metadata = authorization_server_metadata(authorization_server: authorization_server, legacy: prm.nil?)
+          as_metadata = authorization_server_metadata(
+            authorization_server: authorization_server,
+            legacy: prm.nil?,
+            server_url: server_url,
+          )
 
           case provider_authorization_flow
           when :client_credentials
@@ -212,6 +222,11 @@ module MCP
 
           if resource_metadata_url
             ensure_secure_url!(resource_metadata_url, label: "WWW-Authenticate resource_metadata URL")
+            ensure_same_origin!(
+              resource_metadata_url,
+              label: "WWW-Authenticate resource_metadata URL",
+              server_url: server_url,
+            )
           end
 
           prm, authorization_server = locate_authorization_server(
@@ -221,7 +236,11 @@ module MCP
 
           resource = canonical_resource(server_url: server_url, prm_resource: prm&.dig("resource"))
 
-          as_metadata = authorization_server_metadata(authorization_server: authorization_server, legacy: prm.nil?)
+          as_metadata = authorization_server_metadata(
+            authorization_server: authorization_server,
+            legacy: prm.nil?,
+            server_url: server_url,
+          )
 
           client_info = if have_stored_client_info
             # Pre-registered / DCR-issued `client_information` always wins: if the user picked an explicit identity,
@@ -296,6 +315,11 @@ module MCP
           if prm
             authorization_server = first_authorization_server(prm)
             ensure_secure_url!(authorization_server, label: "PRM `authorization_servers` entry")
+            ensure_routable_destination!(
+              authorization_server,
+              label: "PRM `authorization_servers` entry",
+              server_url: server_url,
+            )
             [prm, authorization_server]
           else
             authorization_base = server_origin!(server_url)
@@ -311,7 +335,7 @@ module MCP
         # and a pre-PRM server may host its OAuth endpoints under a path prefix whose `issuer` legitimately differs from
         # the origin the metadata was discovered at (neither the TypeScript nor the Python SDK validates the issuer on this path).
         # When even the metadata document is absent, the legacy spec's default endpoints are used.
-        def authorization_server_metadata(authorization_server:, legacy:)
+        def authorization_server_metadata(authorization_server:, legacy:, server_url:)
           metadata = if legacy
             begin
               fetch_authorization_server_metadata(issuer_url: authorization_server)
@@ -324,7 +348,7 @@ module MCP
             end
           end
 
-          ensure_secure_endpoints!(metadata)
+          ensure_secure_endpoints!(metadata, server_url: server_url)
           metadata
         end
 
@@ -445,13 +469,72 @@ module MCP
             "#{label} #{url.inspect} is not over HTTPS; refusing to use it (MCP authorization Communication Security)."
         end
 
-        def ensure_secure_endpoints!(as_metadata)
+        # Requires a URL the *server* chose to sit on the origin the *caller* chose.
+        #
+        # Protected Resource Metadata describes the MCP server itself, so on a real deployment it is
+        # published on that server's own origin. Without this check a `WWW-Authenticate` challenge
+        # can aim the first request of the flow at any host the client can route to: the URL arrives
+        # from the network, it is fetched before the user approves anything, and the `resource` check that
+        # runs afterwards cannot un-send the request.
+        #
+        # RFC 9728 does not itself require the metadata URL to be same-origin, so this is stricter than
+        # the specification. It is enforced unconditionally because no known deployment publishes its PRM
+        # anywhere else, and because the alternative (`Discovery.private_network_host?`) cannot see
+        # internal hosts that are named rather than addressed.
+        # https://www.rfc-editor.org/rfc/rfc9728#section-7.7
+        def ensure_same_origin!(url, label:, server_url:)
+          return if Discovery.same_origin?(url, server_url)
+
+          raise AuthorizationError,
+            "#{label} #{sanitized_url(url).inspect} is not on the MCP server origin " \
+              "#{sanitized_url(server_url).inspect}; refusing to fetch it."
+        end
+
+        # Refuses an OAuth URL that points into a private, loopback, link-local, or unique-local address,
+        # which is the SSRF precaution RFC 9728 Section 7.7 and the MCP security best practices ask clients to take.
+        #
+        # The carve-out matters as much as the rule: when the MCP server the caller configured is itself on such an address,
+        # the whole flow is already inside that network and the authorization server legitimately lives there too.
+        # That covers `http://localhost` development, the conformance harness (which runs the MCP server and
+        # the authorization server on two loopback ports), and deployments that never leave a corporate network.
+        # Only a server reachable on the public internet is barred from steering the client inward.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization
+        def ensure_routable_destination!(url, label:, server_url:)
+          return unless private_network_url?(url)
+          return if private_network_url?(server_url)
+
+          raise AuthorizationError,
+            "#{label} #{sanitized_url(url).inspect} points into a private network range, " \
+              "which the MCP server at #{sanitized_url(server_url).inspect} is not on; refusing to contact it."
+        end
+
+        def ensure_secure_endpoints!(as_metadata, server_url:)
           ["authorization_endpoint", "token_endpoint", "registration_endpoint"].each do |key|
             endpoint = as_metadata[key]
-            ensure_secure_url!(endpoint, label: "Authorization server #{key}") if endpoint
+            next unless endpoint
+
+            ensure_secure_url!(endpoint, label: "Authorization server #{key}")
+            ensure_routable_destination!(endpoint, label: "Authorization server #{key}", server_url: server_url)
           end
         end
 
+        # `ensure_secure_url!` runs first at every call site and already rejects a URL that fails to parse,
+        # so the rescue here is a backstop rather than a leniency.
+        def private_network_url?(url)
+          Discovery.private_network_host?(URI.parse(url.to_s).host)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        # Strips userinfo and query before a URL reaches an exception message, the same precaution `MCP::Client::HTTP` takes
+        # when it reports a URL: these values come off the network and can carry credentials that would otherwise land in
+        # every log destination the error passes through.
+        def sanitized_url(url)
+          Discovery.canonicalize_origin_and_path(url)
+        rescue URI::Error
+          url.to_s
+        end
+
         # Per RFC 8414 Section 3.3, the AS metadata document's `issuer` value MUST be
         # identical (literal byte-for-byte equality, no normalization) to
         # the issuer URL the client used to discover that document. This guards
@@ -938,32 +1021,71 @@ module MCP
         end
 
         def http_get(url)
-          http_client.get(url)
+          bounded_request do |on_data|
+            http_client.get(url) do |req|
+              req.options.on_data = on_data
+            end
+          end
         end
 
         def http_post_json(url, body)
-          http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/json"
-            req.headers["Accept"] = "application/json"
-            req.body = JSON.generate(body)
+          bounded_request do |on_data|
+            http_client.post(url) do |req|
+              req.headers["Content-Type"] = "application/json"
+              req.headers["Accept"] = "application/json"
+              req.options.on_data = on_data
+              req.body = JSON.generate(body)
+            end
           end
         end
 
         def http_post_form(url, form, headers: {})
-          http_client.post(url) do |req|
-            req.headers["Content-Type"] = "application/x-www-form-urlencoded"
-            req.headers["Accept"] = "application/json"
-            headers.each { |key, value| req.headers[key] = value }
-            req.body = URI.encode_www_form(form)
+          bounded_request do |on_data|
+            http_client.post(url) do |req|
+              req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+              req.headers["Accept"] = "application/json"
+
+              headers.each do |key, value|
+                req.headers[key] = value
+              end
+
+              req.options.on_data = on_data
+              req.body = URI.encode_www_form(form)
+            end
           end
         end
 
+        # Issues a request with the response body bounded as it arrives, and returns the status paired with
+        # that body. An over-cap response is refused rather than truncated: a partial discovery or token document
+        # cannot be validated, and `fetch_metadata_json` must not fall through to the next candidate URL either,
+        # since the same server would serve the same body.
+        def bounded_request
+          bounded = BoundedBody.new
+
+          response = yield(bounded.on_data)
+
+          bounded.response_for(response)
+        rescue BoundedBody::TooLargeError => e
+          raise AuthorizationError, "#{e.message}."
+        end
+
         def http_client
           @http_client ||= @http_client_factory.call
         end
 
+        # Deliberately built without redirect-following middleware. Every destination check in
+        # this class runs against the URL as written, before the request goes out, so a connection
+        # that transparently followed a `3xx` would let a server reach a host the checks just refused.
+        # A caller passing `http_client_factory:` takes on that responsibility: add redirect following here
+        # and the guards above only cover the first hop.
+        #
+        # `Accept-Encoding` is deliberately left unset. `Net::HTTP::GenericRequest` negotiates it and decodes
+        # the response only while the caller has not claimed that header; assigning it turns `decode_content` off,
+        # which would silently move `BoundedBody`'s cap onto compressed bytes and let a small body expand past it
+        # after the check.
         def default_http_client
           require "faraday"
+
           Faraday.new do |faraday|
             faraday.headers["Accept"] = "application/json"
           end

data/lib/mcp/client/oauth/id_jag_token_exchange.rb

@@ -34,10 +34,13 @@ module MCP
           def request(token_endpoint:, id_token:, client_id:, audience:, resource:, http_client: nil)
             http_client ||= default_http_client
 
+            bounded = BoundedBody.new
+
             response = begin
-              http_client.post(token_endpoint) do |req|
+              raw_response = http_client.post(token_endpoint) do |req|
                 req.headers["Content-Type"] = "application/x-www-form-urlencoded"
                 req.headers["Accept"] = "application/json"
+                req.options.on_data = bounded.on_data
                 req.body = URI.encode_www_form(
                   "grant_type" => GRANT_TYPE,
                   "subject_token" => id_token,
@@ -48,6 +51,10 @@ module MCP
                   "client_id" => client_id,
                 )
               end
+
+              bounded.response_for(raw_response)
+            rescue BoundedBody::TooLargeError => e
+              raise ExchangeError, "#{e.message}."
             rescue Faraday::Error => e
               raise ExchangeError, "Token exchange request to #{token_endpoint} failed: #{e.class}: #{e.message}."
             end
@@ -88,8 +95,12 @@ module MCP
             assertion
           end
 
+          # `Accept-Encoding` is deliberately left unset, for the same reason as `Flow#default_http_client`:
+          # claiming that header turns Net::HTTP's `decode_content` off and would move `BoundedBody`'s cap
+          # onto compressed bytes.
           def default_http_client
             require "faraday"
+
             Faraday.new do |faraday|
               faraday.headers["Accept"] = "application/json"
             end

data/lib/mcp/client/oauth.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "oauth/bounded_body"
 require_relative "oauth/discovery"
 require_relative "oauth/flow"
 require_relative "oauth/in_memory_storage"

data/lib/mcp/client/stdio.rb

@@ -7,7 +7,9 @@ require "timeout"
 require_relative "../../json_rpc_handler"
 require_relative "../configuration"
 require_relative "../methods"
+require_relative "../protocol_deprecations"
 require_relative "../version"
+require_relative "modern_envelope"
 
 module MCP
   class Client
@@ -26,6 +28,12 @@ module MCP
       # realistic JSON-RPC frame, including base64-embedded images.
       MAX_LINE_BYTES = 4 * 1024 * 1024
 
+      # Seconds the `server/discover` probe may wait when no `read_timeout` was configured.
+      # A compliant legacy server answers the probe with `-32601` immediately, but a non-compliant one
+      # that silently drops unknown methods would otherwise block `connect(mode: :auto)` forever.
+      # Matches the C# SDK's `DiscoverProbeTimeout` default.
+      DEFAULT_DISCOVER_PROBE_TIMEOUT = 5
+
       attr_reader :command, :args, :env, :server_info
 
       def initialize(command:, args: [], env: nil, read_timeout: nil, max_line_bytes: MAX_LINE_BYTES)
@@ -49,6 +57,9 @@ module MCP
         @started = false
         @initialized = false
         @server_info = nil
+        @modern_protocol_version = nil
+        @modern_client_info = nil
+        @modern_capabilities = nil
         # Serializes writes to `@stdin` so a request line and a notification line emitted from
         # different threads (e.g. cancellation) cannot interleave on the wire.
         @write_mutex = Mutex.new
@@ -66,86 +77,57 @@ module MCP
       #
       # @param client_info [Hash, nil] `{ name:, version: }` identifying the client.
       #   Defaults to `{ name: "mcp-ruby-client", version: MCP::VERSION }`.
-      # @param protocol_version [String, nil] Protocol version to offer. Defaults
-      #   to `MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION`.
+      # @param protocol_version [String, nil] Protocol version to offer on the legacy handshake.
+      #   Defaults to `MCP::Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION`; a modern version
+      #   raises `ArgumentError` here (modern versions are selected via `mode: :modern`/`:auto`).
       # @param capabilities [Hash] Capabilities advertised by the client. Defaults to `{}`.
       # @return [Hash] The server's `InitializeResult`.
       # @raise [RequestHandlerError] If the server responds with a JSON-RPC error,
       #   a malformed result, or an unsupported protocol version.
+      # @param mode [Symbol] Lifecycle selection (SEP-2575): `:legacy` (default) performs
+      #   the handshake below, `:modern` skips it and probes `server/discover`,
+      #   and `:auto` probes `server/discover` first, falling back to the legacy handshake
+      #   when the server does not serve a mutually supported modern version.
       # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
-      def connect(client_info: nil, protocol_version: nil, capabilities: {})
-        return @server_info if @initialized
+      def connect(client_info: nil, protocol_version: nil, capabilities: {}, mode: :legacy)
+        return @server_info if connected?
+
+        # Validated before `start` so a pure argument error never spawns the server process.
+        MCP::Configuration.reject_modern_handshake_version!(protocol_version) if mode == :legacy
 
         start unless @started
 
         client_info ||= { name: "mcp-ruby-client", version: MCP::VERSION }
-        protocol_version ||= MCP::Configuration::LATEST_STABLE_PROTOCOL_VERSION
-
-        init_request = {
-          jsonrpc: JsonRpcHandler::Version::V2_0,
-          id: SecureRandom.uuid,
-          method: MCP::Methods::INITIALIZE,
-          params: {
-            protocolVersion: protocol_version,
-            capabilities: capabilities,
-            clientInfo: client_info,
-          },
-        }
-
-        write_message(init_request)
-        response = read_response(init_request)
 
-        if response.key?("error")
-          error = response["error"]
-          raise RequestHandlerError.new(
-            "Server initialization failed: #{error["message"]}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        unless response["result"].is_a?(Hash)
-          raise RequestHandlerError.new(
-            "Server initialization failed: missing result in response",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
-        end
-
-        @server_info = response["result"]
-
-        negotiated_protocol_version = @server_info["protocolVersion"]
-        unless MCP::Configuration::SUPPORTED_STABLE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
-          # Per spec, if the client does not support the server's returned protocol version,
-          # the client SHOULD disconnect. Roll back the cached `InitializeResult` before
-          # raising so a retry starts without a stale `server_info`.
-          # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
-          @server_info = nil
-          raise RequestHandlerError.new(
-            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
-            { method: MCP::Methods::INITIALIZE },
-            error_type: :internal_error,
-          )
+        case mode
+        when :legacy
+          connect_legacy(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+        when :modern
+          connect_modern(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+        when :auto
+          connect_auto(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+        else
+          raise ArgumentError, "mode must be :legacy, :modern, or :auto"
         end
+      end
 
-        begin
-          notification = {
-            jsonrpc: JsonRpcHandler::Version::V2_0,
-            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
-          }
-          write_message(notification)
-        rescue StandardError
-          @server_info = nil
-          raise
-        end
+      # Whether the transport operates in the stateless modern lifecycle (SEP-2575):
+      # no handshake was performed and every request carries the `_meta` envelope.
+      def modern?
+        !@modern_client_info.nil?
+      end
 
-        @initialized = true
-        @server_info
+      # The protocol version in use on this connection, independent of its era:
+      # negotiated by `initialize` (legacy) or adopted via `server/discover` (modern).
+      # Returns `nil` before `connect` and after `close`.
+      def protocol_version
+        @modern_protocol_version || (@server_info && @server_info["protocolVersion"])
       end
 
-      # Returns true once `connect` has completed the handshake. Returns false before the handshake and after `close`.
+      # Returns true once `connect` has completed the handshake or adopted the modern lifecycle.
+      # Returns false before the handshake and after `close`.
       def connected?
-        @initialized
+        @initialized || modern?
       end
 
       # Transports may yield once the request line has been written to `@stdin`.
@@ -153,7 +135,16 @@ module MCP
       # write does not race ahead of the request write on the wire. The yield happens inside `@write_mutex`,
       # so any subsequent `send_notification` write waits for the mutex and is guaranteed to land after the request.
       def send_request(request:)
-        raise "MCP::Client#connect must be called before sending requests." unless @initialized
+        method = request[:method] || request["method"]
+        if method == MCP::Methods::SERVER_DISCOVER
+          # `server/discover` (SEP-2575) is sessionless capability discovery that
+          # works before (or instead of) `connect`.
+          start unless @started
+        elsif !connected?
+          raise "MCP::Client#connect must be called before sending requests."
+        end
+
+        request = stamp_modern(request)
 
         @write_mutex.synchronize do
           write_message(request)
@@ -166,7 +157,7 @@ module MCP
       # `notifications/cancelled` for an in-flight request.
       def send_notification(notification:)
         start unless @started
-        connect unless @initialized
+        connect unless connected?
 
         @write_mutex.synchronize { write_message(notification) }
         nil
@@ -228,10 +219,196 @@ module MCP
         @started = false
         @initialized = false
         @server_info = nil
+        leave_modern_mode
       end
 
       private
 
+      def connect_legacy(client_info:, protocol_version:, capabilities:)
+        protocol_version ||= MCP::Configuration::LATEST_HANDSHAKE_PROTOCOL_VERSION
+
+        init_request = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::INITIALIZE,
+          params: {
+            protocolVersion: protocol_version,
+            capabilities: capabilities,
+            clientInfo: client_info,
+          },
+        }
+
+        write_message(init_request)
+        response = read_response(init_request)
+
+        if response.key?("error")
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server initialization failed: #{error["message"]}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        unless response["result"].is_a?(Hash)
+          raise RequestHandlerError.new(
+            "Server initialization failed: missing result in response",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        @server_info = response["result"]
+
+        negotiated_protocol_version = @server_info["protocolVersion"]
+        unless MCP::Configuration::SUPPORTED_HANDSHAKE_PROTOCOL_VERSIONS.include?(negotiated_protocol_version)
+          # Per spec, if the client does not support the server's returned protocol version,
+          # the client SHOULD disconnect. A modern version is rejected along with unknown ones:
+          # the handshake settles on a legacy version by definition, and the TypeScript and Python clients refuse
+          # a modern counter-offer the same way. Roll back the cached `InitializeResult` before raising
+          # so a retry starts without a stale `server_info`.
+          # https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#version-negotiation
+          @server_info = nil
+          raise RequestHandlerError.new(
+            "Server initialization failed: unsupported protocol version #{negotiated_protocol_version.inspect}",
+            { method: MCP::Methods::INITIALIZE },
+            error_type: :internal_error,
+          )
+        end
+
+        begin
+          notification = {
+            jsonrpc: JsonRpcHandler::Version::V2_0,
+            method: MCP::Methods::NOTIFICATIONS_INITIALIZED,
+          }
+          write_message(notification)
+        rescue StandardError
+          @server_info = nil
+          raise
+        end
+
+        @initialized = true
+        @server_info
+      end
+
+      # Enters the modern lifecycle by probing `server/discover` at the requested (or latest) modern version.
+      # No `initialize` or `notifications/initialized` is sent; the probe response becomes `server_info`.
+      def connect_modern(client_info:, protocol_version:, capabilities:)
+        version = protocol_version || MCP::Configuration::LATEST_MODERN_PROTOCOL_VERSION
+        unless MCP::Configuration.modern_protocol_version?(version)
+          raise ArgumentError, "protocol_version #{version.inspect} is not a supported modern protocol version"
+        end
+
+        @modern_protocol_version = version
+        @modern_client_info = client_info
+        @modern_capabilities = capabilities || {}
+
+        begin
+          result = with_probe_read_timeout { probe_discover }
+        rescue StandardError
+          leave_modern_mode
+          raise
+        end
+
+        supported = result["supportedVersions"]
+        unless supported.is_a?(Array) && supported.include?(version)
+          leave_modern_mode
+          raise RequestHandlerError.new(
+            "Server discovery failed: no mutually supported modern protocol version " \
+              "(server supports #{supported.inspect})",
+            { method: MCP::Methods::SERVER_DISCOVER },
+            error_type: :internal_error,
+          )
+        end
+
+        # SEP-2577 deprecates roots and sampling at 2026-07-28, the revision every modern connection speaks,
+        # so the warning lives here now that the handshake cannot land on one.
+        MCP::ProtocolDeprecations.warn_for_client_capabilities(capabilities, protocol_version: version, uplevel: 1)
+
+        @server_info = result
+        @server_info
+      end
+
+      # Probes `server/discover` and adopts the modern lifecycle when the server serves
+      # a mutually supported modern version; otherwise falls back to the legacy handshake.
+      # The fallback intentionally covers a successful discovery without a mutual modern
+      # version as well: during the 2026-07-28 rollout a server may answer discovery while
+      # only serving legacy versions.
+      def connect_auto(client_info:, protocol_version:, capabilities:)
+        modern_pin = protocol_version if protocol_version && MCP::Configuration.modern_protocol_version?(protocol_version)
+        connect_modern(client_info: client_info, protocol_version: modern_pin, capabilities: capabilities)
+      rescue RequestHandlerError
+        # An explicitly requested modern version is never downgraded by the fallback: the legacy handshake cannot negotiate it,
+        # so the probe's failure is the real answer and propagates.
+        raise if modern_pin
+
+        connect_legacy(client_info: client_info, protocol_version: protocol_version, capabilities: capabilities)
+      end
+
+      def leave_modern_mode
+        @modern_protocol_version = nil
+        @modern_client_info = nil
+        @modern_capabilities = nil
+      end
+
+      # Bounds the probe read when the caller configured no `read_timeout`, and only for the probe:
+      # regular requests keep the unbounded default so long-running tools are unaffected.
+      # The timeout surfaces as a `RequestHandlerError`, which `connect_auto` treats as legacy evidence
+      # and falls back on.
+      def with_probe_read_timeout
+        return yield if @read_timeout
+
+        @read_timeout = DEFAULT_DISCOVER_PROBE_TIMEOUT
+        begin
+          yield
+        ensure
+          @read_timeout = nil
+        end
+      end
+
+      def probe_discover
+        request = {
+          jsonrpc: JsonRpcHandler::Version::V2_0,
+          id: SecureRandom.uuid,
+          method: MCP::Methods::SERVER_DISCOVER,
+        }
+
+        @write_mutex.synchronize { write_message(stamp_modern(request)) }
+        response = read_response(request)
+
+        if response.key?("error")
+          error = response["error"]
+          raise RequestHandlerError.new(
+            "Server discovery failed: #{error["message"]}",
+            { method: MCP::Methods::SERVER_DISCOVER },
+            error_type: :internal_error,
+          )
+        end
+
+        result = response["result"]
+        unless result.is_a?(Hash)
+          raise RequestHandlerError.new(
+            "Server discovery failed: missing result in response",
+            { method: MCP::Methods::SERVER_DISCOVER },
+            error_type: :internal_error,
+          )
+        end
+
+        result
+      end
+
+      # Modern requests (never notifications, whose `_meta` has no envelope) carry the SEP-2575 triple.
+      def stamp_modern(request)
+        return request unless modern? && (request[:id] || request["id"])
+
+        ModernEnvelope.stamp(
+          request,
+          protocol_version: @modern_protocol_version,
+          client_info: @modern_client_info,
+          capabilities: @modern_capabilities,
+        )
+      end
+
       def write_message(message)
         ensure_running!
         json = JSON.generate(message)