ruby-mcp-client 1.1.0 → 2.0.0

data/lib/mcp_client/elicitation_validator.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require 'uri'
+require 'date'
+require 'time'
+
 module MCPClient
   # Validates elicitation schemas and content per MCP 2025-11-25 spec.
   # Schemas are restricted to flat objects with primitive property types:
@@ -197,9 +201,48 @@ module MCPClient
         errors << "Field '#{field}' must be at most #{prop['maxLength']} characters"
       end
 
+      errors.concat(validate_string_format(field, value, prop['format']))
+
       errors
     end
 
+    # Validate a string value against the schema's format constraint.
+    # The MCP elicitation schema supports email, uri, date, and date-time.
+    # @param field [String] field name
+    # @param value [String] the value
+    # @param format [String, nil] declared format
+    # @return [Array<String>] validation errors
+    def self.validate_string_format(field, value, format)
+      valid = case format
+              when 'email' then value.match?(URI::MailTo::EMAIL_REGEXP)
+              when 'uri' then valid_uri?(value)
+              when 'date' then parseable?(Date, value)
+              when 'date-time' then parseable?(Time, value)
+              else true # No format declared, or an unknown format: not validated
+              end
+
+      valid ? [] : ["Field '#{field}' must be a valid #{format}"]
+    end
+
+    # @param value [String] candidate URI
+    # @return [Boolean] whether the value is an absolute URI
+    def self.valid_uri?(value)
+      uri = URI.parse(value)
+      !uri.scheme.nil?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # @param klass [Class] Date or Time
+    # @param value [String] candidate ISO 8601 value
+    # @return [Boolean] whether the value parses
+    def self.parseable?(klass, value)
+      klass.iso8601(value)
+      true
+    rescue ArgumentError
+      false
+    end
+
     # Validate a number value against its property schema.
     # @param field [String] field name
     # @param value [Object] the value

data/lib/mcp_client/errors.rb

@@ -30,6 +30,30 @@ module MCPClient
     # Raised when there's a connection error with an MCP server
     class ConnectionError < MCPError; end
 
+    # Raised when a request requires a server capability that was not
+    # negotiated during initialization (MCP lifecycle: "Only use capabilities
+    # that were successfully negotiated")
+    class CapabilityError < MCPError; end
+
+    # Raised for an HTTP 403 with a WWW-Authenticate insufficient_scope
+    # challenge (MCP 2025-11-25 / SEP-835). Exposes the challenge parameters
+    # so hosts can run a step-up authorization flow with the required scopes.
+    class InsufficientScopeError < ConnectionError
+      # @return [String, nil] the scopes required by the server's challenge
+      attr_reader :scope
+      # @return [String, nil] the challenge's human-readable error description
+      attr_reader :error_description
+
+      # @param message [String] error message
+      # @param scope [String, nil] scopes from the challenge's scope parameter
+      # @param error_description [String, nil] challenge error_description
+      def initialize(message, scope: nil, error_description: nil)
+        super(message)
+        @scope = scope
+        @error_description = error_description
+      end
+    end
+
     # Raised when the MCP server returns an error response
     class ServerError < MCPError; end
 
@@ -45,7 +69,17 @@ module MCPClient
     # Raised when there's an error in the MCP server transport
     class TransportError < MCPError; end
 
-    # Raised when tool parameters fail validation against JSON schema
+    # Raised when a request exceeded its timeout without receiving a
+    # response. A subclass of TransportError so existing rescues keep
+    # working, but deliberately excluded from automatic retries: the
+    # request may still be executing server-side, so a blind re-send could
+    # run a non-idempotent operation twice (MCP lifecycle: on timeout the
+    # sender SHOULD cancel and stop waiting, not re-send).
+    class RequestTimeoutError < TransportError; end
+
+    # Raised when tool parameters fail validation against the tool's input
+    # schema, or (in strict mode) when a tool result's structuredContent fails
+    # validation against the tool's output schema
     class ValidationError < MCPError; end
 
     # Raised when multiple tools with the same name exist across different servers

data/lib/mcp_client/http_transport_base.rb

