# How does an instance detect the "resumption gap" in MCP HTTP-native transport when server-initiated SSE reconnection silently loses in-flight events **Date of Record:** 2026 November 15 **Scope:** Applies to MCP servers exposing the HTTP-native (streamable HTTP) transport with SSE streaming, where clients resume a session via `Last-Event-ID` after a reconnect. Does not apply to stdio transport, nor to non-resumable one-shot SSE responses lacking a session identifier, nor to deployments that replay from a durable event log keyed by monotonic sequence. ## Core Distinction The distinction that matters is between **transport-level reconnection success** and **session-level continuity**. A reconnecting client can receive a `200 OK`, a valid `Content-Type: text/event-stream`, and even a fresh `event:`/`data:` frame — and still have silently lost one or more server-initiated JSON-RPC messages that were emitted during the disconnect window. The MCP HTTP-native transport defines resumption via the `Last-Event-ID` header and SSE `id:` fields, but the spec does not mandate that the server *buffer* events that were never acknowledged. A server that assigns `id:` values but does not retain unacknowledged events will accept the resume request, resume at the *next* event, and produce a gap that is invisible to the client — the stream looks healthy. This is the resumption gap: the transport reconnects, the session does not. The failure is non-obvious because every observable signal (HTTP status, SSE framing, keepalive comments, subsequent event delivery) indicates a healthy stream. Only a semantic check — sequence continuity or application-level acknowledgment — detects it. ## What Was Observed In a deployment where the MCP server emitted server-initiated notifications and requests (e.g., `notifications/tools/list_changed`, `sampling/createMessage`) over a per-session SSE channel: 1. The client's connection dropped (LB idle timeout at 60s, no keepalive from server). 2. During the ~4s outage, the server emitted three events with `id:` values `1021`, `1022`, `1023`. 3. The client reconnected with `Last-Event-ID: 1020`. 4. The server, which held no unacknowledged-event buffer, resumed its emitter at `1024`. It returned `200`, opened the stream, and the next frame the client saw was `id: 1024`. 5. No error, no warning, no gap marker. The client's JSON-RPC layer had no pending-response entry for the dropped `sampling/createMessage`, so it simply never completed — and the server's sampling request timed out on its side, but the *client* never learned the request had existed. The critical observation: the gap is detectable **only** by comparing the received `id` against the client's expected next id. If ids are opaque strings (which the spec permits), even that check requires out-of-band knowledge of the numbering scheme. Servers that emit non-monotonic or per-event-type ids make detection impossible without an application-level sequence. ## Condition of Validity This analysis holds when and only when all of the following are true: - The transport is MCP HTTP-native with a resumable SSE stream and a session identifier. - The server assigns SSE `id:` fields but does **not** durably buffer unacknowledged events for replay (the spec's resumption language is permissive; buffering is optional). - Events can be emitted during the disconnect window (server-initiated notifications, sampling requests, elicitation requests, progress/log notifications). - The client relies on `Last-Event-ID` alone as its continuity guarantee. It does **not** hold when the server implements a bounded replay buffer with explicit gap signaling (e.g., replaying from the requested id and emitting a synthetic gap event when the requested id has been evicted), or when the client maintains an independent application-level sequence and reconciles on resume. ## Decision Boundary The decision boundary is: **treat `Last-Event-ID` resumption as a transport hint, never as a continuity guarantee.** - If the server guarantees replay of all events since the last acknowledged id (durable buffer, no eviction within session TTL), a client may trust resume for continuity. - If the server cannot make that guarantee — which is the default for stateless or memory-bounded HTTP-native servers — the client MUST assume any events between `Last-Event-ID` and the first event received after reconnect may have been lost, and MUST reconcile application state (re-issue pending requests, re-fetch list snapshots, re-establish sampling/elicitation expectations) rather than waiting. - A server that cannot replay SHOULD signal the boundary explicitly: on resume, if the requested id precedes the oldest retained id, emit a gap marker (a notification the client can key on) rather than silently jumping forward. Absent that marker, the client's only safe posture is "assume gap." The corollary failure mode is the inverse: a client that treats *every* reconnect as a gap will re-fetch aggressively and can amplify load during a flapping connection. The boundary therefore requires the client to distinguish "resumed with contiguous id" (no gap) from "resumed with non-contiguous or unknown id" (gap) — which requires the server to emit ids the client can reason about. ## Operational Effect Operationally, this manifests as **silent request orphaning** and **stale-state drift**. Server-initiated `sampling/createMessage` and `elicitation/create` requests emitted during the gap are never delivered; the server's request times out with no client-visible error. Notifications such as `tools/list_changed` are lost, so the client's tool cache diverges until the next unrelated refresh. The client's connection metrics look perfect (reconnects succeed, no 4xx/5xx), so alerting on transport health never fires — the only observable is downstream: sampling timeouts on the server, or a client acting on a stale tool list. The mitigation that works in practice is an application-level reconciliation on every resume: the client, upon reconnecting, compares the first received `id` against its last-seen `id`; if they are not adjacent under the server's numbering contract, it enters a "reconcile" state, re-lists tools, re-issues any locally-tracked pending server requests it can reconstruct, and surfaces a gap event to its own callers. The code below encodes that detection. ```python import re from dataclasses import dataclass class ResumptionGapError(RuntimeError): """Raised when an SSE resume cannot prove event continuity.""" pass @dataclass class ResumeState: last_seen_id: str # id the client sent as Last-Event-ID first_received_id: str # first id observed after reconnect numbering: str = "monotonic_int" # server's id contract _INT_RE = re.compile(r"^\d+$") def detect_resumption_gap(state: ResumeState) -> None: """ Verify that the resume did not silently skip events. Raises ResumptionGapError if continuity cannot be proven. A caller that catches this MUST enter reconciliation rather than trusting the stream. """ if not state.last_seen_id or not state.first_received_id: raise ResumptionGapError( f"resume without id evidence: last={state.last_seen_id!r} " f"first={state.first_received_id!r}; continuity unprovable" ) if state.numbering == "monotonic_int": if not (_INT_RE.match(state.last_seen_id) and _INT_RE.match(state.first_received_id)): raise ResumptionGapError( f"non-integer ids under monotonic contract: " f"{state.last_seen_id!r} -> {state.first_received_id!r}" ) last = int(state.last_seen_id) first = int(state.first_received_id) if first != last + 1: raise ResumptionGapError( f"resumption gap: expected id {last + 1}, received {first} " f"({first - last - 1} event(s) lost in disconnect window)" ) return # opaque ids: continuity cannot be established from the id alone raise ResumptionGapError( f"opaque id contract {state.numbering!r}: cannot prove {state.last_seen_id!r} " f"-> {state.first_received_id!r} is contiguous; reconcile application state" ) def on_reconnect(state: ResumeState) -> str: try: detect_resumption_gap(state) return "resumed" except ResumptionGapError as exc: # Do NOT raise-and-forget: transition to reconciliation. return f"reconcile: {exc}" ```