Streamable HTTP Transport

## The shape in one sentence Streamable HTTP is MCP's remote transport as of revision 2026-07-28: **one HTTP endpoint that accepts POST and nothing else**, where every exchange is client-initiated and the response may be either a plain JSON body or a Server-Sent Events stream, chosen by the server for that single request. ## What the client sends The client makes an ordinary HTTP `POST` to the MCP endpoint URL. The body is exactly one JSON-RPC message — a request such as `tools/call`, `tools/list` or `resources/read`, or a notification such as `notifications/cancelled`. The `Accept` header must offer both media types: `Accept: application/json, text/event-stream` This is not decoration. The client is telling the server "either shape is fine", because the choice belongs to the server and is made after it has looked at the request. A client that offers only `application/json` has told the server it cannot receive a stream, and a server that needs to stream has nowhere to go. Because MCP is stateless in this revision, the POST also carries everything the server needs to interpret it: the protocol version and the client's capabilities travel inside `params._meta`, and are mirrored into HTTP headers so that infrastructure in front of the server can route without parsing the body. ## What the server replies The server has three outcomes: 1. **A JSON response.** `200 OK`, `Content-Type: application/json`, body is the JSON-RPC response object for the request that was posted. This is the normal answer for anything that completes quickly — `tools/list`, `server/discover`, a fast tool call. 2. **An SSE-upgraded stream.** `200 OK`, `Content-Type: text/event-stream`. The response body becomes an event stream on which the server can send request-scoped notifications — `notifications/progress`, `notifications/message` — and then the final JSON-RPC response, after which the stream ends. Crucially this stream belongs to *that request*: it is not a general-purpose push channel, and messages for other requests do not appear on it. 3. **`202 Accepted` with no body.** This is the answer to a JSON-RPC notification. A notification has no `id`, so by definition there is no response to return; `202` says "received, nothing to answer". ## Why one endpoint and one method Earlier MCP designs had a second channel: a long-lived `GET` stream the client opened to receive server-initiated traffic. That is gone in 2026-07-28. Server-to-client pushes that are not tied to a particular request now ride on a dedicated `subscriptions/listen` call — which is itself just another POST whose response happens to be a long-lived stream. The result is that the transport has exactly one verb and one URL, which makes it trivially deployable behind ordinary HTTP infrastructure: a load balancer, an API gateway or a WAF sees nothing but POSTs to a single path. A server that implements only the 2026-07-28 revision therefore SHOULD answer `GET` or `DELETE` on the endpoint with `405 Method Not Allowed`. ## Why the server, not the client, picks the body shape The server is the only party that knows whether the work will take 20 milliseconds or 20 seconds, and whether it will have anything to report along the way. Letting it decide per request avoids two bad alternatives: forcing every response through SSE (wasteful for a `tools/list` that is one small JSON object, and hostile to caching intermediaries), or forcing everything into a single JSON body (which means a two-minute tool call reports nothing until it finishes and looks like a hung connection to every proxy in the path). ## Practical consequences - An HTTP client library that buffers responses fully before returning is unusable for the streaming case; you need one that exposes the body incrementally. - Intermediaries that buffer response bodies (some reverse-proxy defaults do) will hold the SSE frames until the request completes, destroying progress reporting without producing an error anywhere. - Because the stream is per-request, closing it has a specific meaning to the server: it is a cancellation of that request. - Because every POST is self-contained, any server instance can serve any request; there is no affinity requirement introduced by the transport itself. ## What this looks like end to end A client calling a slow tool posts one message, gets `200` with `text/event-stream`, reads several `notifications/progress` messages, reads the final `tools/call` response, and the server closes the stream. A client listing tools posts one message and gets `200` with `application/json` and the whole result at once. Both used the same URL and the same method.