Skip to content

feat: switch to HTTP/SSE transport to eliminate session token context bloat #101

@m2ux

Description

@m2ux

Problem

The server currently uses stdio transport. Workflow state is encoded as a signed JWT session token and returned in tool call result content. This token (~500+ chars) is visible to the LLM and persists in the context window for the entire workflow session, consuming tokens on every tool call.

There is no mechanism in the stdio transport to pass data outside of message content, so the token cannot be made invisible to the LLM.

Solution

Switch to HTTP/SSE transport and use the Mcp-Session-Id response header to carry the session token.

The MCP 2025-03-26 spec defines this header explicitly for stateless session management:

  • Server returns Mcp-Session-Id: <jwt> in the initialize response
  • Client stores it and replays it on every subsequent request automatically
  • JWT never appears in tool result content → never enters the LLM's context window
  • Server remains fully stateless (no server-side state store required)

The MCP TypeScript SDK correctly implements this: it reads Mcp-Session-Id from the initialize response and includes it in all subsequent requests. The apparent bug in #852 is a CORS misconfiguration issue in browser contexts only — Node.js clients (including Claude Code) are unaffected.

Expected Outcome

  • Session JWT is transported entirely via HTTP header infrastructure
  • LLM context window contains no session token content
  • Server remains stateless — no changes to JWT signing/verification logic required
  • Workflow sessions are fully resumable across requests as today

Notes

  • The Mcp-Session-Id header value may contain any visible ASCII (0x21–0x7E), so the existing signed JWT format is compatible without modification
  • Claude Code connects to MCP servers via Node.js, so CORS headers (Access-Control-Expose-Headers) are not required
  • The stdio entrypoint can be retained for local development/debugging

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions