# What structural signals indicate a resumable MCP streamable-session versus a poisoned SSE-to-streamable upgrade **Date of Record:** 2026 November 15 **Scope:** Applies to MCP servers exposing the HTTP-native streamable transport with `Mcp-Session-Id` and `Last-Event-ID` resumption semantics, and to clients negotiating an upgrade from a legacy SSE endpoint to the streamable endpoint. Does not apply to stdio transports or to pure SSE transports without session identifiers. ## Core Distinction The distinction that matters operationally is between a *resumable session* and a *resumable event stream*. A streamable session is identified by `Mcp-Session-Id` and is a server-side lifecycle object with an associated event log keyed by monotonically increasing event IDs. An SSE event stream is a transport-level connection that may be re-established independently of the session. Clients and intermediaries routinely conflate these: a successful `Last-Event-ID` replay proves only that the *event log* survived, not that the *session* survived. The reverse is also true: a live session with a truncated or rotated event log will accept a `Last-Event-ID` and silently resume at the wrong offset, producing a session that appears healthy but has lost tool-call results. The second, more insidious distinction is between an *upgrade negotiation* and an *upgrade completion*. When a client presents an `Accept: text/event-stream` header to the streamable endpoint while holding a legacy SSE session cookie, the server may respond `200 OK` with `Content-Type: text/event-stream` — which looks identical to a successful upgrade — while actually serving the legacy SSE handler. The structural signal of a completed upgrade is not the response status or content type; it is the presence of `Mcp-Session-Id` in the response headers *and* the absence of the legacy `event: endpoint` frame in the first flush. ## What Was Observed During a migration of an MCP server from SSE-only to streamable HTTP, the following sequence was observed repeatedly across three client implementations: 1. Client opens `GET /mcp` with `Accept: text/event-stream` and a legacy session cookie. Server responds `200`, `Content-Type: text/event-stream`, and immediately emits `event: endpoint` with a legacy POST URL. The client interprets this as a successful upgrade because status and content type match the streamable spec's success shape. 2. Client subsequently issues `POST /mcp` with JSON-RPC payloads to the *streamable* path. The server, having routed the GET to the legacy handler, has no streamable session for this client and returns `404` with `Mcp-Session-Id` absent. 3. Client retries with `Last-Event-ID: 0` on a fresh GET. The server's streamable handler accepts it, mints a new `Mcp-Session-Id`, and replays from its event log — but the event log was scoped to the *new* session, so replay is empty and the client silently loses any in-flight tool results from before the upgrade attempt. 4. In a minority of cases the server emitted `Mcp-Session-Id` on the legacy SSE response (a bug in a shared middleware that set the header unconditionally). The client then held a session ID that the streamable handler did not recognize, producing `404` on every subsequent POST and an infinite reconnect loop with exponential backoff capped at 30s. The invariant violated: **a `Mcp-Session-Id` in a response header must be honored by the same handler that emitted it.** Shared middleware that decorates all responses with session headers breaks the binding between session ID and handler identity, and there is no protocol-level signal that distinguishes a real session ID from a decorative one. ## Condition of Validity Resumption via `Last-Event-ID` is only valid when all of the following hold: - The server's event log is scoped to the session ID presented in the same request, not to a global or per-connection log. - The `Last-Event-ID` value was emitted by the *same* session's stream, not by a prior session that happened to use overlapping IDs. - The server has not rotated the event log (e.g., on deploy) since the referenced event ID was issued. Rotation must be signaled by a `404` on the resumption GET, not by replaying from the oldest retained event. - The client's upgrade attempt did not pass through an intermediary that rewrites `Accept` headers or strips `Mcp-Session-Id`. The upgrade from SSE to streamable is only valid when the response to the *first* GET contains `Mcp-Session-Id` and does *not* contain an `event: endpoint` frame. If both appear, the response is ambiguous and must be treated as a failed upgrade, regardless of status code. ## Decision Boundary The operational decision rule: - If a GET returns `200` with `Content-Type: text/event-stream` and no `Mcp-Session-Id`, treat as legacy SSE. Do not attempt streamable POSTs against this connection. - If a GET returns `200` with `Mcp-Session-Id` and an `event: endpoint` frame in the first flush, treat as a poisoned upgrade. Abort the connection, discard any session ID from the response, and fall back to the legacy path explicitly rather than retrying the upgrade. - If a resumption GET with `Last-Event-ID` returns `200` but the first replayed event ID is not strictly greater than the requested `Last-Event-ID`, treat the event log as rotated and re-initialize the session rather than continuing. - If a POST returns `404` while the client holds a `Mcp-Session-Id` that was emitted by a GET on the same endpoint, treat the session as decorative and re-negotiate from scratch; do not retry the POST with the same session ID. The boundary is sharp: there is no "mostly upgraded" state. A connection is either streamable-and-session-bound or it is not, and the only structural evidence is the co-occurrence of `Mcp-Session-Id` with the absence of legacy framing. ## Operational Effect The practical consequence is that clients must validate the *shape* of the upgrade response, not its status. A `200 OK` is necessary but not sufficient. The cost of missing this is silent data loss: tool-call results emitted between the upgrade attempt and the first successful streamable POST are dropped, and the client has no way to detect the loss because the session appears live. In the observed migration, this manifested as intermittent missing `tools/call` responses under load, correlated with clients that had stale legacy cookies — a failure mode that took two weeks to isolate because every individual response looked correct. The defensive posture is to treat session identity as a capability token issued by a specific handler, to verify handler identity by round-tripping a no-op request before trusting a session for stateful operations, and to fail closed on any response that mixes legacy and streamable framing signals. ```python class PoisonedUpgradeError(RuntimeError): """Raised when an SSE-to-streamable upgrade response is structurally ambiguous.""" class SessionBindingError(RuntimeError): """Raised when a session ID is not honored by the handler that emitted it.""" def validate_upgrade_response(status: int, headers: dict, first_frame: str | None) -> str: """Return the validated Mcp-Session-Id, or raise if the upgrade is poisoned.""" if status != 200: raise PoisonedUpgradeError(f"upgrade returned status {status}") content_type = headers.get("content-type", "") if "text/event-stream" not in content_type: raise PoisonedUpgradeError(f"unexpected content-type {content_type!r}") session_id = headers.get("mcp-session-id") if session_id is None: raise PoisonedUpgradeError( "no Mcp-Session-Id on streamable upgrade response; " "treat as legacy SSE, not streamable" ) if first_frame is not None and first_frame.startswith("event: endpoint"): raise PoisonedUpgradeError( "response carries both Mcp-Session-Id and legacy endpoint frame; " "handler identity is ambiguous" ) return session_id def validate_resumption(status: int, requested_last_event_id: int, replayed_ids: list[int]) -> None: """Raise if the event log was rotated under a resumption attempt.""" if status == 404: raise SessionBindingError("session not recognized on resumption; re-initialize") if not replayed_ids: return if min(replayed_ids) <= requested_last_event_id: raise PoisonedUpgradeError( f"replayed event id {min(replayed_ids)} <= requested " f"{requested_last_event_id}; event log rotated, replay would lose events" ) ```