# Which invariants prevent silent event loss when an MCP streamable HTTP session migrates from SSE to POST mid-stream **Date of Record:** 2026 November 16 **Scope:** Applies to MCP servers and clients using the HTTP-native streamable transport where a single logical session spans an initial `GET` (SSE event stream) and subsequent `POST` requests resuming that session via `Last-Event-ID`. Does not apply to the legacy two-endpoint SSE transport, nor to sessions that never resume after disconnection. ## Core Distinction The streamable HTTP transport conflates two orthogonal concerns: *transport channel* (GET-held SSE vs. POST-response SSE) and *event continuity* (the monotonically ordered event ID space). A resumption is correct only if the client's `Last-Event-ID` is interpreted against the *same* event log that produced it, regardless of which HTTP method currently carries events. The failure mode is not "the client reconnected to the wrong URL" — it is "the server accepted a resume token and replayed from a position that the new channel never held." The invariant that matters is **event-ID monotonicity across channel boundaries**, not connection identity. ## What Was Observed A client opened a `GET /mcp` stream and received events `e1..e7` (IDs `1..7`). The connection dropped after `e7`. The client resumed by issuing `POST /mcp` with `Last-Event-ID: 7` and a new JSON-RPC request. The server, treating the POST as a fresh request scope, initialized a *new* event counter at `1` for the POST-response SSE stream. The client accepted the POST response body as a continuation and appended the new `e1..e3` (IDs `1..3`) to its local log. Result: the client's event-ID space now reads `1..7,1,2,3`. Any later resume with `Last-Event-ID: 3` is ambiguous — the server cannot distinguish "resume from the original e3" from "resume from the post-migration e3," and replays the wrong suffix. Events `e8..eN` that the server had actually emitted between the drop and the POST were never delivered and never acknowledged. A second, subtler variant: the server *did* honor `Last-Event-ID: 7` but replayed `e8..e12` as a *batch preamble* inside the POST response body before the response to the new request. Clients that parse the POST body as a single JSON-RPC response (not as an SSE stream) silently discarded the preamble and lost `e8..e12` while still considering the session healthy. ## Condition of Validity Resumption is valid only when all of the following hold: 1. The event-ID space is **session-scoped and globally monotonic**, independent of HTTP method. Event IDs are never reset by a channel switch. 2. The server persists emitted events (or a replay cursor) for the session's retention window, and `Last-Event-ID` is resolved against that persisted log — not against a per-request counter. 3. The client treats the POST response body as an SSE stream *when and only when* the server signals it will carry events (e.g., `Content-Type: text/event-stream`), and treats replayed preamble events as authoritative, not as response noise. 4. The client rejects any received event whose ID is not strictly greater than its current high-water mark for that session, treating a regression as a protocol violation rather than a new epoch. ## Decision Boundary - **If** the server cannot guarantee a session-scoped monotonic ID space across GET and POST, **then** it must not accept `Last-Event-ID` on a POST and must instead return an explicit resumption failure (forcing a full re-initialize). Silent acceptance is the bug. - **If** the POST response is `application/json`, **then** no events may be assumed delivered; the client must re-open a GET to resume the stream, and must not mark the session as caught-up. - **If** a client observes a non-increasing event ID, **then** it must halt the session and surface a protocol error, never merge the stream. Merging is what converts a detectable server bug into undetectable data loss. - **If** the retention window has elapsed, **then** the correct response is an explicit "resume impossible" signal, not a replay-from-zero. ## Operational Effect The practical consequence is that "successful reconnect" is not evidence of "no event loss." Health checks that assert only HTTP 200 on the POST will pass while events `e8..eN` are permanently lost. The only reliable detector is a client-side high-water-mark assertion on every event ID plus a server-side persisted replay log keyed by session, not by connection. Deployments that added POST-resume without a session-scoped event log experienced exactly this: zero error rate, zero failed reconnects, and a steadily widening gap between server-emitted and client-observed event counts that was invisible until a stateful tool call diverged. ```python class EventContinuityViolation(RuntimeError): """Raised when a resumed MCP stream regresses or skips event IDs.""" pass class SessionEventLog: def __init__(self, session_id: str): self.session_id = session_id self.events: list[tuple[int, dict]] = [] self._next_id = 1 def emit(self, payload: dict) -> int: event_id = self._next_id self._next_id += 1 self.events.append((event_id, payload)) return event_id def replay_after(self, last_event_id: int) -> list[tuple[int, dict]]: if last_event_id >= self._next_id: raise EventContinuityViolation( f"session {self.session_id}: Last-Event-ID {last_event_id} " f"exceeds high-water mark {self._next_id - 1}" ) return [(eid, p) for (eid, p) in self.events if eid > last_event_id] class ResumingClient: def __init__(self, session_id: str): self.session_id = session_id self.high_water = 0 def accept_event(self, event_id: int) -> None: if event_id <= self.high_water: raise EventContinuityViolation( f"session {self.session_id}: event ID {event_id} regressed " f"below high-water mark {self.high_water}; channel switch " f"reset the ID space — refusing to merge" ) if event_id != self.high_water + 1: raise EventContinuityViolation( f"session {self.session_id}: gap detected between " f"{self.high_water} and {event_id}" ) self.high_water = event_id def resume_over_post(log: SessionEventLog, client: ResumingClient) -> list[dict]: # Server must resolve Last-Event-ID against the session log, not a # per-request counter, or the client will observe a regression. replayed = log.replay_after(client.high_water) delivered = [] for event_id, payload in replayed: client.accept_event(event_id) delivered.append(payload) return delivered ```