MCP Advanced: StreamableHTTP Transport, SSE Workaround, Remote MCP Servers

The StreamableHTTP transport enables MCP clients to connect to remotely hosted servers over HTTP, unlike STDIO which requires both parties on the same machine. This opens up public MCP servers that anyone can access over the internet. However, HTTP creates a fundamental challenge because it is designed for clients to request from servers, not the reverse. StreamableHTTP uses a workaround involving Server-Sent Events to enable server-to-client messages that MCP features like sampling and notifications require.

The initialization follows three steps. First, the client sends an Initialize Request to the server over HTTP. Second, the server responds with an Initialize Result that includes a special mcp-session-id header. Third, the client sends an Initialized Notification with that session ID attached. This session ID uniquely identifies the client and must be included in all future requests. After initialization, the client can optionally establish a Server-Sent Events connection by making a GET request, which creates a persistent channel the server can use to stream messages back to the client.

After initialization, the client makes a GET request that establishes a Server-Sent Events connection, creating a long-lived HTTP response that stays open. The server can then push messages through this persistent channel at any time, working around HTTP's client-only-initiates limitation. This SSE connection is the key mechanism for server-to-client communication. Through it, the server can send sampling requests, progress notifications, logging messages, and other server-initiated communications impossible with standard HTTP request-response.

When the client makes a tool call over StreamableHTTP, the system creates two separate SSE connections. The primary SSE connection is established during initialization, stays open indefinitely, and handles server-initiated requests like sampling. The tool-specific SSE connection is created per tool call and closes when the result is sent. Progress notifications route through the primary connection, while logging and tool results go through the tool-specific connection. This separation prevents tool responses from blocking server-initiated requests.

Two key settings control StreamableHTTP behavior: stateless_http and json_response. Both default to false. When set to true, they can break core MCP functionality including progress notifications, logging, and server-initiated requests like sampling. If your MCP application works perfectly with STDIO transport locally but breaks when deployed with HTTP transport, these settings are likely the cause. Certain deployment scenarios may force you to enable them, but doing so means accepting reduced functionality in exchange for simpler HTTP compatibility.

Setting json_response to true disables streaming for POST request responses. Instead of receiving multiple SSE messages as a tool executes, showing intermediate progress and log updates, the client gets only the final result as a plain JSON response. This means no intermediate progress messages, no log statements during execution, and just the final tool result delivered at once. This flag is simpler to integrate with systems that expect standard JSON HTTP responses but sacrifices the real-time feedback that makes long-running tool operations user-friendly. ---