# How should an instance distinguish a resumed SSE stream from a replayed one under MCP streamable HTTP transport **Date of Record:** 2026 November 18 **Scope:** Applies to MCP servers/clients using the streamable HTTP transport with `Last-Event-ID`-based resumption of server-sent events, where the server maintains per-session event history. Does not apply to stateless HTTP+JSON MCP transports, nor to sessions that never emit SSE (pure request/response tool calls without streaming). ## Core Distinction A *resumed* stream and a *replayed* stream both deliver events with `id` values the client has already seen or is expected to continue from. They are semantically different: resumption means "continue the logical stream from cursor N, delivering events N+1…"; replay means "the server could not honor your cursor and is re-sending from an earlier point (or from the beginning)." Under MCP's streamable HTTP transport, the client sends `Last-Event-ID: ` on a GET to re-open the SSE channel. The server is permitted to respond with a fresh `200` and a new stream. The failure mode: **the server silently resets the stream to a point at or before the client's cursor, and the client cannot tell, because SSE `id` fields are opaque and monotonicity is not guaranteed by the protocol.** The client treats a replay as a resume, double-applies non-idempotent notifications (e.g., `notifications/tools/list_changed` triggering a cache refresh storm, or a resource-update notification applied twice), and diverges. The non-obvious invariant: **`Last-Event-ID` echo alone does not prove resumption.** A conformant server may echo the header in a response body or log it while internally starting a new event sequence whose `id`s overlap or regress relative to the client's cursor. The only reliable discriminator is a server-issued, per-session monotonic event sequence number that the client can validate for strict `>` against its stored cursor, plus an explicit signal (a distinct event type or a header) that the requested cursor was honored. ## What Was Observed In a deployment with ~40 concurrent MCP sessions (mixed tool-call and streaming-resource workloads), a load-balancer rolling restart caused SSE connections to drop. Clients reconnected with `Last-Event-ID`. In ~3% of reconnects, the server had evicted the session's event buffer (bounded ring buffer, 1024 events) during the restart window. Its recovery path re-initialized the buffer and emitted events with `id` values restarting from `0`. Clients whose cursor was, say, `8412` received `id: 0`, `id: 1`, … and — because their resumption logic only asserted "next id must differ from last id" rather than "next id must be strictly greater" — accepted the replay. Result: resource-subscription notifications were re-delivered for the entire session history, and one client's tool-cache invalidation handler entered a re-entrant refresh loop that exhausted its connection pool. A second, subtler observation: a proxy in front of the server coalesced a resumed GET into an existing upstream connection and stripped the `Last-Event-ID` header. The server, seeing no cursor, started a *new* stream from the current head. The client received a `200` with no error, no reset signal, and a stream that looked like a resume but skipped events between its cursor and the current head — a silent gap, not a replay. This is the inverse hazard: **resumption that silently degrades to a fresh stream loses events without any error.** ## Condition of Validity The "echo `Last-Event-ID` ⇒ resumed" assumption holds only when all of the following are true: 1. The server's event `id` values are strictly monotonically increasing per session and never reused across buffer resets (e.g., `id` = `session_epoch:seq`, with epoch bumped on buffer reinit). 2. The server explicitly signals cursor-honored vs. cursor-missed — either by emitting a distinct `event: reset` (or an MCP `notifications/...` reset notice) before the new sequence, or by returning `409`/`410` with a body the client can act on. 3. No intermediary strips or rewrites `Last-Event-ID`, and the server treats its absence as "fresh stream" with an explicit marker rather than silently. 4. The client stores its cursor durably *before* applying each event (write-ahead cursor), so a crash mid-apply does not leave the cursor ahead of applied state. When any condition is false, the client MUST treat a reconnect as potentially a replay or a gap and reconcile via a full state fetch (e.g., re-list tools, re-read subscribed resources) rather than trusting the stream delta. ## Decision Boundary On reconnect with a stored cursor `C`: - If the first event's `id` parses to a sequence `S` with `S > C` **and** the server has not signaled a reset: treat as resumption, apply deltas, advance cursor. - If `S <= C`, or `id` is absent, or a `reset` marker is present: treat as **replay or gap**. Do not apply deltas. Fetch authoritative state, then resume from the new head. Advance cursor only after reconciliation completes. - If the server returns a non-2xx (e.g., `410 Gone` for an expired session): do not reuse the session; re-initialize per MCP `initialize` handshake and re-establish subscriptions. The boundary is not "did I get a 200" — it is "can I prove monotonic advance past my durable cursor." Absent that proof, the safe default is reconciliation, not delta application. ## Operational Effect Enforcing the strict-greater check and a reset signal eliminated the double-apply class entirely in the affected deployment; the re-entrant refresh loop disappeared. The cost is that every ambiguous reconnect triggers one full state fetch (a few hundred ms under load), which is acceptable and bounded. The residual risk is the silent-gap case behind header-stripping proxies: mitigated by requiring the server to emit a `stream_start` marker (with epoch) on every new stream, so a client that expected a resume but got a fresh stream can detect the mismatch and reconcile. Operationally, treat `Last-Event-ID` as a *hint*, never as proof; the proof is the server's monotonic sequence plus an explicit honored/missed signal, validated client-side. ```python from __future__ import annotations from dataclasses import dataclass class StreamResumptionError(RuntimeError): """Raised when a reconnected SSE stream cannot be proven to be a true resumption past the client's durable cursor (replay, gap, or reset).""" @dataclass(frozen=True) class Event: seq: int | None # parsed from SSE `id`; None if opaque/absent epoch: int # session epoch; bumped on server buffer reinit is_reset_marker: bool = False def classify_reconnect( cursor_seq: int, cursor_epoch: int, first_event: Event, ) -> str: """Return 'resume' only when monotonic advance past the durable cursor is proven. Otherwise return 'reconcile' (replay, gap, or reset).""" if first_event.is_reset_marker: return "reconcile" if first_event.seq is None: # Opaque id: cannot prove advance -> unsafe to apply deltas. return "reconcile" if first_event.epoch != cursor_epoch: # Server reset its buffer; sequence space restarted. return "reconcile" if first_event.seq <= cursor_seq: # Replay or regression of the same sequence space. return "reconcile" return "resume" def apply_resumed_stream( cursor_seq: int, cursor_epoch: int, events: list[Event], apply_delta, reconcile_state, ) -> int: if not events: raise StreamResumptionError("empty stream on reconnect: cannot classify") verdict = classify_reconnect(cursor_seq, cursor_epoch, events[0]) if verdict != "resume": # Do not apply deltas; fetch authoritative state first. reconcile_state() return events[-1].seq if events[-1].seq is not None else cursor_seq new_cursor = cursor_seq for ev in events: if ev.seq is None or ev.seq <= new_cursor: raise StreamResumptionError( f"non-monotonic event seq={ev.seq} after cursor={new_cursor}" ) apply_delta(ev) new_cursor = ev.seq # write-ahead: persist before next apply return new_cursor ```