# How should an instance distinguish resumable MCP stream state from replayable event log state under HTTP-native bidirectional transport **Date of Record:** 2026 November 15 **Scope:** Applies to MCP servers and clients using the HTTP-native transport (POST for client→server messages, GET with `text/event-stream` for server→client streaming, `Mcp-Session-Id` header for session identity) where the client may resume a dropped SSE stream via `Last-Event-ID`. Does not apply to stdio transport, nor to servers that hold no per-session state and treat every request as fully independent. ## Core Distinction There are two things an MCP HTTP-native server is tempted to conflate under the single label "session state": 1. **Transport stream state** — the position of a particular SSE connection in the sequence of server-to-client events, identified by `Last-Event-ID`. This is a *resumable cursor* over a byte stream. Its correctness requirement is only: given event id *N*, the server can produce every event with id > *N* that was emitted on that stream. 2. **Protocol session state** — the negotiated capabilities, the initialized lifecycle flag, and any server-side context that logically belongs to the `Mcp-Session-Id` (e.g., subscriptions, in-flight sampling requests awaiting a client response, resource watches). This is *identity* state. Its correctness requirement is: any request bearing this session id is interpreted against the same logical context, regardless of which TCP connection carries it. The non-obvious invariant is that **resumption must restore stream state without requiring session state to be resident**. A server that keeps a resumable event log keyed by `Last-Event-ID` but has evicted the session record will happily replay events into a context that no longer exists — and it will look correct because the bytes flow. Conversely, a server that keeps the session record but has discarded the event log will accept a `Last-Event-ID` it cannot honor and silently drop events, violating at-least-once delivery of notifications. ## What Was Observed In a deployment serving long-lived tool-use sessions over HTTP-native transport, the following sequence recurred under load-shedding: - A client opened a GET SSE stream, received events `1..40`, and the stream was severed by a mid-tier proxy idle timeout at 30s. - The server's per-session event ring buffer (capacity 64) was keyed by session id, not by stream id. A second concurrent GET from the same client (a legitimate reconnect race, since the client's old connection had not yet been reaped by the OS) attached to the *same* buffer and consumed events `35..40` a second time. The client, correctly honoring `Last-Event-ID: 34`, had already processed them. - Separately, when the session record was evicted by an LRU at 5 minutes of no client→server POSTs, a subsequent GET with `Last-Event-ID: 40` was accepted by the transport layer (which only checked that *some* buffer existed) but the buffer had been cleared with the session. The server responded `200` with an empty stream. The client interpreted an empty stream on a resume as "no new events" and waited indefinitely for a `tools/call` result that had been emitted as event `41` and lost. The first failure is a **duplicate delivery** bug; the second is a **silent loss** bug. Both stem from the same conflation: the event log's lifetime was tied to the session record's lifetime, and its identity was tied to the session id rather than to the stream. ## Condition of Validity The distinction holds — i.e., stream state and session state must be separated — under these conditions: - The transport permits **more than one concurrent GET stream** per `Mcp-Session-Id`. The spec does not forbid this, and reconnect races produce it routinely. If the server serializes GETs per session (rejecting the second with `409`), a single shared buffer is defensible. - Events carry **monotonically increasing, per-stream ids**. If ids are per-session instead of per-stream, a resumed stream cannot distinguish "already seen on this stream" from "seen on a sibling stream," and `Last-Event-ID` becomes ambiguous. - The server offers **at-least-once** delivery of server→client notifications across resumption. If the contract were at-most-once, silent loss on resume would be acceptable and the invariant would not bind. When any of these fails — single-stream-per-session enforcement, session-scoped event ids, or at-most-once semantics — the two states may be coalesced, and the failure modes above do not arise (they are replaced by different ones, notably head-of-line blocking on the single stream). ## Decision Boundary The operational rule an agent should apply: - **If a GET arrives with `Last-Event-ID` and the referenced stream's log is still within its retention window** → resume from that id on *that stream's* log; do not consult the session record to decide whether to resume. Session liveness is irrelevant to whether the bytes for events > N still exist. - **If the stream log has been evicted but the session is alive** → respond with an explicit, machine-readable resumption failure (a `404` on the stream endpoint, or an SSE `event: error` with a `resumption_failed` reason) rather than an empty `200`. An empty `200` is indistinguishable from "no new events" and is the direct cause of the silent-loss incident. - **If the session has been evicted but the stream log survives** → treat the resume as a *replay-only* stream: deliver the buffered events, then close with a `session_expired` terminal event. Do not attempt to service new requests against the dead session. - **If both are gone** → `404` with `session_expired`; the client must re-initialize. The boundary is: **the event log's retention is a function of stream age and buffer pressure; the session record's retention is a function of client activity. These two clocks are independent, and the code must not assume one implies the other.** ## Operational Effect Separating the two states changes the failure surface in three concrete ways: 1. **Duplicate delivery becomes detectable.** With per-stream logs, a reconnect race produces two logs, each with its own id sequence; the client's `Last-Event-ID` unambiguously selects one. The server can assert id monotonicity per stream and raise when a resume id exceeds the log head for that stream (indicating the client saw events the server never emitted — a corruption signal, not a normal condition). 2. **Silent loss becomes loud.** The empty-`200`-on-resume path is eliminated by requiring an explicit terminal event or non-2xx status when the log cannot honor the cursor. Clients can then distinguish "caught up" from "cannot catch up." 3. **Eviction policy decouples.** The LRU on sessions and the ring buffer on streams can be sized and evicted on independent schedules, so a burst of short tool calls (high session churn, low stream duration) no longer evicts the event logs of long-lived streaming sessions, and vice versa. The residual risk is the replay-only window: a client resuming against a live log but a dead session will receive events it cannot act on (e.g., a `sampling/createMessage` request whose response channel is gone). The server must tag replayed events with the session-epoch at which they were emitted, so the client can drop requests belonging to a prior epoch rather than answering them into a dead session. ``` ```python class StreamResumptionError(RuntimeError): """Raised when a Last-Event-ID cursor cannot be honored on its stream log.""" pass class SessionEpochMismatch(RuntimeError): """Raised when a replayed event belongs to an evicted session epoch.""" pass def resume_stream(stream_log, session_record, last_event_id, session_epoch): """ Resume an SSE stream for an MCP HTTP-native transport. stream_log: per-stream ring buffer of (event_id, session_epoch, payload), keyed by stream id, NOT by session id. session_record: current session state, or None if evicted. last_event_id: value of the client's Last-Event-ID header. session_epoch: epoch the client believes it is on. """ if stream_log is None: # No log for this stream at all: cannot honor the cursor. raise StreamResumptionError( f"no event log for stream; cannot resume from id={last_event_id}" ) head = stream_log.head_id() if last_event_id is not None and last_event_id > head: # Client claims to have seen an event the server never emitted. raise StreamResumptionError( f"resume cursor {last_event_id} exceeds stream head {head}; " "log corruption or cross-stream id collision" ) pending = stream_log.events_after(last_event_id) if last_event_id is not None and not pending and stream_log.was_truncated_after(last_event_id): # Log was trimmed past the cursor: explicit failure, never empty 200. raise StreamResumptionError( f"cursor {last_event_id} evicted from log (oldest retained " f"{stream_log.oldest_id()}); client must re-initialize" ) if session_record is None: # Replay-only: session gone, log survives. Deliver then terminate. for ev in pending: if ev.session_epoch != session_epoch: raise SessionEpochMismatch( f"event {ev.event_id} from epoch {ev.session_epoch}, " f"client on epoch {session_epoch}; drop, do not answer" ) return {"mode": "replay_only", "events": pending, "terminal": "session_expired"} return {"mode": "live", "events": pending, "terminal": None} ``` ```