ruby-mcp-client 1.1.0 → 2.0.0

data/lib/mcp_client/server_base.rb

@@ -9,6 +9,22 @@ module MCPClient
 
     # Initialize the server with a name
     # @param name [String, nil] server name
+    # Server-declared instructions from the initialize result, if any
+    # @return [String, nil]
+    attr_reader :instructions
+
+    # Host-supplied Implementation info sent as clientInfo during initialize
+    # (MCP 2025-11-25 Implementation: name, version, plus optional title,
+    # description, websiteUrl, icons). Defaults to the gem's identity.
+    # @param info [Hash] implementation info; must include name and version
+    # @raise [ArgumentError] when name or version is missing
+    def client_info=(info)
+      raise ArgumentError, 'client_info must include name' unless info['name'] || info[:name]
+      raise ArgumentError, 'client_info must include version' unless info['version'] || info[:version]
+
+      @client_info = info.transform_keys(&:to_s)
+    end
+
     def initialize(name: nil)
       @name = name
     end
@@ -83,11 +99,61 @@ module MCPClient
     end
 
     # Get server capabilities
+    # MCP 2025-11-25 tasks: all messages related to a task MUST carry the
+    # io.modelcontextprotocol/related-task key in _meta. Reserved key name:
+    RELATED_TASK_META_KEY = 'io.modelcontextprotocol/related-task'
+
+    # Echo the related-task _meta of an incoming server request onto the
+    # outgoing result, so responses to task-related requests (elicitation or
+    # sampling during input_required) stay associated with their task.
+    # @param result [Hash] the outgoing JSON-RPC result payload
+    # @param params [Hash, nil] the incoming request params
+    # @return [Hash] result with related-task _meta merged when applicable
+    def merge_related_task_meta(result, params)
+      related = params.is_a?(Hash) ? params.dig('_meta', RELATED_TASK_META_KEY) : nil
+      return result unless related && result.is_a?(Hash) && !result.key?('error')
+
+      meta = (result['_meta'] || {}).merge(RELATED_TASK_META_KEY => related)
+      result.merge('_meta' => meta)
+    end
+
     # @return [Hash, nil] server capabilities
     def capabilities
       raise NotImplementedError, 'Subclasses must implement capabilities'
     end
 
+    # Whether the server declared the given (possibly nested) capability
+    # during initialization.
+    # @param path [Array<String, Symbol>] capability key path, e.g. 'logging'
+    #   or 'resources', 'subscribe'
+    # @return [Boolean]
+    def capability?(*path)
+      node = begin
+        capabilities
+      rescue NotImplementedError
+        nil
+      end
+      path.each do |key|
+        return false unless node.is_a?(Hash)
+
+        node = node[key.to_s]
+      end
+      !node.nil? && node != false
+    end
+
+    # Raise unless the server negotiated the given capability (MCP lifecycle:
+    # "Only use capabilities that were successfully negotiated").
+    # @param path [Array<String, Symbol>] capability key path
+    # @param method [String] the JSON-RPC method the caller wants to send
+    # @raise [MCPClient::Errors::CapabilityError]
+    def require_capability!(*path, method:)
+      return if capability?(*path)
+
+      raise MCPClient::Errors::CapabilityError,
+            "Server #{name || self.class.name} did not declare the #{path.join('.')} capability " \
+            "required for #{method}"
+    end
+
     # Clean up the server connection
     def cleanup
       raise NotImplementedError, 'Subclasses must implement cleanup'

data/lib/mcp_client/server_http/json_rpc_transport.rb

@@ -12,10 +12,11 @@ module MCPClient
 
       # Parse an HTTP JSON-RPC response
       # @param response [Faraday::Response] the HTTP response
+      # @param _request [Hash, nil] the originating JSON-RPC request (unused)
       # @return [Hash] the parsed result
       # @raise [MCPClient::Errors::TransportError] if parsing fails
       # @raise [MCPClient::Errors::ServerError] if the response contains an error
-      def parse_response(response)
+      def parse_response(response, _request = nil)
         body = response.body.strip
         data = JSON.parse(body)
         process_jsonrpc_response(data)

data/lib/mcp_client/server_http.rb