@@ -9,6 +9,19 @@ module MCPClient
   module HttpTransportBase
     include JsonRpcCommon
 
+    # Lightweight response wrapper for Faraday exception payloads (Hashes),
+    # so the exception path and the default path share one challenge pipeline.
+    NormalizedResponse = Struct.new(:status, :headers)
+
+    # One auth-param (name = token / quoted-string) as it appears in a
+    # WWW-Authenticate challenge (RFC 7235 §2.1, optional whitespace around '=').
+    AUTH_PARAM = /[A-Za-z0-9._~+-]+\s*=\s*(?:"(?:[^"\\]|\\.)*"|[^,\s]*)/
+    # A run of comma/space separated auth-params anchored at the start of a
+    # string. The run ends before a token that is NOT followed by '=' — the
+    # auth-scheme introducing the next challenge — while commas inside quoted
+    # values are consumed by the quoted-string branch, not treated as boundaries.
+    AUTH_PARAMS_RUN = /\A(?:[\s,]*#{AUTH_PARAM})*/
+
     # Generic JSON-RPC request: send method with params and return result
     # @param method [String] JSON-RPC method name
     # @param params [Hash] parameters for the request
@@ -17,16 +30,35 @@ module MCPClient
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
-    def rpc_request(method, params = {})
+    def rpc_request(method, params = {}, timeout: nil)
       ensure_connected
 
       with_retry do
         request_id = @mutex.synchronize { @request_id += 1 }
         request = build_jsonrpc_request(method, params, request_id)
-        send_jsonrpc_request(request)
+        begin
+          send_jsonrpc_request(request, timeout: timeout)
+        rescue MCPClient::Errors::RequestTimeoutError
+          # MCP lifecycle: on timeout the sender SHOULD issue a cancellation
+          # notification for the abandoned request and stop waiting.
+          send_cancellation_notification(request_id) if cancellable_request?(method, params)
+          raise
+        end
       end
     end
 
+    # Best-effort notifications/cancelled for a request the client stopped
+    # waiting on. Failures are swallowed.
+    # @param request_id [Integer] id of the abandoned request
+    # @return [void]
+    def send_cancellation_notification(request_id)
+      notif = build_jsonrpc_notification('notifications/cancelled',
+                                         { 'requestId' => request_id, 'reason' => 'Request timed out' })
+      send_http_request(notif)
+    rescue StandardError => e
+      @logger.debug("Failed to send cancellation notification: #{e.message}")
+    end
+
     # Send a JSON-RPC notification (no response expected)
     # @param method [String] JSON-RPC method name
     # @param params [Hash] parameters for the notification
@@ -59,6 +91,8 @@ module MCPClient
           @headers.each { |k, v| req.headers[k] = v }
           req.headers['Mcp-Session-Id'] = @session_id
           req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
+          # MCP: authorization MUST be included in every HTTP request
+          @oauth_provider&.apply_authorization(req)
         end
 
         if response.success?
@@ -78,16 +112,19 @@ module MCPClient
       end
     end
 
-    # Validate session ID format for security
+    # Validate session ID format
+    # Per MCP 2025-11-25, the server-assigned session ID "MUST only contain
+    # visible ASCII characters (ranging from 0x21 to 0x7E)" — e.g. a UUID, a
+    # JWT, or a cryptographic hash — and the client MUST echo whatever the
+    # server assigned. A generous length cap guards against abuse.
     # @param session_id [String] the session ID to validate
     # @return [Boolean] true if session ID is valid
     def valid_session_id?(session_id)
       return false unless session_id.is_a?(String)
-      return false if session_id.empty?
 
-      # Session ID should be alphanumeric with optional hyphens and underscores
-      # Length should be reasonable (8-128 characters)
-      session_id.match?(/\A[a-zA-Z0-9\-_]{8,128}\z/)
+      # The 4096-char cap is header-size hygiene, not MCP grammar — the spec
+      # imposes no length limit on session IDs.
+      session_id.match?(/\A[\x21-\x7E]{1,4096}\z/)
     end
 
     # Validate the server's base URL for security
@@ -116,16 +153,6 @@ module MCPClient
 
     private
 
-    # Generate initialization parameters for HTTP MCP protocol
-    # @return [Hash] the initialization parameters
-    def initialization_params
-      {
-        'protocolVersion' => MCPClient::PROTOCOL_VERSION,
-        'capabilities' => {},
-        'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
-      }
-    end
-
     # Perform JSON-RPC initialize handshake with the MCP server
     # @return [void]
     # @raise [MCPClient::Errors::ConnectionError] if initialization fails
@@ -135,11 +162,16 @@ module MCPClient
       @logger.debug("Performing initialize RPC: #{json_rpc_request}")
 
       result = send_jsonrpc_request(json_rpc_request)
-      return unless result.is_a?(Hash)
+      unless result.is_a?(Hash)
+        raise MCPClient::Errors::ConnectionError,
+              "Server returned invalid initialize result: #{result.inspect}"
+      end
 
+      # Disconnects if the server negotiated a version we cannot speak.
+      @protocol_version = validate_protocol_version!(result)
       @server_info = result['serverInfo']
       @capabilities = result['capabilities']
-      @protocol_version = result['protocolVersion']
+      @instructions = result['instructions']
     end
 
     # Send a JSON-RPC request to the server and wait for result
@@ -148,12 +180,12 @@ module MCPClient
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::ToolCallError] for other errors during request execution
-    def send_jsonrpc_request(request)
+    def send_jsonrpc_request(request, timeout: nil)
       @logger.debug("Sending JSON-RPC request: #{request.to_json}")
 
       begin
