ruby-mcp-client 1.1.0 → 2.1.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:
@@ -14,6 +18,18 @@ module MCPClient
     # Allowed string formats per MCP spec
     STRING_FORMATS = %w[email uri date date-time].freeze
 
+    # Wall-clock budget for ALL pattern matching in a single validate_content
+    # call. The requestedSchema comes from the remote server, so an expensive
+    # expression must not be able to monopolize the calling thread.
+    #
+    # The budget covers the whole operation, not each match: a per-match limit
+    # multiplies, since the server also controls how many fields it declares.
+    PATTERN_MATCH_TIMEOUT = 1.0
+
+    # Floor for an individual match, so a nearly-exhausted budget still makes
+    # progress rather than failing every remaining field.
+    MIN_PATTERN_MATCH_TIMEOUT = 0.01
+
     # Validate that a requestedSchema conforms to MCP elicitation constraints.
     # Returns an array of error messages (empty if valid).
     # @param schema [Hash] the requestedSchema
@@ -114,6 +130,9 @@ module MCPClient
       errors = []
       return errors unless content.is_a?(Hash) && schema.is_a?(Hash)
 
+      # One deadline covers every field's pattern in this call.
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + PATTERN_MATCH_TIMEOUT
+
       properties = schema['properties'] || {}
       required = Array(schema['required'])
 
@@ -128,7 +147,7 @@ module MCPClient
         prop = properties[field.to_s]
         next unless prop.is_a?(Hash)
 
-        errors.concat(validate_value(field.to_s, value, prop))
+        errors.concat(validate_value(field.to_s, value, prop, deadline))
       end
 
       errors
@@ -139,13 +158,13 @@ module MCPClient
     # @param value [Object] the value to validate
     # @param prop [Hash] property schema
     # @return [Array<String>] validation errors
-    def self.validate_value(field, value, prop)
+    def self.validate_value(field, value, prop, deadline = nil)
       errors = []
       type = prop['type']
 
       case type
       when 'string'
-        errors.concat(validate_string_value(field, value, prop))
+        errors.concat(validate_string_value(field, value, prop, deadline))
       when 'number', 'integer'
         errors.concat(validate_number_value(field, value, prop))
       when 'boolean'
@@ -162,7 +181,7 @@ module MCPClient
     # @param value [Object] the value
     # @param prop [Hash] property schema
     # @return [Array<String>] validation errors
-    def self.validate_string_value(field, value, prop)
+    def self.validate_string_value(field, value, prop, deadline = nil)
       errors = []
 
       unless value.is_a?(String)
@@ -179,15 +198,7 @@ module MCPClient
         errors << "Field '#{field}' must be one of: #{allowed.join(', ')}" unless allowed.include?(value)
       end
 
-      if prop['pattern']
-        begin
-          unless value.match?(Regexp.new(prop['pattern']))
-            errors << "Field '#{field}' must match pattern '#{prop['pattern']}'"
-          end
-        rescue RegexpError
-          # Skip pattern validation if the pattern is invalid
-        end
-      end
+      errors.concat(validate_string_pattern(field, value, prop['pattern'], deadline)) if prop['pattern']
 
       if prop['minLength'] && value.length < prop['minLength']
         errors << "Field '#{field}' must be at least #{prop['minLength']} characters"
@@ -197,9 +208,84 @@ 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 regular-expression pattern.
+    # An invalid pattern is not enforced (unchanged behavior), but matching
+    # runs under PATTERN_MATCH_TIMEOUT because the pattern comes from the
+    # remote server. A match that exceeds the budget is reported as a
+    # validation error rather than silently accepted — the value was never
+    # shown to satisfy the constraint.
+    # @param field [String] field name
+    # @param value [String] the value
+    # @param pattern [String] the declared pattern
+    # @return [Array<String>] validation errors
+    def self.validate_string_pattern(field, value, pattern, deadline = nil)
+      remaining = pattern_budget_remaining(deadline)
+      return ["Field '#{field}' pattern matching budget exhausted"] if remaining.zero?
+
+      return [] if value.match?(Regexp.new(pattern, timeout: remaining))
+
+      ["Field '#{field}' must match pattern '#{pattern}'"]
+    rescue Regexp::TimeoutError
+      ["Field '#{field}' pattern '#{pattern}' exceeded the #{PATTERN_MATCH_TIMEOUT}s matching budget"]
+    rescue RegexpError
+      # Skip pattern validation if the pattern is invalid
+      []
+    end
+
+    # Time left in the validation-wide pattern budget.
+    # @param deadline [Float, nil] monotonic deadline, or nil for a lone match
+    # @return [Float] seconds available for the next match; 0.0 when exhausted
+    def self.pattern_budget_remaining(deadline)
+      return PATTERN_MATCH_TIMEOUT unless deadline
+
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return 0.0 if remaining <= 0
+
+      [remaining, MIN_PATTERN_MATCH_TIMEOUT].max
+    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,25 @@ 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 a response body exceeded the configured size limit (e.g. a
+    # gzip payload that expands past the decompression ceiling). A subclass of
+    # TransportError so existing rescues keep working, but deliberately
+    # excluded from automatic retries: the server already received and
+    # processed the request, so re-sending it could run a non-idempotent
+    # operation again — and would decompress the oversized body each time.
+    class ResponseTooLargeError < 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
+      with_retry(method) 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,42 @@ module MCPClient
       end
     end
 
-    # Validate session ID format for security
+    # Resend a request against the freshly restarted session — unless doing so
+    # could execute a side effect twice.
+    #
+    # A 404 usually means the server rejected the request outright, but it does
+    # not prove that: a session can expire after the tool ran. Automatic
+    # session recovery is worth having for idempotent methods, and would
+    # otherwise be a hole straight through the no-replay guarantee that
+    # with_retry enforces for NON_IDEMPOTENT_METHODS.
+    #
+    # Raises ConnectionError (which with_retry never retries) so no other path
+    # can turn this into a second attempt.
+    # @param request [Hash] the JSON-RPC request that hit the expired session
+    # @return [Faraday::Response] the response to the resent request
+    # @raise [MCPClient::Errors::ConnectionError] for a non-idempotent method
+    def resend_after_session_restart(request)
+      method = request['method']
+      return send_http_request(request) unless NON_IDEMPOTENT_METHODS.include?(method)
+
+      raise MCPClient::Errors::ConnectionError,
+            "Session expired during #{method}; a new session was started but the request was NOT resent " \
+            'because it may already have executed. Retry it explicitly if that is safe.'
+    end
+
+    # 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 +176,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 +185,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,16 +203,16 @@ 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)
-      @logger.debug("Sending JSON-RPC request: #{request.to_json}")
+    def send_jsonrpc_request(request, timeout: nil)
+      @logger.debug("Sending JSON-RPC request: #{describe_jsonrpc_message(request)}")
 
       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
-        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{e.message}"
+        raise MCPClient::Errors::TransportError, "Invalid JSON response from server: #{describe_parse_error(e)}"
       rescue Errno::ECONNREFUSED => e
         raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
       rescue StandardError => e
@@ -170,15 +225,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 +268,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 resend_after_session_restart(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
+        resend_after_session_restart(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 +340,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 +377,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 +395,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
@@ -281,14 +494,14 @@ module MCPClient
     # Log HTTP response (to be overridden by specific transports)
     # @param response [Faraday::Response] the HTTP response
     def log_response(response)
-      @logger.debug("Received HTTP response: #{response.status} #{response.body}")
+      @logger.debug("Received HTTP response: #{response.status} (#{describe_body_size(response.body)})")
     end
 
     # Parse HTTP response (to be implemented by specific transports)
     # @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