@@ -183,10 +183,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
-      rpc_request('tools/call', {
-                    name: tool_name,
-                    arguments: parameters
-                  })
+      rpc_request('tools/call', build_named_request_params(tool_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -271,10 +268,7 @@ module MCPClient
     # @raise [MCPClient::Errors::TransportError] if response isn't valid JSON
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
     def get_prompt(prompt_name, parameters)
-      rpc_request('prompts/get', {
-                    name: prompt_name,
-                    arguments: parameters
-                  })
+      rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       raise
     rescue StandardError => e
@@ -336,11 +330,14 @@ module MCPClient
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def complete(ref:, argument:, context: nil)
+      ensure_connected
+      require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
       result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
@@ -352,8 +349,11 @@ module MCPClient
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
+      ensure_connected
+      require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
@@ -384,9 +384,12 @@ module MCPClient
     # @return [Boolean] true if subscription successful
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
     def subscribe_resource(uri)
+      ensure_connected
+      require_capability!('resources', 'subscribe', method: 'resources/subscribe')
       rpc_request('resources/subscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
@@ -397,9 +400,12 @@ module MCPClient
     # @return [Boolean] true if unsubscription successful
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
     def unsubscribe_resource(uri)
+      ensure_connected
+      require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
       rpc_request('resources/unsubscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"

data/lib/mcp_client/server_sse/json_rpc_transport.rb

@@ -16,16 +16,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_initialized
 
         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' })
+        post_json_rpc_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
@@ -62,15 +81,28 @@ module MCPClient
 
       # Perform JSON-RPC initialize handshake with the MCP server
       # @return [void]
+      # @raise [MCPClient::Errors::ConnectionError] if the initialize result is malformed
       def perform_initialize
         request_id = @mutex.synchronize { @request_id += 1 }
         json_rpc_request = build_jsonrpc_request('initialize', initialization_params, request_id)
         @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)
+          # A non-object initialize result means the handshake did not succeed.
+          # Continuing would enter the Operation phase without ever sending the
+          # mandatory notifications/initialized (MCP lifecycle "Initialization":
+          # "After successful initialization, the client MUST send an
+          # `initialized` notification"), so fail the connection instead.
+          cleanup
+          raise MCPClient::Errors::ConnectionError,
+                "Invalid initialize response from server: expected an object, got #{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']
+        @instructions = result['instructions']
 
         # Send initialized notification to acknowledge completion of initialization
         initialized_notification = build_jsonrpc_notification('notifications/initialized', {})
@@ -86,7 +118,7 @@ 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}")
         record_activity
 
@@ -94,7 +126,7 @@ module MCPClient
           response = post_json_rpc_request(request)
 
           if @use_sse
-            wait_for_sse_result(request)
+            wait_for_sse_result(request, timeout: timeout)
           else
             parse_direct_response(response)
           end
@@ -133,6 +165,8 @@ module MCPClient
           end
 
           response
+        rescue Faraday::TimeoutError => e
+          raise MCPClient::Errors::RequestTimeoutError, "Request timed out: #{e.message}"
         rescue Faraday::ConnectionFailed => e
           raise MCPClient::Errors::ConnectionError, "Server connection lost: #{e.message}"
         end
@@ -160,6 +194,11 @@ module MCPClient
         response = conn.post(endpoint) do |req|
           req.headers['Content-Type'] = 'application/json'
           req.headers['Accept'] = 'application/json'
+          # MCP lifecycle "Version Negotiation": the client MUST include the
+          # MCP-Protocol-Version header on all requests after the initialize
+          # handshake. The guard naturally skips the initialize POST itself,
+          # since the negotiated version is only known from its result.
+          req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
           (@headers.dup.tap do |h|
             h.delete('Accept')
             h.delete('Cache-Control')
@@ -177,10 +216,10 @@ module MCPClient
       # @param request [Hash] the original JSON-RPC request
       # @return [Hash] the result data
       # @raise [MCPClient::Errors::ConnectionError, MCPClient::Errors::ToolCallError] on errors
-      def wait_for_sse_result(request)
+      def wait_for_sse_result(request, timeout: nil)
         request_id = request['id']
         start_time = Time.now
-        timeout = @read_timeout || 10
+        timeout ||= @read_timeout || 10
 
         ensure_sse_connection_active
 
@@ -222,12 +261,13 @@ module MCPClient
           sleep 0.1
         end
 
-        raise MCPClient::Errors::ToolCallError, "Timeout waiting for SSE result for request #{request_id}"
+        raise MCPClient::Errors::RequestTimeoutError, "Timeout waiting for SSE result for request #{request_id}"
       end
 
       # Check if a result is available for the given request ID
       # @param request_id [Integer] the request ID to check
       # @return [Hash, nil] the result if available, nil otherwise
+      # @raise [MCPClient::Errors::ServerError] if the stored result is a JSON-RPC error response
       def check_for_result(request_id)
         result = nil
         @mutex.synchronize do
@@ -236,12 +276,27 @@ module MCPClient
 
         if result
           record_activity
+          # SseParser#process_response? stores JSON-RPC error responses under
+          # the Symbol :error key; deliver them to the caller as ServerError
+          # (MCP lifecycle "Error Handling") instead of timing out.
+          raise_sse_error_response(result[:error]) if result.is_a?(Hash) && result.key?(:error)
           return result
         end
 
         nil
       end
 
+      # Raise a ServerError for a JSON-RPC error response received over SSE,
+      # mirroring JsonRpcCommon#process_jsonrpc_response for the other transports.
+      # @param error [Hash, nil] the JSON-RPC error object ('code', 'message', 'data')
+      # @raise [MCPClient::Errors::ServerError] always
+      def raise_sse_error_response(error)
+        error ||= {}
+        message = error['message'] || 'Unknown server error'
+        message = "#{message} (code #{error['code']})" if error['code']
+        raise MCPClient::Errors::ServerError, message
+      end
+
       # Parse a direct (non-SSE) JSON-RPC response
       # @param response [Faraday::Response] the HTTP response
       # @return [Hash] the parsed result

data/lib/mcp_client/server_sse/reconnect_monitor.rb

@@ -88,9 +88,13 @@ module MCPClient
 
             cleanup
 
-            # Clear any stale auth error from the previous connection so it does
-            # not spuriously abort this reconnect via wait_for_connection.
-            @mutex.synchronize { @auth_error = nil }
+            # Clear any stale auth/connection error from the previous connection
+            # so it does not spuriously abort this reconnect via
+            # wait_for_connection.
+            @mutex.synchronize do
+              @auth_error = nil
+              @connection_error = nil
+            end
 
             connect
             @logger.info('Successfully reconnected after ping failures')
@@ -169,11 +173,14 @@ module MCPClient
           deadline = Time.now + timeout
 
           until @connection_established
+            break if @connection_error
+
             remaining = [1, deadline - Time.now].min
             break if remaining <= 0 || @connection_cv.wait(remaining) { @connection_established }
           end
 
           raise MCPClient::Errors::ConnectionError, @auth_error if @auth_error
+          raise MCPClient::Errors::ConnectionError, @connection_error if @connection_error
 
           unless @connection_established
             cleanup

data/lib/mcp_client/server_sse/sse_parser.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module MCPClient
   class ServerSSE
@@ -30,7 +31,7 @@ module MCPClient
         begin
           data = JSON.parse(event[:data])
 
-          return if process_error_in_message(data)
+          return if process_error_in_message?(data)
           return if process_server_request?(data)
           return if process_notification?(data)
 
@@ -44,11 +45,17 @@ module MCPClient
         end
       end
 
-      # Process a JSON-RPC error() in the SSE stream.
+      # Process a connection-level JSON-RPC error payload in the SSE stream.
+      # Error RESPONSES (id-bearing) belong to a pending request and are
+      # delivered to the waiting caller via process_response? instead, per the
+      # MCP lifecycle "Error Handling" section (implementations SHOULD handle
+      # error cases such as protocol version mismatch), so they must not be
+      # swallowed here.
       # @param data [Hash] the parsed JSON payload
-      # @return [Boolean] true if we saw & handled an error
-      def process_error_in_message(data)
-        return unless data['error']
+      # @return [Boolean] true if we saw & handled an id-less error
+      def process_error_in_message?(data)
+        return false unless data['error']
+        return false if data['id']
 
         error_message = data['error']['message'] || 'Unknown server error'
         error_code    = data['error']['code']
@@ -93,8 +100,10 @@ module MCPClient
         @mutex.synchronize do
           @sse_results[data['id']] =
             if data['error']
-              { 'isError' => true,
-                'content' => [{ 'type' => 'text', 'text' => data['error'].to_json }] }
+              # JSON-RPC error response: store the error under a Symbol key
+              # (JSON.parse only produces String keys, so this cannot collide
+              # with a success result) for the waiter to raise ServerError.
+              { error: data['error'] }
             else
               data['result']
             end
@@ -130,16 +139,44 @@ module MCPClient
         has_content ? event : nil
       end
 
-      # Handle the special "endpoint" control frame (for SSE handshake)
+      # Handle the special "endpoint" control frame (for SSE handshake).
+      # The event data is a URI reference (MCP 2024-11-05 HTTP with SSE: the
+      # server sends "an `endpoint` event containing a URI for the client to
+      # use for sending messages") which must be resolved against the SSE
+      # connection URL per RFC 3986 section 5.1.3, so relative endpoint URIs
+      # POST to the URL the server actually designated.
       # @param data [String] the raw endpoint payload
       def handle_endpoint_event(data)
+        endpoint = resolve_endpoint_uri(data)
         @mutex.synchronize do
-          @rpc_endpoint = data
+          @rpc_endpoint = endpoint
           @sse_connected = true
           @connection_established = true
           @connection_cv.broadcast
         end
       end
+
+      # Resolve an endpoint URI reference against the SSE connection URL
+      # @param data [String] the endpoint event payload (absolute or relative URI)
+      # @return [String] the absolute endpoint URL
+      def resolve_endpoint_uri(data)
+        URI.join(@base_url, data).to_s
+      rescue URI::Error => e
+        # The endpoint event is the handshake's core payload; an unresolvable
+        # URI must fail the handshake rather than deferring a broken POST
+        # target to the first request.
+        @logger.error("Failed to resolve endpoint URI #{data.inspect} against #{@base_url}: #{e.message}")
+        message = "Invalid endpoint URI in SSE endpoint event: #{data.inspect} (#{e.message})"
+        # The SSE worker thread swallows this exception with a generic rescue,
+        # so also record the failure cause (mirroring @auth_error) for the
+        # connect caller blocked in wait_for_connection to surface promptly.
+        @mutex.synchronize do
+          @connection_error = message
+          @connection_established = false
+          @connection_cv.broadcast
+        end
+        raise MCPClient::Errors::TransportError, message
+      end
     end
   end
 end

data/lib/mcp_client/server_sse.rb

@@ -97,7 +97,13 @@ module MCPClient
       @connection_established = false
       @connection_cv = @mutex.new_cond
       @initialized = false
+      # Negotiated protocol version captured from the initialize result
+      # (sent as the MCP-Protocol-Version header on post-initialize requests)
+      @protocol_version = nil
       @auth_error = nil
+      # Non-auth connection failure cause (e.g. invalid endpoint event URI)
+      # recorded by the SSE worker for wait_for_connection to surface
+      @connection_error = nil
       # Whether to use SSE transport; may disable if handshake fails
       @use_sse = true
 
@@ -157,10 +163,7 @@ module MCPClient
     # @raise [MCPClient::Errors::PromptGetError] for other errors during prompt interpolation
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def get_prompt(prompt_name, parameters)
-      rpc_request('prompts/get', {
-                    name: prompt_name,
-                    arguments: parameters
-                  })
+      rpc_request('prompts/get', build_named_request_params(prompt_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -254,9 +257,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during subscription
     def subscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/subscribe')
       rpc_request('resources/subscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error subscribing to resource '#{uri}': #{e.message}"
@@ -269,9 +274,11 @@ module MCPClient
     # @raise [MCPClient::Errors::ResourceReadError] for other errors during unsubscription
     def unsubscribe_resource(uri)
       ensure_initialized
+      require_capability!('resources', 'subscribe', method: 'resources/unsubscribe')
       rpc_request('resources/unsubscribe', { uri: uri })
       true
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError, MCPClient::Errors::ServerError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ResourceReadError, "Error unsubscribing from resource '#{uri}': #{e.message}"
@@ -315,10 +322,7 @@ module MCPClient
     # @raise [MCPClient::Errors::ToolCallError] for other errors during tool execution
     # @raise [MCPClient::Errors::ConnectionError] if server is disconnected
     def call_tool(tool_name, parameters)
-      rpc_request('tools/call', {
-                    name: tool_name,
-                    arguments: parameters
-                  })
+      rpc_request('tools/call', build_named_request_params(tool_name, parameters))
     rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
       # Re-raise connection/transport errors directly to match test expectations
       raise
@@ -334,11 +338,14 @@ module MCPClient
     # @return [Hash] completion result with 'values', optional 'total', and 'hasMore' fields
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def complete(ref:, argument:, context: nil)
+      ensure_initialized
+      require_capability!('completions', method: 'completion/complete')
       params = { ref: ref, argument: argument }
       params[:context] = context if context
       result = rpc_request('completion/complete', params)
       result['completion'] || { 'values' => [] }
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error requesting completion: #{e.message}"
@@ -350,8 +357,11 @@ module MCPClient
     # @return [Hash] empty result on success
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
+      ensure_initialized
+      require_capability!('logging', method: 'logging/setLevel')
       rpc_request('logging/setLevel', { level: level })
-    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError
+    rescue MCPClient::Errors::ConnectionError, MCPClient::Errors::TransportError,
+           MCPClient::Errors::CapabilityError
       raise
     rescue StandardError => e
       raise MCPClient::Errors::ServerError, "Error setting log level: #{e.message}"
@@ -369,6 +379,8 @@ module MCPClient
       begin
         # Don't reset auth error if it's pre-existing
         @mutex.synchronize { @auth_error = nil } unless pre_existing_auth_error
+        # Clear any stale connection failure cause from a previous attempt
+        @mutex.synchronize { @connection_error = nil }
 
         start_sse_thread
         effective_timeout = [@read_timeout || 30, 30].min
@@ -404,6 +416,10 @@ module MCPClient
         @connection_established = false
         @sse_connected = false
         @initialized = false # Reset initialization state for reconnection
+        # A fresh session negotiates its own protocol version; keeping the old
+        # one would leak the previous session's version into the next
+        # initialize POST's MCP-Protocol-Version header.
+        @protocol_version = nil
 
         # Reset the SSE parse buffer so a reconnect never inherits a leftover
         # partial event from the previous connection.
@@ -527,18 +543,19 @@ module MCPClient
     # @param params [Hash] the elicitation parameters
     # @return [void]
     def handle_elicitation_create(request_id, params)
-      # If no callback is registered, decline the request
+      # Without a callback there is no user to interact with: answer with a
+      # JSON-RPC error rather than fabricating a user "decline".
       unless @elicitation_request_callback
-        @logger.warn('Received elicitation request but no callback registered, declining')
-        send_elicitation_response(request_id, { 'action' => 'decline' })
+        @logger.warn('Received elicitation request but no callback registered')
+        send_error_response(request_id, -32_601, 'Elicitation not supported: no handler configured')
         return
       end
 
       # Call the registered callback
       result = @elicitation_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_elicitation_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_elicitation_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Handle roots/list request from server (MCP 2025-06-18)
@@ -556,8 +573,8 @@ module MCPClient
       # Call the registered callback
       result = @roots_list_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_roots_list_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_roots_list_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Send roots/list response back to server via HTTP POST (MCP 2025-06-18)
@@ -594,8 +611,8 @@ module MCPClient
       # Call the registered callback
       result = @sampling_request_callback.call(request_id, params)
 
-      # Send the response back to the server
-      send_sampling_response(request_id, result)
+      # Send the response back to the server (echoing related-task _meta)
+      send_sampling_response(request_id, merge_related_task_meta(result, params))
     end
 
     # Send sampling response back to server via HTTP POST (MCP 2025-11-25)
@@ -628,6 +645,14 @@ module MCPClient
     # @param result [Hash] the elicitation result (action and optional content)
     # @return [void]
     def send_elicitation_response(request_id, result)
+      # Error-shaped results become JSON-RPC error responses (e.g. -32602 for
+      # an undeclared elicitation mode), mirroring the sampling error path.
+      if result.is_a?(Hash) && result['error']
+        send_error_response(request_id, result['error']['code'] || -32_603,
+                            result['error']['message'] || 'Elicitation error')
+        return
+      end
+
       ensure_initialized
 
       response = {
@@ -685,6 +710,9 @@ module MCPClient
       @rpc_conn.post do |req|
         req.url @rpc_endpoint
         req.headers['Content-Type'] = 'application/json'
+        # MCP lifecycle "Version Negotiation": include the MCP-Protocol-Version
+        # header on all HTTP requests after the initialize handshake.
+        req.headers['Mcp-Protocol-Version'] = @protocol_version if @protocol_version
         @headers.each { |k, v| req.headers[k] = v }
         req.body = json_body
       end