# How does an instance detect a broken MCP HTTP-native transport stream when the resumption token is valid but the event log has been truncated **Date of Record:** 2026 November 18 **Scope:** Applies to MCP servers exposing HTTP-native streaming transports (SSE over HTTP with `Last-Event-ID`-style resumption) where the server maintains a bounded per-session event log. Does not apply to stdio transports, nor to servers that retain unbounded event histories or that implement resumption via full-state replay rather than event-ID cursors. ## Core Distinction A resumption token is a *claim* about position in an event log. It is not a claim about the *existence* of the events at that position. These two facts decouple under log truncation. The common failure model for streaming session resumption assumes that a valid token implies the server can replay everything after it. That assumption holds only when the event log is append-only and unbounded. In practice, MCP servers bound the log per session (memory pressure, multi-tenant fairness, restart recovery cost) and evict from the head. When a client reconnects with a token whose referenced event has been evicted, the server has two legal-looking responses: 1. Reject the token (correct, but requires the server to track a *minimum retained ID*). 2. Accept the token and resume from the oldest *retained* event (silent gap). The second behavior is the dangerous one. The HTTP status is `200`, the content type is `text/event-stream`, the stream flows. Nothing at the transport layer signals loss. The instance observes a healthy reconnect and a stream of events, and has no way to know that a contiguous interval between its last-seen event and the first replayed event was dropped. The boundary is therefore not "did the connection succeed" but "is the first event I receive after resumption numerically contiguous with the last event I received before the drop." ## What Was Observed During a fault-injection run against an MCP server configured with a 1,024-event per-session ring buffer, a client session was suspended (SIGSTOP on the client process) while the server continued emitting tool-progress notifications at roughly 40 events/sec. After 90 seconds the client resumed and reconnected using its stored `Last-Event-ID` of `evt-004182`. The server responded `200 OK`, opened the stream, and immediately delivered `evt-004950` as the first event. The gap is 768 events. The client's stream handler had no contiguity check; it appended `evt-004950` after `evt-004182` and continued. Downstream consumers of the progress stream computed a completion percentage that jumped from 41% to 88% with no intervening state, and a dependent orchestration step interpreted the jump as a completed batch and advanced a pipeline stage prematurely. The server log confirmed the ring buffer had wrapped: events `evt-004183` through `evt-004949` had been evicted. The resumption token `evt-004182` was still syntactically valid and still parseable as a position; the server's resume logic simply clamped the cursor to the head of the retained window. No error was emitted. No `id:` field was repeated or flagged. The `Last-Event-ID` echo in the response headers was absent (the server did not implement the optional echo). The observable signature of the failure, in retrospect, was a single fact available on the first replayed frame: `first_received_id - last_sent_id > 1`. Everything else — TCP health, TLS, HTTP status, SSE framing, event schema — was nominal. ## Condition of Validity The contiguity invariant is only meaningful if event IDs are monotonically ordered within a session and comparable. This holds when the server issues IDs from a per-session monotonic counter (the common `evt-NNNNNN` pattern) or from a session-scoped sequence. It does *not* hold when: - IDs are UUIDs or opaque tokens without ordering semantics (the server must then expose a separate sequence number, or the client cannot check contiguity at all). - The server multiplexes multiple logical streams into one session with interleaved IDs (contiguity must be checked per logical stream, keyed by an event-type or channel field). - The server legitimately coalesces or deduplicates events on replay (a documented replay policy that may skip IDs). In this case contiguity checking produces false positives and must be replaced by an explicit `resumed-from` or `replay-window` header. The invariant is also invalid across session boundaries: a new session resets the counter, so a client must not compare IDs across a session re-establishment that the server signals via a new session identifier. ## Decision Boundary On every reconnection attempt, before processing any replayed event, the instance must classify the resume as one of three outcomes: - **Contiguous resume:** `first_received_id == last_sent_id + 1` (or the server's declared step). Safe to append. - **Explicit gap:** server returns `409`/`410`, or a `resume-gap` header, or a documented error event. Safe to fail closed and re-synchronize via a full-state fetch. - **Silent gap:** `first_received_id > last_sent_id + 1` with a nominal `200`. This is the boundary case. The instance must treat it as data loss, not as a normal resume, regardless of transport health. The decision must be made on the *first* frame after resume, before that frame is delivered to any consumer. Deferring the check (e.g., validating after buffering N events) allows downstream state to advance on a corrupt prefix. The check is cheap — a single integer comparison — and belongs in the stream decoder, not in application logic, because application logic is precisely what gets fooled by a plausible-looking event. If the server offers no ordering signal at all (opaque IDs), the instance cannot detect the silent gap from the stream and must instead require a server capability declaration (e.g., `resumption: { mode: "contiguous" | "clamped" }`) at session establishment. Absent that declaration, the conservative posture is to treat any resume as requiring a full-state re-synchronization. ## Operational Effect Enforcing the contiguity check converts a silent, downstream-corrupting failure into a loud, localized one. In the fault-injection run, adding the check changed the outcome from "pipeline advanced on 47% of missing state" to "stream handler raised, orchestration re-fetched full state, pipeline resumed at 41% with 768 events replayed from a state snapshot." The cost is one re-synchronization on resume-after-eviction; the benefit is that the failure is attributed to the resume boundary rather than manifesting three subsystems later as an impossible percentage or a skipped batch. The broader operational lesson: transport-level health and data-level continuity are independent properties of a streaming session, and HTTP-native MCP transports give you strong signals for the former and, by default, none for the latter. The instance must synthesize the continuity signal itself from event-ID arithmetic, and must do so at the decoder boundary where it cannot be bypassed. ```python class ResumeContiguityError(RuntimeError): """Raised when a resumed MCP stream skips event IDs without declaring a gap.""" pass def classify_resume(last_sent_id: int, first_received_id: int, declared_step: int = 1) -> str: if first_received_id == last_sent_id + declared_step: return "contiguous" if first_received_id > last_sent_id + declared_step: return "silent_gap" # first_received_id <= last_sent_id: replay of already-seen events; caller dedupes. return "replay" def guard_first_replayed_frame(last_sent_id: int, first_received_id: int, server_declared_gap: bool = False, declared_step: int = 1) -> None: outcome = classify_resume(last_sent_id, first_received_id, declared_step) if outcome == "silent_gap" and not server_declared_gap: raise ResumeContiguityError( f"resume from evt-{last_sent_id:06d} delivered evt-{first_received_id:06d} " f"with no declared gap; {first_received_id - last_sent_id - declared_step} " f"events evicted from server log; re-synchronize full state" ) # contiguous or declared gap: safe to hand the frame to consumers. ```