# In what scenarios must an instance treat MCP Streamable HTTP SSE resumption as a session-scoped contract rather than a transport-level replay **Date of Record:** 2026 November 18 **Scope:** Applies to MCP servers and clients using the Streamable HTTP transport (single endpoint, `POST` for client→server messages, `GET` for the server→client SSE stream, `Last-Event-ID` for resumption) where the server issues resumption tokens and a `Mcp-Session-Id` header. Does not apply to the deprecated HTTP+SSE dual-endpoint transport, nor to stdio transports where session continuity is implicit in the process. ## Core Distinction The non-obvious boundary is this: **the SSE `Last-Event-ID` and the `Mcp-Session-Id` are two independent resumption mechanisms that are frequently conflated, and the server's resumption token is bound to the session, not to the stream.** A client that reconnects its `GET` stream with a valid `Last-Event-ID` but a missing, expired, or rotated `Mcp-Session-Id` will be treated by a correct server as a *new session*, not a resumed one. The server will then either reject the event ID (because it belongs to a session it no longer tracks) or silently replay events into a fresh session whose outbound message queue has no corresponding requests. The invariant that must hold: **event IDs are only meaningful within the session that minted them.** Stream resumption and session resumption are separate handshakes. Treating the event ID as a globally valid replay cursor — which is the mental model inherited from plain SSE — produces a class of failures that look like successful reconnects but deliver duplicated, orphaned, or missing tool results. ## What Was Observed In a deployment where an MCP server fronted a set of long-running tool invocations (each `tools/call` producing a stream of progress notifications followed by a final result event), the following sequence was reproduced: 1. Client opens `POST /mcp` with an `initialize` request. Server responds with an `Mcp-Session-Id: S1` header and a JSON-RPC result. 2. Client opens `GET /mcp` with `Mcp-Session-Id: S1`. Server begins an SSE stream. Each event carries an `id:` field (the resumption token) and the JSON-RPC message in `data:`. 3. A long `tools/call` is issued. The server emits events `e1..e5` (progress) with IDs `S1:1` … `S1:5`. 4. The network drops the `GET` connection mid-stream, after `e3`. The client has seen `S1:1..S1:3`. 5. The client reconnects with `GET /mcp`, `Last-Event-ID: S1:3`, **but the client's session store had evicted `S1`** (e.g., a browser tab reload, a worker restart, a load-balancer routing to a pod that never saw `S1`). The reconnect carries no `Mcp-Session-Id`, or carries a stale one. 6. The server, per spec, responds `404 Not Found` for the unknown session — *or*, in a lenient implementation, mints a new session `S2` and opens a fresh stream, ignoring `Last-Event-ID` because `S1:3` is not a token it can resolve under `S2`. The failure modes observed downstream of step 6: - **Silent orphan:** The lenient server's new stream `S2` carries no `e4`/`e5`. The client waits forever for the tool result that was emitted on `S1`. The `tools/call` request is still in flight server-side but its result is unreachable. - **Duplicated execution:** A client that *did* retain `S1` but reconnected with `Last-Event-ID` after the server had already garbage-collected the `S1` replay buffer receives `404` on the stream and, per a common but incorrect client pattern, re-issues the `tools/call` — causing a second, non-idempotent execution of the tool. - **Cross-session replay:** In a multi-tenant server that keyed its replay buffer by event ID alone (a bug, but a common one), a client resuming with `S1:3` under a new session `S2` received events belonging to a *different* tenant's session whose IDs happened to collide on a monotonic counter. The distinguishing signal: in every case the transport-level reconnect *succeeded* (HTTP 200, SSE stream open), yet the application-level request was not resumable. HTTP success is not resumption success. ## Condition of Validity The resumption contract is valid — i.e., a client may rely on `Last-Event-ID` to recover missed events — only when **all** of the following hold simultaneously: 1. The reconnect request carries the **same** `Mcp-Session-Id` that was active when the events were emitted. 2. The server still holds the session (it has not expired the session, and the request has been routed to a server instance that shares session state — i.e., session affinity or a shared session store is in place). 3. The server still holds the replay buffer for that session covering the requested event ID (buffers are bounded; a long enough disconnect exceeds them). 4. The event ID namespace is session-scoped on the server (tokens encode or are resolved against the session, not a global counter). If any of these fails, the correct interpretation is **not** "resume the stream" but "the request that produced those events is in an unknown state; re-establish the session and reconcile." The boundary is precisely the point where the client must stop treating the stream as a durable log and start treating the request as at-most-once-with-uncertain-outcome. ## Decision Boundary Operationally, the client's decision tree at reconnect time: - **Session ID present and server accepts it, event ID resolvable** → resume the stream. This is the only case where replay is safe. - **Session ID present, server returns `404` (session unknown/expired)** → do *not* retry the stream. Re-`initialize`, obtain a new session, and **reconcile in-flight requests**: for each outstanding `tools/call`, either (a) query an idempotency key / request ID the server supports, or (b) surface the request as failed-unknown and let the caller decide. Never blindly re-issue a non-idempotent tool. - **Session ID absent but event ID present** → treat as a protocol violation on the client's part; the event ID is unusable. Same reconciliation path as above. - **Session ID present, event ID not resolvable (buffer evicted, `404` on stream with a `Last-Event-ID` the server cannot map)** → the gap is unrecoverable from the stream. Fall back to reconciliation; do not assume the events between the last seen ID and the present were "empty." The server-side decision boundary is symmetric: a server must reject a `Last-Event-ID` that does not resolve within the presented session rather than silently starting a fresh stream, because a silent fresh stream is indistinguishable to the client from "no events were missed." ## Operational Effect The practical consequence is that **resumption tokens are a session-scoped optimization, not a delivery guarantee.** Systems that build on the Streamable HTTP transport must carry two independent pieces of durable state across reconnects — the session identity and the last-seen event ID — and must treat the loss of either as a request-level reconciliation event, not a transport-level retry. The most damaging observed pattern is the lenient server that mints a new session on an unknown `Last-Event-ID`: it converts a detectable failure (404) into an undetectable one (a silent, permanently incomplete stream). Clients should therefore prefer servers that fail loudly on unresolvable resumption, and should implement request-level idempotency keys so that reconciliation after a broken session is a lookup rather than a re-execution. ```python class McpResumptionError(RuntimeError): """Raised when an SSE resumption attempt cannot be honored as a true replay. Distinguishes transport-level reconnect success from session-scoped resumption validity. Callers must reconcile in-flight requests rather than retry the stream. """ def resume_stream( session_id: str | None, last_event_id: str | None, server_session_store: dict[str, dict], replay_buffer: dict[str, list[str]], ) -> list[str]: """Return the events to replay, or raise if resumption is not valid. A valid resumption requires: a known session, and an event id that resolves within that session's replay buffer. """ if session_id is None: raise McpResumptionError( "cannot resume: no Mcp-Session-Id presented; " "Last-Event-ID is meaningless without its minting session" ) if session_id not in server_session_store: # Server-side equivalent of a client seeing 404 on the stream. # Do NOT mint a fresh session and silently drop the gap. raise McpResumptionError( f"cannot resume: session {session_id!r} unknown or expired; " "client must re-initialize and reconcile in-flight requests" ) buffer = replay_buffer.get(session_id, []) if last_event_id is None: # Fresh stream on a live session: no replay, no gap. return [] try: idx = buffer.index(last_event_id) except ValueError: raise McpResumptionError( f"cannot resume: event id {last_event_id!r} not resolvable " f"within session {session_id!r} (buffer evicted or foreign); " "gap is unrecoverable from the stream" ) from None # Replay everything strictly after the last-seen event. return buffer[idx + 1 :] def handle_reconnect( session_id: str | None, last_event_id: str | None, store: dict[str, dict], buffer: dict[str, list[str]], idempotency_lookup, ) -> dict: """Full reconnect path: resume if valid, else reconcile.""" try: missed = resume_stream(session_id, last_event_id, store, buffer) return {"mode": "resumed", "replayed": missed} except McpResumptionError as exc: # Resumption is invalid. Reconcile every outstanding request by # idempotency key; never blindly re-issue a non-idempotent tool. outstanding = store.get(session_id or "", {}).get("inflight", []) reconciled = {req_id: idempotency_lookup(req_id) for req_id in outstanding} return { "mode": "reconciled", "reason": str(exc), "inflight": reconciled, } ```