12. Streamable HTTP Transport

Chapter 12 of 22 · 15 min

KEY INSIGHT

The Streamable HTTP transport mechanism transforms MCP from a synchronous request-response protocol into a capable, scalable architecture that handles real-time updates and long-running operations. MCP servers communicate over HTTP using Server-Sent Events (SSE) for streaming responses. This design accommodates operations that produce output over timeΓÇöa critical feature for AI agents that may need to process files, query databases, or perform operations with variable completion times. The transport layer establishes two key endpoints: an POST endpoint for sending JSON-RPC requests and a GET endpoint for receiving streamed responses via SSE. When a client initiates a request, the server can begin responding immediately while continuing to process the operation. ```python # server.py from mcp.server.fastmcp import FastMCP from starlette.routing import Match from starlette.responses import Response mcp = FastMCP("Streamable Server") @mcp.tool() async def long_running_analysis(data: str) -> str: """Simulate analysis that streams progress updates.""" results = [] for i in range(5): # Simulate work await asyncio.sleep(1) results.append(f"Batch {i}: processed") return "\n".join(results) ``` The client initiates streaming by sending a POST request with the standard JSON-RPC payload. The server responds with a `text/event-stream` content type, sending chunks as they become available. Each chunk follows the SSE format with an `event:` field and `data:` payload. For clients, the streaming pattern requires handling partial responses: ```python # client_streaming.py import httpx async def stream_request(tool_name: str, arguments: dict): async with httpx.AsyncClient() as client: response = await client.post( f"{BASE_URL}/mcp", json={ "jsonrpc": "2.0", "method": "tools/call", "params": {"name": tool_name, "arguments": arguments}, "id": 1 }, headers={"Accept": "text/event-stream"}, timeout=None ) async for line in response.iter_lines(): if line.startswith("data: "): data = json.loads(line[6:]) yield data ``` The protocol also supports session management, allowing clients to maintain state across multiple requests. Sessions enable caching, connection pooling, and authenticated contexts. Failure handling in streaming differs from request-response. If a connection drops mid-stream, the client must detect the incomplete response and either retry or signal an error. The JSON-RPC protocol provides `id` fields that help correlate partial results.

EXERCISE

Implement a streaming MCP tool that processes a large dataset in chunks. Measure the response time difference between buffered (all-at-once) and streamed approaches. Verify that clients can correctly reconstruct the full response from SSE chunks.