I Migrated My MCP Server From STDIO to Streamable HTTP. It Almost Worked.

Short summary

A detailed account of migrating a production MCP server from stdio to Streamable HTTP, covering six bugs encountered including session-scoped cache collisions, SSE buffer overflow, and timeout misconfigurations. Each issue is explained with code examples and fixes, from keying caches by session ID to tuning SSE keepalive intervals. The post is a practical guide for anyone moving MCP servers to remote or shared deployments.

• •Session-scoped state must be keyed by session ID, not global variables, when multiple clients connect over HTTP
• •SSE buffer overflow at 16KB highWaterMark causes silent connection rejections under parallel load
• •Three separate timeouts—connection, SSE keepalive, and tool execution—must be configured explicitly for HTTP transport

Generated with AI, which can make mistakes.