-        response = send_http_request(request)
-        parse_response(response)
+        response = send_http_request(request, timeout: timeout)
+        parse_response(response, request)
       rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
         raise
       rescue JSON::ParserError => e
@@ -170,15 +202,42 @@ module MCPClient
     # @param request [Hash] the JSON-RPC request
     # @return [Faraday::Response] the HTTP response
     # @raise [MCPClient::Errors::ConnectionError] if connection fails
-    def send_http_request(request)
+    def send_http_request(request, timeout: nil)
       conn = http_connection
+      # Capture the session id this request goes out with — the value
+      # apply_request_headers attaches — so a later 404 is attributed to the
+      # id that actually accompanied the request, not to whatever @session_id
+      # holds by 404-handling time (another caller may have completed a
+      # restart in between, and its fresh session must not be re-initialized).
+      sent_session_id = @mutex.synchronize { @session_id }
 
       begin
         response = conn.post(@endpoint) do |req|
           apply_request_headers(req, request)
+          # Per-request timeout override (MCP lifecycle: timeouts SHOULD be
+          # configurable on a per-request basis)
+          req.options.timeout = timeout if timeout
+          # The wire header must match the captured id exactly: a restart
+          # completing between capture and header attachment would otherwise
+          # attach a different (or fresh) session than the one attributed to
+          # this request at 404-handling time.
+          if req.headers.key?('Mcp-Session-Id')
+            if sent_session_id
+              req.headers['Mcp-Session-Id'] = sent_session_id
+            else
+              req.headers.delete('Mcp-Session-Id')
+            end
+          end
           req.body = request.to_json
         end
 
+        # MCP 2025-11-25 session management: HTTP 404 for a request carrying
+        # Mcp-Session-Id means the session expired — the client MUST start a
+        # new session with a fresh InitializeRequest (without a session ID).
+        if response.status == 404 && session_restart_applicable?(sent_session_id)
+          return restart_session_and_resend(request, sent_session_id)
+        end
+
         handle_http_error_response(response) unless response.success?
         handle_successful_response(response, request)
 
@@ -186,13 +245,59 @@ module MCPClient
         response
       rescue Faraday::UnauthorizedError, Faraday::ForbiddenError => e
         handle_auth_error(e)
+      rescue Faraday::ResourceNotFound => e
+        # User-configured raise_error middleware surfaces 404 as an exception;
+        # apply the same session-expiry recovery as the response path.
+        return restart_session_and_resend(request, sent_session_id) if session_restart_applicable?(sent_session_id)
+
+        raise MCPClient::Errors::ServerError, "Client error: HTTP 404 #{e.message}"
       rescue Faraday::ConnectionFailed => e
         raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
