Transports II: Streamable HTTP

Replies: status codes and two content types

For a request, the server answers with one of two content types, and clients must handle both. It's the difference between one letter and a parcel's tracking updates, which end with "delivered":

• Content-Type: application/json: one JSON-RPC response, the simple case.
• Content-Type: text/event-stream: a stream of server-sent events for this one request. Notifications about it, such as progress updates, come first, and the final response ends the stream:

HTTP/1.1 200 OK
Content-Type: text/event-stream
X-Accel-Buffering: no

data: {"jsonrpc":"2.0","method":"notifications/progress","params":{"progressToken":"t1","progress":50,"total":100}}

data: {"jsonrpc":"2.0","id":1,"result":{"resultType":"complete","content":[{"type":"text","text":"done"}]}}

X-Accel-Buffering: no asks proxies such as nginx not to hold events back in a buffer. For a notification POST, the server answers 202 Accepted with no body.

The spec ties several protocol failures to HTTP statuses, so even code that only reads the status can react sensibly:

Over Streamable HTTP, closing the event stream cancels the request, the way hanging up ends a call. Each request has its own stream, so a disconnect is unambiguous, and no cancel message is needed.

import requests

URL = "https://api.gradient.test/mcp"
META = {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {"name": "lesson-client", "version": "1.0"}}

def call(method, params=None, name=None, id=1):
    headers = {"Accept": "application/json, text/event-stream",
               "MCP-Protocol-Version": "2026-07-28", "Mcp-Method": method}
    if name is not None:
        headers["Mcp-Name"] = name
    body = {"jsonrpc": "2.0", "id": id, "method": method, "params": {**(params or {}), "_meta": META}}
    r = requests.post(URL, json=body, headers=headers, timeout=10)
    return r.status_code, r.json()

status, reply = call("tools/call", {"name": "get_campaign", "arguments": {"id": "cmp_103"}}, name="get_campaign")
print(status, reply["result"]["structuredContent"]["name"])

status, reply = call("tools/call", {"name": "get_campaign", "arguments": {"id": "cmp_103"}}, name="list_campaigns")
print(status, reply["error"]["code"], reply["error"]["message"][:40])

status, reply = call("tools/delete")
print(status, reply["error"])

Security: Origin checks and localhost

A server running on your own machine at http://127.0.0.1:8000/mcp seems unreachable from the internet. 127.0.0.1 is the address a computer uses for itself. But a web page you visit runs inside your browser, on your machine. It's a visitor already inside your house, within reach of your intercom. Through a trick called DNS rebinding, where a hostile site changes what its own name points to, the page can make your browser send requests to your local server. So:

• Servers must check the Origin header on every request. If it's present and not on the allowlist, answer 403. Browsers always send Origin, and command-line clients usually don't.
• Local servers should listen only on 127.0.0.1, not on every network interface (0.0.0.0).
• Remote servers need real authentication: OAuth, covered in a later lesson.

In plain words: "only on my machine" doesn't mean "safe from websites". Check where each request says it came from.

ALLOWED = {"http://localhost:3000", "https://app.shop.example"}

def check_origin(headers):
    origin = headers.get("Origin")
    if origin is None:
        return 200, "no Origin: not a browser page"
    if origin in ALLOWED:
        return 200, "allowed"
    return 403, f"refused {origin}"

print(check_origin({}))
print(check_origin({"Origin": "https://app.shop.example"}))
print(check_origin({"Origin": "https://evil.example"}))

How the transport changed

You'll meet older servers, so it helps to know the history. Deprecated below means still around, but on its way out.

• HTTP+SSE (2024-11-05) used two endpoints: one for POSTs, and one long-lived event stream for all replies. It's deprecated.
• Streamable HTTP, legacy revisions (2025-03-26 to 2025-11-25) used one endpoint but kept sessions. The server issued an Mcp-Session-Id header at initialize, and the client sent it on every request. There was also a GET stream for server messages, and resumable streams using Last-Event-ID.
• Streamable HTTP, 2026-07-28 removed sessions, the GET stream and resumption. Long-lived change notifications now come from a subscriptions/listen request, covered later. A broken stream means the client re-sends the request with a new id.

Things a remote server can't assume

Check headers against the body. An envelope marked "invoice" can hold anything. The Mcp-Method header is there so that load balancers can route without reading the body. But a client can send a header that disagrees with the body. If you authorize on the header and act on the body, an attacker gets past your checks. Compare them, and reject a mismatch.

127.0.0.1 doesn't keep web pages out. A page in your browser can send requests to your own machine. That's why Origin checks matter, even for a server nobody else can reach.

Handle both reply types. A client that only reads JSON fails the first time a server answers with an event stream.