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

[atesgoral]

Summary

• Capture Mcp-Session-Id and protocolVersion from the initialize response and expose them on the transport as session_id / protocol_version
• Automatically include Mcp-Session-Id on subsequent requests once captured
• Map 404 responses to a new MCP::Client::SessionExpiredError (subclass of RequestHandlerError) and clear local session state so callers can start a new session

Per the Streamable HTTP spec:

If the server returns an Mcp-Session-Id header during initialization, clients MUST include it on all subsequent HTTP requests.

When a client receives HTTP 404 in response to a request containing the Mcp-Session-Id, it MUST start a new session by sending a new InitializeRequest without a session ID attached.

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

This is part of a series of PRs splitting up #321. Previous: #322 (SSE parsing) and #323 (202 Accepted). Next: session termination via DELETE (close), then client handshake ergonomics and example rewrite.

Test plan

• New tests for session capture on initialize
• New tests that session header is included on subsequent requests
• New test that session ID is not overwritten by later responses
• New test that stateless servers (no Mcp-Session-Id header) work fine
• 404 now raises SessionExpiredError and clears session state
• Full suite passes (bundle exec rake test)

🤖 Generated with Claude Code

[koic]

This implementation currently raises SessionExpiredError for every 404, including when @session_id is nil (e.g., the very first request before initialize, or a stateless server where the URL is misconfigured).

The spec wording is:

When a client receives HTTP 404 in response to a request containing an Mcp-Session-Id, it MUST start a new session...

So strictly speaking, "session expired" would apply only when a session ID was actually attached.

Not a blocker, and it's fine to keep the current behavior if that's intentional, but one alternative would be:

if @session_id
  clear_session
  raise SessionExpiredError.new(...)
else
  raise RequestHandlerError.new(..., error_type: :not_found, ...)
end

That way a 404 from a wrong URL or a server that's simply not there surfaces as a generic :not_found rather than as a potentially misleading "session expired".

Would this make sense?

[atesgoral]

Good catch, the spec scopes the "start a new session" MUST to 404s carrying an MCP-Session-Id, so the session-expired interpretation shouldn't apply to plain 404s. Updated per your suggestion: branch on @session_id and only raise SessionExpiredError (and clear session state) when a session was attached; otherwise raise a generic RequestHandlerError with :not_found. Split the test into pre-session and post-session cases.

[atesgoral]

The spec has this as "MCP-Session-Id". Will standardize casing for existing server code + this new client code in a separate PR.

[koic]

Good catch, it looks like this was updated in the spec at some point.
modelcontextprotocol/modelcontextprotocol#1325

[koic]

Thanks!