+      rescue Faraday::TimeoutError => e
+        raise MCPClient::Errors::RequestTimeoutError, "Request timed out: #{e.message}"
       rescue Faraday::Error => e
         raise MCPClient::Errors::TransportError, "HTTP request failed: #{e.message}"
       end
     end
 
+    # Start a new session after the server invalidated the current one, then
+    # resend the original request once. The @restarting_session flag prevents
+    # a second restart if the fresh session also answers 404.
+    # @param request [Hash] the JSON-RPC request that hit the expired session
+    # @param expired_session_id [String] the session id the 404'd request was sent with
+    # @return [Faraday::Response] the response to the resent request
+    def restart_session_and_resend(request, expired_session_id)
+      # Serialized on the transport monitor so concurrent 404s trigger a
+      # single restart; the monitor is reentrant, so the nested
+      # perform_initialize/id generation inside is safe.
+      @mutex.synchronize do
+        # Recheck now that the monitor is held: another caller may already
+        # have restarted the session while this one waited. If so, skip the
+        # extra initialize and just resend against the fresh session.
+        return send_http_request(request) if @session_id != expired_session_id
+
+        @logger.warn("Session #{@session_id} no longer valid (HTTP 404); starting a new session")
+        @restarting_session = true
+        @session_id = nil
+        @last_event_id = nil if instance_variable_defined?(:@last_event_id)
+        perform_initialize
+        send_http_request(request)
+      ensure
+        @restarting_session = false
+      end
+    end
+
+    # Whether a 404 should trigger a session restart: only when the 404'd
+    # request was actually sent with a session id and no restart is already
+    # in flight (a restart's own resend answering 404 must not loop).
+    # @param sent_session_id [String, nil] session id captured when the request was sent
+    # @return [Boolean] true if session restart recovery applies
+    def session_restart_applicable?(sent_session_id)
+      return false if sent_session_id.nil?
+
+      @mutex.synchronize { !@restarting_session }
+    end
+
     # Apply headers to the HTTP request (can be overridden by subclasses)
     # @param req [Faraday::Request] HTTP request
     # @param _request [Hash] JSON-RPC request
@@ -212,22 +317,30 @@ module MCPClient
       # Default: no additional handling
     end
 
-    # Handle authentication errors
+    # Handle authentication errors raised by user-configured raise_error
+    # middleware; routes through the same challenge pipeline as the default
+    # response path.
     # @param error [Faraday::UnauthorizedError, Faraday::ForbiddenError] Auth error
-    # @raise [MCPClient::Errors::ConnectionError] Connection error
+    # @raise [MCPClient::Errors::InsufficientScopeError, MCPClient::Errors::ConnectionError]
     def handle_auth_error(error)
-      # Handle OAuth authorization challenges
-      if error.response && @oauth_provider
-        resource_metadata = @oauth_provider.handle_unauthorized_response(error.response)
-        if resource_metadata
-          @logger.debug('Received OAuth challenge, discovered resource metadata')
-          # Re-raise the error to trigger OAuth flow in calling code
-          raise MCPClient::Errors::ConnectionError, "OAuth authorization required: HTTP #{error.response[:status]}"
-        end
+      response = normalize_error_response(error.response)
+      if response
+        process_authorization_challenge(response)
+        raise_authorization_error(response)
       end
 
-      error_status = error.response ? error.response[:status] : 'unknown'
-      raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{error_status}"
+      raise MCPClient::Errors::ConnectionError, 'Authorization failed: HTTP unknown'
+    end
+
+    # @param raw [Faraday::Response, Hash, nil] an exception's response payload
+    # @return [#status, nil] a response-like object with #status and #headers
+    def normalize_error_response(raw)
+      return nil unless raw
+      return raw if raw.respond_to?(:status) && raw.respond_to?(:headers)
+
+      status = raw[:status] || raw['status']
+      headers = raw[:headers] || raw['headers'] || {}
+      NormalizedResponse.new(status, headers)
     end
 
     # Handle HTTP error responses
@@ -241,7 +354,11 @@ module MCPClient
 
       case response.status
       when 401, 403
