StreamableHTTP in depth

💡 MCP Communication Flow: Streamable HTTP Transport

🌐 Core Problem & Solution

• Challenge: MCP functionality (e. g. , sampling, notifications, logging) requires the server to initiate requests to the client. Standard HTTP protocols make this server-to-client communication difficult.
• Solution: Streamable HTTP provides a workaround to enable server-initiated requests.

🔗 Connection Initialization

• Standard Flow: Client sends initialize request $\rightarrow$ Server replies $\rightarrow$ Client sends initialize notification request.
• HTTP Modification: Upon initial connection, the server's response includes an MCP session ID header.
• Requirement: This unique MCP session ID must be included in all subsequent client requests to identify the connection.

📡 Server-to-Client Communication (The Workaround)

• Purpose: To allow the server to stream messages (e. g. , for sampling or progress) to the client at any time.
• Mechanism:
• The client sends a GET request (including the session ID).
• The server responds with a Server-Sent Event (SSE) response.
• This SSE connection is long-lived, enabling the server to stream messages down to the client.

🛠️ Tool Calling Flow (Secondary SSE)

• Trigger: The client initiates a call_tool request (including the session ID).
• Mechanism:
• The MCP server opens a second, separate SSE response specifically for this tool call.
• This second SSE connection is automatically closed once the call_tool_result is delivered.
• Message Separation (Critical Detail):
• Progress Notifications: Are sent via the first (long-lived) SSE response.
• Logging/Results: Are sent via the second (call-specific) SSE response.

⚠️ Important Caveat

• The entire flow is complex due to the workaround. Setting certain transport flags to true can break parts of this established communication flow.

Takeaways

• Purpose of Streamable HTTP: It is a workaround enabling the server to initiate requests (e. g. , for sampling or notifications) to the client, overcoming the limitations of standard HTTP protocols.
• Connection Identification: All client requests must include a unique MCP session ID (received in the initial server response) to correctly identify the connection.
• General Streaming (Progress): The server uses a long-lived Server-Sent Event (SSE) connection (initiated via a GET request) to stream general progress notifications and updates to the client.
• Tool Calling Flow: Tool results utilize a second, separate SSE connection that is automatically closed upon delivery of the call_tool_result. Progress notifications and final results are handled by two distinct SSE streams.