# Why does an instance of the MCP streamable HTTP transport silently lose events across a session resumption when the SSE upgrade is negotiated on a POST that later returns 202 Accepted **Date of Record:** 2026 November 17 **Scope:** Applies to MCP servers implementing the HTTP-native streamable transport (single endpoint, `POST` for client→server messages, optional `GET` for server→client SSE stream, `Last-Event-ID` resumption) where the server may return `202 Accepted` on a `POST` that has no immediately available response body. Does not apply to pure SSE transports where the stream is established once and never re-negotiated, nor to servers that always respond synchronously with `200` and an inline `text/event-stream` body. ## Core Distinction The streamable transport conflates two logically distinct things onto one HTTP exchange: *acknowledgement of a client message* and *establishment of the server→client event stream*. A `POST` carrying a JSON-RPC request may legitimately return either `200` with an `text/event-stream` body (the response is streamed back on this exchange) or `202 Accepted` (the message was received; any response or related events will arrive on the separately negotiated `GET` SSE stream). The failure mode lives in the seam between these two: when a client has an *active resumable session* with a tracked `Last-Event-ID`, and it opens a fresh `POST` that negotiates an SSE upgrade, the server's event-ID sequence is per-*stream*, not per-*session*. A `202` on that `POST` tells the client "no stream here," but if the client optimistically attached `Last-Event-ID` to the request and the server accepted the upgrade before deciding to answer `202`, the server may have already *consumed* the resumption cursor and advanced its internal replay pointer — or, worse, emitted events into a stream the client never read because the body was empty. The non-obvious invariant: **`Last-Event-ID` is only meaningful on an exchange whose response body is actually an event stream.** A `202 Accepted` response has no body and therefore no event stream, so any `Last-Event-ID` supplied on that request must be treated as *not consumed*. Servers that advance their replay watermark on request receipt rather than on successful stream establishment violate this invariant, and clients that treat a `202` as "resumption succeeded, events will appear on GET" without re-issuing `Last-Event-ID` on the `GET` will silently skip the gap. ## What Was Observed A client held an established session (`Mcp-Session-Id: 7f3c…`) with a live `GET` SSE stream and a tracked `Last-Event-ID: 412`. The connection dropped (load-balancer idle timeout at 60s). On reconnect the client issued a `POST /mcp` with `Accept: application/json, text/event-stream`, `Last-Event-ID: 412`, and a `tools/call` request, expecting the server to either stream the response inline or acknowledge and resume. The server routed the request to a worker that decided the tool call would take longer than its inline-stream budget, so it returned `202 Accepted` with an empty body and a `Mcp-Session-Id` echo. Internally, however, the worker had *already* registered the request against the session's event log and advanced the session's `last_delivered_event_id` from 412 to 419 (the events queued between the drop and the reconnect). Those events — 413 through 419 — were written to the session log but never delivered to any open stream, because the `POST` had no stream body and the client's subsequent `GET` (issued after the `202`) carried `Last-Event-ID: 412` again but the server's replay logic keyed off `last_delivered_event_id = 419`, so it replayed from 420 onward. Events 413–419 were lost, including the `notifications/progress` and the terminal `notifications/cancelled` for a prior call. The client saw a `tools/call` that never resolved and never received its cancellation notice; the server believed it had delivered them. ## Condition of Validity This failure requires the conjunction of four conditions; remove any one and it does not occur: 1. The server advances its session-level replay watermark on *request receipt* rather than on *successful event-stream establishment* (i.e., watermark update is not gated on the response being `200` with a stream body). 2. The server is permitted to return `202` on a `POST` that carried `Last-Event-ID` — i.e., it does not reject or ignore the header on non-streaming responses. 3. The client re-issues resumption (`Last-Event-ID`) on a fresh `GET` *after* the `202`, rather than treating the `202`'s session as already-resumed and relying on the server to have buffered the gap. 4. There exists a gap of undelivered events between the old `Last-Event-ID` and the moment of the `202` decision. Condition 1 is the root cause; conditions 2–4 are the enabling surface. A server that only advances the watermark when it begins writing SSE frames to a `200` response is immune, because the `202` path never touches the watermark and the subsequent `GET` with `Last-Event-ID: 412` replays 413–419 correctly. ## Decision Boundary The correct rule is a single-sentence invariant to enforce on both sides: > **A `202 Accepted` response MUST NOT consume, advance, or otherwise mutate the session's event-replay cursor, and a client MUST treat `Last-Event-ID` on a `202`'d request as unconsumed and re-present the same cursor on the next stream-establishing exchange.** Operationally this means: - Server: compute the `202`-vs-`200` decision *before* touching any per-session replay state. If you must register the inbound request, do so against a separate "in-flight" ledger keyed by request ID, not the delivered-events watermark. Only advance the watermark inside the code path that has committed to writing `200` + `text/event-stream` and has begun flushing frames. - Server: if you cannot guarantee the above (e.g., a shared worker pool where the routing decision is made after enqueueing), then reject `Last-Event-ID` on any request you might answer `202` and require the client to resume exclusively via `GET`. Returning `400` with a clear error is safer than a silent gap. - Client: after a `202`, do not assume resumption succeeded. Open (or re-open) the `GET` stream with the *same* `Last-Event-ID` you sent on the `POST`. Treat the `202` as "message accepted, cursor unchanged." - Client: never advance your local `Last-Event-ID` based on a `202`; only advance it on receipt of an event with an `id:` field on an actual SSE stream. The boundary is sharp: the moment a server writes a `202` status line, it has forfeited the right to have consumed the client's resumption cursor. ## Operational Effect When this invariant is violated the failure is *silent and asymmetric*: the server's metrics show events delivered (they were written to the log and the watermark advanced), the client's metrics show a hung request, and neither side logs an error. The gap is only detectable by comparing the client's last-seen event ID against the server's watermark for that session — a cross-system reconciliation that most deployments do not perform. In practice this manifests as intermittently "stuck" long-running tool calls, missing cancellation notifications after reconnect, and progress bars that freeze at 99% across a load-balancer timeout. Because it requires a reconnect *and* a slow-tool `202` *and* queued events in the gap, it reproduces at low frequency under normal load and at high frequency during deploys and LB rotations — precisely when operators are least able to attribute it to a transport bug rather than the deploy itself. The mitigation with the best cost/benefit is server-side: gate all replay-watermark mutation behind the `200`-with-stream commit, and make `202` a pure no-op on session state. Client-side re-presentation of the cursor on `GET` is a necessary belt-and-suspenders but cannot recover events the server already marked delivered. ```python from __future__ import annotations from dataclasses import dataclass, field class ResumptionCursorConsumedError(RuntimeError): """Raised when a 202 Accepted response has advanced the session replay watermark, violating the invariant that a non-streaming response must not consume the client's Last-Event-ID cursor.""" @dataclass class SessionReplayState: session_id: str last_delivered_event_id: int # Events written to the log but not yet confirmed delivered on a stream. pending: dict[int, str] = field(default_factory=dict) def advance_on_stream_commit(self, event_id: int) -> None: # Legal: only called once a 200 + text/event-stream body is committed. if event_id <= self.last_delivered_event_id: raise ResumptionCursorConsumedError( f"event {event_id} <= watermark {self.last_delivered_event_id}" ) self.last_delivered_event_id = event_id self.pending.pop(event_id, None) def decide_response( state: SessionReplayState, client_last_event_id: int | None, will_stream_inline: bool, ) -> str: """Return '200-stream' or '202-accepted' and enforce the invariant. A 202 must not touch state.last_delivered_event_id. If the caller has already advanced the watermark before this decision, we detect and raise. """ if client_last_event_id is not None and not will_stream_inline: # We are about to return 202. The cursor must be untouched. if state.last_delivered_event_id != client_last_event_id: raise ResumptionCursorConsumedError( "202 path would consume Last-Event-ID: " f"client={client_last_event_id} " f"server_watermark={state.last_delivered_event_id} " f"session={state.session_id}" ) return "202-accepted" if will_stream_inline: # Commit to a stream, then (and only then) advance the watermark. if client_last_event_id is not None: for eid in sorted(state.pending): if eid > client_last_event_id: state.advance_on_stream_commit(eid) return "200-stream" return "202-accepted" # --- Correct usage --------------------------------------------------------- state = SessionReplayState(session_id="7f3c", last_delivered_event_id=412) state.pending = {413: "progress", 414: "progress", 419: "cancelled"} # Slow tool -> 202. Cursor stays at 412; client must re-present it on GET. assert decide_response(state, 412, will_stream_inline=False) == "202-accepted" assert state.last_delivered_event_id == 412 # invariant held # --- Violation detection --------------------------------------------------- # A buggy worker advanced the watermark before deciding to return 202: state.last_delivered_event_id = 419 try: decide_response(state, 412, will_stream_inline=False) except ResumptionCursorConsumedError as exc: # This is the silent-gap bug surfacing loudly at the boundary. print(f"detected: {exc}") ```