-        raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{response.status}"
+        # MCP 2025-11-25: clients MUST parse WWW-Authenticate headers on 401
+        # responses and use the advertised resource metadata; the challenge's
+        # scope parameter is authoritative for the next authorization.
+        process_authorization_challenge(response)
+        raise_authorization_error(response)
       when 400..499
         # Deterministic client errors: the request was processed/rejected and
         # will not succeed on retry, so raise a plain (non-retryable) ServerError.
@@ -255,6 +372,79 @@ module MCPClient
       end
     end
 
+    # Surface a 401/403 WWW-Authenticate challenge to the OAuth provider so
+    # the advertised resource metadata and challenge scope are captured before
+    # the error propagates. Discovery failures must not mask the original
+    # authorization error.
+    # @param response [Faraday::Response] the 401/403 response
+    # @return [void]
+    def process_authorization_challenge(response)
+      return unless @oauth_provider && response.respond_to?(:headers)
+
+      @oauth_provider.handle_unauthorized_response(response)
+    rescue StandardError => e
+      @logger.debug("OAuth challenge processing failed: #{e.message}")
+    end
+
+    # Raise the appropriate error for a 401/403: an insufficient_scope 403
+    # challenge (SEP-835) raises InsufficientScopeError exposing the required
+    # scopes so hosts can run a step-up authorization flow.
+    # @param response [Faraday::Response] the 401/403 response
+    # @raise [MCPClient::Errors::InsufficientScopeError, MCPClient::Errors::ConnectionError]
+    def raise_authorization_error(response)
+      challenge = bearer_challenge_segment(www_authenticate_header(response))
+
+      if response.status == 403 && insufficient_scope_challenge?(challenge)
+        scope = challenge[/(?:^|[\s,])scope\s*=\s*"([^"]*)"/i, 1] ||
+                challenge[/(?:^|[\s,])scope\s*=\s*([^,\s"]+)/i, 1]
+        description = challenge[/(?:^|[\s,])error_description\s*=\s*"([^"]*)"/i, 1]
+        raise MCPClient::Errors::InsufficientScopeError.new(
+          "Authorization failed: HTTP 403 insufficient_scope#{" (required scopes: #{scope})" if scope}",
+          scope: scope, error_description: description
+        )
+      end
+
+      raise MCPClient::Errors::ConnectionError, "Authorization failed: HTTP #{response.status}"
+    end
+
+    # Extract the Bearer challenge's own parameter segment from a (possibly
+    # multi-challenge) WWW-Authenticate header, so params belonging to other
+    # schemes (e.g. `Basic error="insufficient_scope", Bearer realm="x"`) are
+    # never attributed to the Bearer challenge.
+    # @param header [String, nil] the WWW-Authenticate header value
+    # @return [String, nil] the Bearer challenge's parameters (possibly empty),
+    #   or nil when the header has no Bearer challenge
+    def bearer_challenge_segment(header)
+      return nil unless header
+
+      # Locate the Bearer scheme token only OUTSIDE quoted strings: a quoted
+      # value such as realm="prefix Bearer x" must not anchor the segment.
+      masked = header.gsub(/"(?:\\.|[^"\\])*"/) { |q| "\"#{' ' * (q.length - 2)}\"" }
+      match = masked.match(/(?:\A|[\s,])Bearer(?=[\s,]|\z)/i)
+      return nil unless match
+
+      header[match.end(0)..][AUTH_PARAMS_RUN]
+    end
+
+    # The Bearer challenge segment carries an error auth-param that is exactly
+    # insufficient_scope (RFC 6750 / SEP-835); prefixed or extended tokens
+    # (e.g. insufficient_scope.extra) do not match.
+    # @param challenge [String, nil] the Bearer challenge segment
+    # @return [Boolean]
+    def insufficient_scope_challenge?(challenge)
+      return false unless challenge
+
+      challenge.match?(/(?:^|[\s,])error\s*=\s*"?insufficient_scope"?(?![\w.-])/i)
+    end
+
+    # @param response [Faraday::Response] an HTTP response
+    # @return [String, nil] the WWW-Authenticate header value, if any
+    def www_authenticate_header(response)
+      return nil unless response.respond_to?(:headers) && response.headers
+
+      response.headers['WWW-Authenticate'] || response.headers['www-authenticate']
+    end
+
     # Get or create HTTP connection
     # @return [Faraday::Connection] the HTTP connection
     def http_connection
@@ -288,7 +478,7 @@ module MCPClient
     # @param response [Faraday::Response] the HTTP response
     # @return [Hash] the parsed result
     # @raise [NotImplementedError] if not implemented by concrete transport
-    def parse_response(response)
+    def parse_response(response, _request = nil)
       raise NotImplementedError, 'Subclass must implement parse_response'
     end
   end

data/lib/mcp_client/json_rpc_common.rb

@@ -23,6 +23,10 @@ module MCPClient
         yield
       rescue MCPClient::Errors::TransientServerError, MCPClient::Errors::TransportError, IOError,
              Errno::ETIMEDOUT, Errno::ECONNRESET, Errno::EPIPE => e
+        # A timed-out request may still be executing server-side; re-sending
+        # it could run a non-idempotent operation twice. Never retry those.
+        raise if e.is_a?(MCPClient::Errors::RequestTimeoutError)
+
         attempts += 1
         if attempts <= @max_retries
           delay = @retry_backoff * (2**(attempts - 1))
@@ -43,6 +47,46 @@ module MCPClient
       rpc_request('ping')
     end
 
+    # Whether automatic notifications/cancelled on timeout is appropriate
+    # for this request: never for initialize (MUST NOT be cancelled), and
+    # never for task-augmented requests (tasks use tasks/cancel instead).
+    # @param method [String] JSON-RPC method
+    # @param params [Hash] request params
+    # @return [Boolean]
+    def cancellable_request?(method, params)
+      return false if method == 'initialize'
+      return false if params.is_a?(Hash) && (params.key?('task') || params.key?(:task))
+
+      true
+    end
+
+    # Split request-level _meta (RequestParams._meta, e.g. progressToken or
+    # related-task metadata) out of user-supplied tool/prompt arguments.
+    # Accepts both :_meta and '_meta' key spellings; per MCP, _meta belongs at
+    # the request params level, not inside the tool's arguments.
+    # @param arguments [Hash, nil] user-supplied arguments
+    # @return [Array(Hash, Hash|nil)] [arguments without _meta, _meta or nil]
+    def split_request_meta(arguments)
+      return [arguments, nil] unless arguments.is_a?(Hash)
+
+      meta = arguments[:_meta] || arguments['_meta']
+      return [arguments, nil] unless meta
+
+      [arguments.except(:_meta, '_meta'), meta]
+    end
+
+    # Build tools/call- or prompts/get-style params with request-level _meta
+    # hoisted out of the arguments (string keys, matching the JSON wire form).
+    # @param name [String] tool or prompt name
+    # @param arguments [Hash] user-supplied arguments (possibly carrying _meta)
+    # @return [Hash] params hash for the JSON-RPC request
+    def build_named_request_params(name, arguments)
+      args, meta = split_request_meta(arguments)
+      params = { 'name' => name, 'arguments' => args }
+      params['_meta'] = meta if meta
+      params
+    end
+
     # Build a JSON-RPC request object
     # @param method [String] JSON-RPC method name
     # @param params [Hash] parameters for the request
@@ -72,24 +116,93 @@ module MCPClient
     # Generate initialization parameters for MCP protocol
     # @return [Hash] the initialization parameters
     def initialization_params
-      capabilities = {
-        'elicitation' => {}, # MCP 2025-11-25: Support for server-initiated user interactions
-        'roots' => { 'listChanged' => true }, # MCP 2025-11-25: Support for roots
-        'sampling' => {} # MCP 2025-11-25: Support for server-initiated LLM sampling
-        # NOTE: we intentionally do NOT declare a client `tasks` capability. That
-        # capability marks the client as a RECEIVER of task-augmented
-        # sampling/elicitation requests, which is not implemented here — this
-        # client only acts as a task REQUESTOR for tools/call (see
-        # Client#call_tool_as_task), which requires no client-side declaration.
-      }
-
       {
         'protocolVersion' => MCPClient::PROTOCOL_VERSION,
-        'capabilities' => capabilities,
-        'clientInfo' => { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+        'capabilities' => client_capabilities,
+        'clientInfo' => client_info_payload
       }
     end
 
+    # Validate the protocol version the server negotiated in its initialize
+    # result. Per the MCP lifecycle, the server may answer with a different
+    # version than requested; if the client cannot support it, it MUST
+    # disconnect. Disconnects (via the transport's cleanup) and raises when
+    # the version is unsupported or absent.
+    # @param result [Hash] the initialize result
+    # @return [String] the negotiated protocol version
+    # @raise [MCPClient::Errors::ConnectionError] if the version is unsupported
+    def validate_protocol_version!(result)
+      version = result['protocolVersion']
+      return version if MCPClient::SUPPORTED_PROTOCOL_VERSIONS.include?(version)
+
+      begin
+        cleanup if respond_to?(:cleanup)
+      rescue StandardError => e
+        @logger.debug("Cleanup after protocol version mismatch failed: #{e.message}")
+      end
+      raise MCPClient::Errors::ConnectionError,
+            "Server negotiated unsupported protocol version #{version.inspect} " \
+            "(supported: #{MCPClient::SUPPORTED_PROTOCOL_VERSIONS.join(', ')}); disconnecting"
+    end
+
+    # The Implementation object sent as clientInfo: the host-provided info
+    # when configured (client_info=), otherwise the gem's identity.
+    # @return [Hash]
+    def client_info_payload
+      return @client_info if defined?(@client_info) && @client_info
+
+      { 'name' => 'ruby-mcp-client', 'version' => MCPClient::VERSION }
+    end
+
+    # Declared client capabilities, derived from the server-request callbacks
+    # the host actually registered before connecting. Per MCP 2025-11-25,
+    # clients that support a feature MUST declare it during initialization,
+    # and only negotiated capabilities may be used afterwards — so declaring
+    # a hardcoded set independent of host support violates the lifecycle in
+    # both directions.
+    # @return [Hash] the capabilities object for the initialize request
+    def client_capabilities
+      capabilities = {}
+      if registered_callback?(:@elicitation_request_callback)
+        # Both defined elicitation modes are implemented (an empty object
+        # would mean form-only per the spec's backwards-compatibility rule).
+        capabilities['elicitation'] = { 'form' => {}, 'url' => {} }
+      end
+      capabilities['roots'] = { 'listChanged' => true } if registered_callback?(:@roots_list_request_callback)
+      if registered_callback?(:@sampling_request_callback)
+        # SEP-1577: servers may only send tool-enabled sampling requests when
+        # the client declares the sampling.tools sub-capability.
+        capabilities['sampling'] = sampling_tools_supported? ? { 'tools' => {} } : {}
+      end
+      # NOTE: we intentionally do NOT declare a client `tasks` capability. That
+      # capability marks the client as a RECEIVER of task-augmented
+      # sampling/elicitation requests, which is not implemented here — this
+      # client only acts as a task REQUESTOR for tools/call (see
+      # Client#call_tool_as_task), which requires no client-side declaration.
+      capabilities
+    end
+
+    # Opt this transport into declaring tool-use support for sampling
+    # (ClientCapabilities.sampling.tools, MCP 2025-11-25 / SEP-1577). Call
+    # before connect so the initialize request advertises it; it only takes
+    # effect when a sampling request callback is also registered, since
+    # sampling.tools is a sub-capability of sampling.
+    # @return [void]
+    def declare_sampling_tools
+      @sampling_tools_supported = true
+    end
+
+    # @param ivar [Symbol] callback instance variable name
+    # @return [Boolean] whether the callback is registered on this transport
+    def registered_callback?(ivar)
+      instance_variable_defined?(ivar) && !instance_variable_get(ivar).nil?
+    end
+
+    # @return [Boolean] whether the host opted into sampling tool use
+    def sampling_tools_supported?
+      instance_variable_defined?(:@sampling_tools_supported) && @sampling_tools_supported
+    end
+
     # Process JSON-RPC response
     # @param response [Hash] the parsed JSON-RPC response
     # @return [Object] the result field from the response