# When must an instance refuse to resume an MCP SSE session after a streamable-HTTP upgrade: the Last-Event-ID replay gap across transport migration **Date of Record:** 2026 November 16 **Scope:** Applies to MCP servers and clients that expose the same logical session over both the legacy HTTP+SSE transport and the newer streamable-HTTP transport, where a client may reconnect via `Last-Event-ID` after a transport switch. Does not apply to pure stdio sessions or to single-transport deployments where no migration occurs mid-session. ## Core Distinction The distinction that matters is between **event continuity** and **event replayability**. A streamable-HTTP server can keep a monotonically increasing event ID sequence across a transport upgrade and still be unable to replay the events emitted before the upgrade, because the pre-upgrade events were written to a per-connection SSE buffer that is destroyed when the legacy connection closes. The ID sequence is a *logical* invariant; the replay buffer is a *physical* resource. Clients and orchestrators routinely conflate the two: they see a valid `Last-Event-ID` that is numerically contiguous with the server's current counter and conclude the session is resumable. It is not. The correct behavior is for the server to reject the resume with an explicit, typed error rather than silently resume from an empty buffer and produce a stream that looks continuous but has a hole. ## What Was Observed In a deployment where an MCP server fronted a long-running tool-call session, a client connected over legacy HTTP+SSE, received events with IDs `1000..1042`, then was instructed (via a `Mcp-Session-Id` re-negotiation after a load-balancer rollout) to reconnect using streamable HTTP with `Last-Event-ID: 1042`. The server accepted the connection, returned `200` with `text/event-stream`, and emitted events `1043..`. The client's event log showed no gap. However, events `1035..1042` had contained the final chunked arguments of a `tools/call` and the server's `notifications/progress` for a long operation; those had been delivered on the legacy connection but the client's *application-level* consumer had not yet durably acknowledged them (it was mid-write to a downstream queue). On reconnect the client assumed it had everything up to `1042` because the server resumed at `1043`. The downstream queue received a tool call with truncated arguments. The failure was silent: no error, no gap in the ID sequence, no log line indicating loss. The root cause: the legacy SSE transport's event store was a bounded in-memory ring buffer scoped to the connection; the streamable-HTTP transport used a separate, freshly initialized replay store. The session ID was preserved; the replay state was not. The server's resume logic checked only `Last-Event-ID <= current_counter` and never checked whether the referenced event was actually present in the *current* transport's replay store. ## Condition of Validity Resumption via `Last-Event-ID` is valid only when all of the following hold: 1. The event identified by `Last-Event-ID` is physically present in the replay store backing the transport that will serve the resumed stream, not merely numerically less than the current counter. 2. The transport generation that produced the event is the same generation (or a generation that shares a durable, shared replay store) as the one serving the resume. 3. The client's acknowledgment boundary — the highest event ID it has *durably* processed, not merely received — is at or below the `Last-Event-ID` it sends. If any condition fails, resume must be refused. Condition 2 is the one that breaks during transport migration, and it is the one that is invisible to ID-sequence checks. ## Decision Boundary The server must branch on **replay-store membership**, not on counter comparison: - If `Last-Event-ID` is absent: start a fresh stream at the current counter. Valid. - If `Last-Event-ID` is present and the event is in the current replay store: resume from the next event. Valid. - If `Last-Event-ID` is present, is numerically ≤ current counter, but is **not** in the current replay store (because it predates a transport migration or was evicted): **refuse**. Return a typed error indicating the resume point is unreplayable, and require the client to re-establish session state from a snapshot or restart the logical operation. Do not resume at the current counter and pretend continuity. - If `Last-Event-ID` is greater than the current counter: refuse as a protocol violation (client is ahead of the server, indicating a split-brain or a stale session ID reuse). The non-obvious part: the third case is the one that silently corrupts. The server's counter is monotonic across migration, so the check `1042 <= 1043` passes and the naive implementation resumes. The correct implementation must additionally verify that event `1042` exists in the *new* store. If the store was reinitialized at migration, it does not, and the resume must fail loudly. ## Operational Effect When the boundary is enforced, transport migration becomes a visible event: clients that were mid-stream receive a `ResumePointUnreplayable` error and are forced to reconcile (re-fetch a session snapshot, re-issue the in-flight tool call with idempotency keys, or surface the failure to the orchestrator). This is the correct trade: a loud, typed failure at migration is strictly better than a silent hole in a tool-call argument stream. When the boundary is not enforced, the failure mode is partial event delivery that is undetectable from the client's ID-sequence view, which is the worst class of distributed-systems bug — it looks like success. The operational rule: **a transport upgrade that does not carry its replay store forward invalidates all outstanding `Last-Event-ID` resume points, regardless of counter continuity.** Servers must treat the replay store as part of the session's durable state or explicitly refuse cross-generation resumes. ```python class ResumePointUnreplayable(RuntimeError): """Raised when a Last-Event-ID cannot be served from the current replay store. Distinct from a generic protocol error: the client's ID is numerically valid (<= current counter) but the referenced event is not physically present in the store backing the transport that would serve the resumed stream. This typically occurs after a legacy-SSE -> streamable-HTTP migration where the per-connection SSE buffer was discarded but the event counter was preserved. """ pass def resume_stream(session, last_event_id, current_store): """Decide whether to resume an MCP stream at last_event_id. Returns the next event ID to emit. Raises ResumePointUnreplayable if the resume point exists in the counter but not in the current replay store. """ if last_event_id is None: return session.counter.current + 1 if last_event_id > session.counter.current: raise ResumePointUnreplayable( f"Last-Event-ID {last_event_id} is ahead of server counter " f"{session.counter.current}; stale session or split-brain." ) if not current_store.contains(last_event_id): # Counter continuity is NOT replayability. The event predates the # current transport generation's store (e.g., discarded SSE buffer # from before a streamable-HTTP upgrade). Refuse rather than resume # from an empty buffer and emit a silently holed stream. raise ResumePointUnreplayable( f"Last-Event-ID {last_event_id} is <= counter " f"{session.counter.current} but absent from the current replay " f"store (transport generation {current_store.generation}); " f"resume would drop events. Client must reconcile from snapshot." ) return last_event_id + 1 ```