What is Streamable HTTP in MCP?
Streamable HTTP is the MCP transport for servers reached over the network. The client sends every JSON-RPC message as an HTTP POST to one endpoint, such as /mcp, and the server answers with either a JSON object or a server-sent events stream for that request. It replaced the older HTTP+SSE transport in the 2025-03-26 revision.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
The client POSTs one JSON-RPC request per HTTP request to the MCP endpoint, with an Accept header that allows both application/json and text/event-stream.
Headers mirror the body: MCP-Protocol-Version, Mcp-Method and, for calls, reads and prompt gets, Mcp-Name. A mismatch gets a 400 with error -32020.
POST /mcp MCP-Protocol-Version: 2026-07-28 Mcp-Method: tools/call Mcp-Name: get_weatherFor a quick answer the server returns one JSON object. For a long one it opens an SSE stream for that request, sends progress notifications, then the response.
To hear about changes, the client POSTs subscriptions/listen; the response is an SSE stream that stays open and carries only the notifications it asked for.
To cancel, the client closes the stream. There is no session header, no GET stream and no resuming with Last-Event-ID in the 2026-07-28 revision.
Streamable HTTP versus stdio
MCP defines two standard transports, and the protocol means the same thing on both. With stdio, the client launches the server as a child process and the two talk through its standard streams: one JSON-RPC message per line on stdin and stdout, nothing on stdout that is not a message, and stderr free for logging. It is the natural fit for a server that lives on your laptop and needs your files or your shell.
Streamable HTTP is for a server that runs as its own process, often on another machine, and serves many clients at once. Each message is an HTTP POST to a single URL, the MCP endpoint. Because it is plain HTTP, it goes through proxies, load balancers and gateways, and it can sit behind OAuth. Intraface's server at https://app.intraface.cc/mcp is one such endpoint: agents on many laptops POST to the same address.
Streamable HTTP versus HTTP+SSE
The first network transport, from the 2024-11-05 revision, was HTTP+SSE: the client opened a GET that returned a long-lived event stream, received an endpoint event telling it where to POST, and sent everything there while answers arrived on the stream. Two endpoints, one permanent connection, awkward to scale.
Streamable HTTP, introduced in 2025-03-26, collapsed that into one endpoint. The server decides per request whether to answer with Content-Type: application/json or text/event-stream; the client must accept both. HTTP+SSE has been deprecated since then, and 2026-07-28 formally lists it in the deprecated features registry under the new lifecycle policy. A client that wants to support old servers POSTs first and, only if it gets a 400, 404 or 405 with no recognisable modern JSON-RPC error, falls back to the GET and waits for the endpoint event.
Example: one request, two kinds of answer
An agent calls a tool. The client POSTs a tools/call body with Accept: application/json, text/event-stream, plus MCP-Protocol-Version: 2026-07-28, Mcp-Method: tools/call and Mcp-Name set to the tool's name. For a fast lookup the server returns 200 with one JSON-RPC response. For a slow job it returns an SSE stream, pushes notifications/progress events as it works, ends with the JSON-RPC response and closes the stream. Closing that stream from the client side is the cancellation signal; no separate message is needed.
If the server needs the person's input partway through, it does not open a channel back. It returns an InputRequiredResult and the client retries the POST with the answers. For change notifications, the client POSTs subscriptions/listen with a filter such as toolsListChanged: true; that response stream stays open, the server sends an acknowledgment first, then only the notification types requested, with an SSE comment line now and then as a keep-alive.
What changed in 2026-07-28
The revision reshaped the transport around statelessness. Gone: the Mcp-Session-Id header and HTTP DELETE to end a session, the standalone GET stream, server-initiated JSON-RPC requests on any stream, and Last-Event-ID resumption. A broken stream now simply loses the in-flight request and the client re-sends it with a new id. New: the required Mcp-Method and Mcp-Name headers, optional Mcp-Param-* headers mirrored from tool arguments via x-mcp-header, and the -32020 HeaderMismatch error when headers and body disagree. A 2026-07-28 server that receives a GET or DELETE from an older client should answer 405.
Common mistakes
- Buffering proxies. Servers should send
X-Accel-Buffering: noon SSE responses so nginx and friends release events immediately. - Skipping Origin checks. A server must validate the
Originheader and return 403 on a bad one, or a web page could reach a local MCP server through DNS rebinding. Bind local servers to 127.0.0.1, not 0.0.0.0. - Expecting progress on the listen stream.
notifications/progressandnotifications/messageonly flow on the stream of the request they belong to. - Reading the headers alone. Headers exist so intermediaries can route; the body is the source of truth, and the server must reject a request where they differ.
FAQ
- Is Streamable HTTP the same as SSE in MCP?
- No, though it uses SSE. The original HTTP+SSE transport (2024-11-05) had two endpoints: a GET that opened a long event stream and a POST for sending. Streamable HTTP has one endpoint and uses server-sent events only as an optional way to answer a single POST. HTTP+SSE is deprecated.
- Does Streamable HTTP still use the Mcp-Session-Id header?
- Not in 2026-07-28. Sessions were removed along with the initialize handshake; every request carries its protocol version and client capabilities in _meta. Servers on the new revision ignore the header, and a server that needs state across calls hands out its own handles as ordinary tool arguments.
- When should an MCP server use stdio instead of Streamable HTTP?
- When the client starts it as a program on the same machine. stdio is simpler: newline-delimited JSON-RPC on stdin and stdout, logs on stderr, no HTTP at all. Use Streamable HTTP when the server runs elsewhere, serves many clients, or sits behind a load balancer.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.