# Why does an instance lose MCP stream resumption when the transport applies backpressure mid-chunk **Date of Record:** 2026 November 15 **Scope:** Applies to MCP servers using the HTTP-native (Streamable HTTP) transport with SSE-style streaming, `Last-Event-ID` resumption, and per-session backpressure. Does not apply to stdio transport, nor to stateless HTTP request/response mode where no session is bound. ## Core Distinction The failure is not "the stream dropped." It is the distinction between **event identity** and **event durability**. The MCP transport assigns an event ID (`id:` field on each SSE frame) at the moment the frame is *serialized into the write buffer*, but the server only guarantees resumption from an event ID if the corresponding frame was *fully flushed to the socket and acknowledged as durable in the session's replay log*. Under backpressure, these two moments diverge. A client that receives `id: 42` and then disconnects will, on reconnect, send `Last-Event-ID: 42`. If the server's replay log committed event 42 but the *next* event (43) was partially written and then discarded by the transport's buffer-full eviction, the server resumes at 43 — but the client never saw the tail of 42's payload. The event ID is monotonic; the payload is not atomic with it. This is the non-obvious boundary: **resumption is keyed on the last *assigned* ID, not the last *fully delivered* ID.** ## What Was Observed In a deployment streaming tool-call progress notifications over Streamable HTTP, a downstream consumer applied TCP-level backpressure (slow reader, ~2 KB/s) while the server produced ~40 KB/s of `notifications/progress` frames. The transport's per-session write buffer had a high-water mark of 64 KB. When the buffer filled: 1. The server continued assigning event IDs to frames as they entered the buffer (IDs 1180–1211 were assigned within one 250 ms window). 2. The buffer's eviction policy dropped the *oldest unsent* frames to make room, but the session's replay log had already committed IDs up to 1211 because the log commit happened at assignment time, not at flush time. 3. The client's connection reset. On reconnect it sent `Last-Event-ID: 1179` (the last frame it had *fully* parsed). 4. The server resumed at 1180 from the replay log — correct — but the replay log's entries for 1180–1211 were *truncated stubs* (the payload had been evicted), so the server emitted `id: 1180` with an empty `data:` field and advanced. 5. The client parsed a sequence of empty-data events, treated them as valid (MCP does not require non-empty data per frame), and the tool call's progress state silently desynchronized from the server's actual state. The observable symptom was not an error. It was a progress notification stream that *appeared* to resume cleanly while carrying no payload — a silent gap. Downstream, the agent's tool-call timeout logic never fired because progress events kept arriving. ## Condition of Validity Resumption is only sound when the following invariant holds: > For every event ID `N` present in the replay log, the full payload of event `N` is retrievable and byte-identical to what was originally assigned to `N`. This invariant is violated whenever the transport decouples *ID assignment* from *payload retention*. Concretely, it fails when: - The write buffer and the replay log are separate structures with independent eviction. - The replay log is bounded by count or bytes and evicts payload while retaining the ID watermark. - Backpressure causes the producer to outrun the consumer such that the replay log's retention window is shorter than the client's disconnect duration. It does *not* fail when the replay log is the single source of truth and frames are only assigned IDs at flush time (at-least-once delivery, IDs assigned post-flush), or when the server refuses to assign an ID until the frame is durably enqueued in a log that cannot evict unacked entries. ## Decision Boundary The operational decision is whether to **block the producer** or **drop with a gap marker** when the replay log cannot retain a frame's payload. - **Block the producer** (correct for stateful tool-call progress): apply backpressure all the way up to the MCP handler. The handler's `await` on the notification send must not resolve until the frame is durably logged. This bounds throughput to the slowest consumer but preserves the invariant. - **Drop with a gap marker** (correct for idempotent, order-independent telemetry): emit a synthetic `id: N` frame with a machine-readable `event: gap` payload carrying the dropped range `[a, b]`. The client must be able to re-request the range or treat the gap as a hard error. The failure mode above is what happens when neither is chosen: the server drops silently *and* keeps advancing IDs, which is the worst of both — no backpressure and no gap signal. The boundary condition to encode: **if `replay_log.bytes_retained < write_buffer.bytes_pending`, the transport MUST NOT assign IDs to pending frames.** Assign IDs only at flush. This makes resumption trivially correct because the replay log and the delivered set are the same set. ## Operational Effect After the fix (ID assignment moved to post-flush, replay log made authoritative and non-evicting for unacked entries), the observable behavior changed in three ways: 1. Slow consumers now slow the producer. Throughput to a 2 KB/s consumer dropped to 2 KB/s, and the MCP handler's progress `send` calls blocked correspondingly. Tool-call wall-clock time increased for slow consumers, which is the correct trade. 2. `Last-Event-ID` resumption became exact: reconnect at `N` replayed `N+1` onward with full payloads, byte-identical. 3. A new failure surfaced and was handled explicitly: when the replay log hit its hard cap (configured at 8 MB per session), the server now emits a terminal `event: overflow` frame and closes the session with a 409, forcing the client to re-initialize the session rather than silently desync. The lesson for agents operating this transport: never trust that a received `id:` implies the payload was complete, and never trust that a server's replay log is payload-complete just because it advanced its watermark. Verify by checksum or by requiring the server to echo the payload length in a header on resume. ```python import hashlib from dataclasses import dataclass class StreamResumptionInvariantError(RuntimeError): """Raised when an MCP stream resume would violate event payload durability.""" pass @dataclass(frozen=True) class ReplayEntry: event_id: int payload: bytes @property def digest(self) -> str: return hashlib.sha256(self.payload).hexdigest() class ReplayLog: """Authoritative, non-evicting-while-unacked replay log for one MCP session.""" def __init__(self, hard_cap_bytes: int) -> None: self._entries: dict[int, ReplayEntry] = {} self._watermark: int = 0 self._cap = hard_cap_bytes self._bytes = 0 def append_flushed(self, payload: bytes) -> ReplayEntry: # ID assigned ONLY after the frame is durably flushed. self._watermark += 1 entry = ReplayEntry(self._watermark, payload) if self._bytes + len(payload) > self._cap: raise StreamResumptionInvariantError( f"replay log cap {self._cap}B exceeded at event {entry.event_id}; " "emit event:overflow and close session" ) self._entries[entry.event_id] = entry self._bytes += len(payload) return entry def resume_from(self, last_event_id: int) -> list[ReplayEntry]: if last_event_id > self._watermark: raise StreamResumptionInvariantError( f"client claims Last-Event-ID {last_event_id} > watermark " f"{self._watermark}; client state is ahead of server, refuse resume" ) missing = [n for n in range(last_event_id + 1, self._watermark + 1) if n not in self._entries] if missing: # This is the exact bug class: watermark advanced, payload evicted. raise StreamResumptionInvariantError( f"watermark {self._watermark} advanced past retained payloads; " f"missing event ids {missing[:5]}... — invariant violated" ) return [self._entries[n] for n in range(last_event_id + 1, self._watermark + 1)] def handle_resume(log: ReplayLog, last_event_id: int, expected_digest: str | None) -> list[ReplayEntry]: entries = log.resume_from(last_event_id) if expected_digest is not None and entries: if entries[0].digest != expected_digest: raise StreamResumptionInvariantError( f"resume digest mismatch at event {entries[0].event_id}: " f"client expected {expected_digest}, server has {entries[0].digest}" ) return entries ```