Track Mcp-Session-Id and protocol version in HTTP client

Per the Streamable HTTP spec, if the server returns an Mcp-Session-Id
header during `initialize`, the client MUST include it on subsequent
requests. Capture the session ID and protocol version from the
`initialize` response and attach them automatically. Expose both via
`session_id` and `protocol_version` readers on the transport.

Map 404 responses to a new `SessionExpiredError` (a subclass of
`RequestHandlerError` for backward compatibility) and clear local
session state so callers can start a fresh session with a new
`initialize` request.

https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: atesgoral

docs/building-clients.md

@@ -74,6 +74,17 @@ response = client.call_tool(
 )
 ```
 
+### Sessions
+
+After a successful `initialize` request, the transport captures the `Mcp-Session-Id` header and `protocolVersion` from the response and includes the session ID on subsequent requests. Both are exposed on the transport:
+
+```ruby
+http_transport.session_id       # => "abc123..."
+http_transport.protocol_version # => "2025-11-25"
+```
+
+If the server terminates the session, subsequent requests return HTTP 404 and the transport raises `MCP::Client::SessionExpiredError` (a subclass of `RequestHandlerError`). Session state is cleared automatically; callers should start a new session by sending a fresh `initialize` request.
+
 ### Authorization
 
 Provide custom headers for authentication:

lib/mcp/client.rb

@@ -33,6 +33,16 @@ def initialize(message, request, error_type: :internal_error, original_error: ni
     # server-returned JSON-RPC error, which is raised as `ServerError`.
     class ValidationError < StandardError; end
 
+    # Raised when the server responds 404 to a request containing a session ID,
+    # indicating the session has expired. Inherits from `RequestHandlerError` for
+    # backward compatibility with callers that rescue the generic error. Per spec,
+    # clients MUST start a new session with a fresh `initialize` request in response.
+    class SessionExpiredError < RequestHandlerError
+      def initialize(message, request, original_error: nil)
+        super(message, request, error_type: :not_found, original_error: original_error)
+      end
+    end
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.

lib/mcp/client/http.rb

@@ -2,23 +2,38 @@
 
 module MCP
   class Client
+    # TODO: HTTP GET for SSE streaming is not yet implemented.
+    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server
+    # TODO: Resumability and redelivery with Last-Event-ID is not yet implemented.
+    #   https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#resumability-and-redelivery
     class HTTP
       ACCEPT_HEADER = "application/json, text/event-stream"
+      SESSION_ID_HEADER = "Mcp-Session-Id"
 
-      attr_reader :url
+      attr_reader :url, :session_id, :protocol_version
 
       def initialize(url:, headers: {}, &block)
         @url = url
         @headers = headers
         @faraday_customizer = block
+        @session_id = nil
+        @protocol_version = nil
       end
 
+      # Sends a JSON-RPC request and returns the parsed response body.
+      # After a successful `initialize` handshake, the session ID and protocol
+      # version returned by the server are captured and automatically included
+      # on subsequent requests.
       def send_request(request:)
         method = request[:method] || request["method"]
         params = request[:params] || request["params"]
 
-        response = client.post("", request)
-        parse_response_body(response, method, params)
+        response = client.post("", request, session_headers)
+        body = parse_response_body(response, method, params)
+
+        capture_session_info(method, response, body)
+
+        body
       rescue Faraday::BadRequestError => e
         raise RequestHandlerError.new(
           "The #{method} request is invalid",
@@ -41,10 +56,13 @@ def send_request(request:)
           original_error: e,
         )
       rescue Faraday::ResourceNotFound => e
-        raise RequestHandlerError.new(
+        # Per spec, the server MAY terminate the session at any time and MUST
+        # respond with 404 to requests containing an expired session ID.
+        # https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+        clear_session
+        raise SessionExpiredError.new(
           "The #{method} request is not found",
           { method: method, params: params },
-          error_type: :not_found,
           original_error: e,
         )
       rescue Faraday::UnprocessableEntityError => e
@@ -83,6 +101,25 @@ def client
         end
       end
 
+      def session_headers
+        headers = {}
+        headers[SESSION_ID_HEADER] = @session_id if @session_id
+        headers
+      end
+
+      def capture_session_info(method, response, body)
+        return unless method.to_s == "initialize"
+
+        # Faraday normalizes header names to lowercase.
+        @session_id ||= response.headers[SESSION_ID_HEADER.downcase]
+        @protocol_version ||= body.is_a?(Hash) ? body.dig("result", "protocolVersion") : nil
+      end
+
+      def clear_session
+        @session_id = nil
+        @protocol_version = nil
+      end
+
       def require_faraday!
         require "faraday"
       rescue LoadError

test/mcp/client/http_test.rb

@@ -203,7 +203,7 @@ def test_send_request_raises_forbidden_error
         assert_equal({ method: "tools/list", params: nil }, error.request)
       end
 
-      def test_send_request_raises_not_found_error
+      def test_send_request_raises_session_expired_error_on_404
         request = {
           jsonrpc: "2.0",
           id: "test_id",
@@ -214,7 +214,7 @@ def test_send_request_raises_not_found_error
           .with(body: request.to_json)
           .to_return(status: 404)
 
-        error = assert_raises(RequestHandlerError) do
+        error = assert_raises(SessionExpiredError) do
           client.send_request(request: request)
         end
 
@@ -223,6 +223,17 @@ def test_send_request_raises_not_found_error
         assert_equal({ method: "tools/list", params: nil }, error.request)
       end
 
+      def test_session_expired_error_is_a_request_handler_error
+        stub_request(:post, url).to_return(status: 404)
+
+        error = assert_raises(RequestHandlerError) do
+          client.send_request(request: { method: "tools/list" })
+        end
+
+        assert_kind_of(SessionExpiredError, error)
+        assert_equal(:not_found, error.error_type)
+      end
+
       def test_send_request_raises_unprocessable_entity_error
         request = {
           jsonrpc: "2.0",
@@ -413,6 +424,116 @@ def test_send_request_raises_error_for_sse_without_response
         assert_equal(:parse_error, error.error_type)
       end
 
+      def test_captures_session_id_and_protocol_version_on_initialize
+        stub_request(:post, url)
+          .to_return(
+            status: 200,
+            headers: {
+              "Content-Type" => "application/json",
+              "Mcp-Session-Id" => "session-abc",
+            },
+            body: { result: { protocolVersion: "2025-11-25" } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "1", method: "initialize" })
+
+        assert_equal("session-abc", client.session_id)
+        assert_equal("2025-11-25", client.protocol_version)
+      end
+
+      def test_includes_session_header_after_initialize
+        stub_request(:post, url)
+          .to_return(
+            status: 200,
+            headers: {
+              "Content-Type" => "application/json",
+              "Mcp-Session-Id" => "session-abc",
+            },
+            body: { result: { protocolVersion: "2025-11-25" } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "1", method: "initialize" })
+
+        stub_request(:post, url)
+          .with(headers: { "Mcp-Session-Id" => "session-abc" })
+          .to_return(
+            status: 200,
+            headers: { "Content-Type" => "application/json" },
+            body: { result: { tools: [] } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "2", method: "tools/list" })
+      end
+
+      def test_session_id_not_overwritten_by_subsequent_responses
+        stub_request(:post, url)
+          .to_return(
+            status: 200,
+            headers: {
+              "Content-Type" => "application/json",
+              "Mcp-Session-Id" => "original-session",
+            },
+            body: { result: { protocolVersion: "2025-11-25" } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "1", method: "initialize" })
+
+        assert_equal("original-session", client.session_id)
+
+        stub_request(:post, url)
+          .to_return(
+            status: 200,
+            headers: {
+              "Content-Type" => "application/json",
+              "Mcp-Session-Id" => "different-session",
+            },
+            body: { result: { tools: [] } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "2", method: "tools/list" })
+
+        assert_equal("original-session", client.session_id)
+      end
+
+      def test_stateless_server_without_session_id_header
+        stub_request(:post, url)
+          .to_return(
+            status: 200,
+            headers: { "Content-Type" => "application/json" },
+            body: { result: { protocolVersion: "2025-11-25" } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "1", method: "initialize" })
+
+        assert_nil(client.session_id)
+        assert_equal("2025-11-25", client.protocol_version)
+      end
+
+      def test_clears_session_state_on_404
+        stub_request(:post, url)
+          .to_return(
+            status: 200,
+            headers: {
+              "Content-Type" => "application/json",
+              "Mcp-Session-Id" => "session-abc",
+            },
+            body: { result: { protocolVersion: "2025-11-25" } }.to_json,
+          )
+
+        client.send_request(request: { jsonrpc: "2.0", id: "1", method: "initialize" })
+
+        assert_equal("session-abc", client.session_id)
+
+        stub_request(:post, url).to_return(status: 404)
+
+        assert_raises(SessionExpiredError) do
+          client.send_request(request: { jsonrpc: "2.0", id: "2", method: "tools/list" })
+        end
+
+        assert_nil(client.session_id)
+        assert_nil(client.protocol_version)
+      end
+
       private
 
       def stub_request(method, url)