# When must an instance refuse to resume an MCP streamable HTTP session after a transport-level backpressure stall **Date of Record:** 2026 November 17 **Scope:** Applies to MCP servers and clients using the HTTP-native "streamable" transport (SSE-over-POST or long-poll chunked responses) where a session may be resumed after a transient connection drop, and where the server applies backpressure by withholding bytes on the response stream. Does not apply to stdio transport, to WebSocket transports, or to sessions explicitly terminated by `session/close` or by server-side authorization revocation. ## Core Distinction The distinction that matters is between **a stalled stream** and **a dead stream**. In streamable HTTP, backpressure is expressed by the server simply not writing to the response body: TCP receive windows fill, the client's read loop blocks, and no bytes flow. From the client's perspective this is indistinguishable, at the socket layer, from a peer that has crashed, been partitioned, or had its process frozen by the OS scheduler. The resumption logic in a naive implementation treats "no bytes received within timeout T" as a trigger to reconnect with `Last-Event-ID` and replay. This is the boundary failure: **backpressure and failure share the same wire signature**, and resuming during an intentional backpressure stall causes duplicate event delivery, replay storms, and — worse — session-state divergence when the server has already advanced its internal cursor past the client's last-acknowledged event. The invariant is this: a session may be resumed only when the server can prove the stream is *dead*, not merely *quiet*. Quietness under backpressure is a normal, expected, and often indefinite condition. Resumption is a state-reconciliation operation, not a liveness check. ## What Was Observed In a deployment where a streamable MCP server emitted tool-call progress notifications over an SSE response and a downstream consumer applied a bounded queue (depth ~256 events) with a 30-second idle read timeout on the client side, the following sequence reproduced reliably under load: 1. Consumer's queue filled; the server's `send()` blocked on a full TCP window. The server correctly stopped writing — this is the desired backpressure signal. 2. The client's idle timer fired at 30s. The client treated this as a stream failure, closed the connection, and reconnected with `Last-Event-ID: `. 3. The server, which had *not* closed the session and had *not* lost state, accepted the resume and replayed events from the last-seen ID — but the original blocked `send()` was still pending on the abandoned connection, and on timeout the server's own write-side cleanup re-queued those same events. 4. Result: every event in the stalled window was delivered twice (once on the new stream, once via the orphaned connection's cleanup path), and the client's dedup layer — keyed on event ID — silently dropped the *second* copy, which happened to be the one carrying the corrected payload after a tool retry. The client's view of the tool result diverged from the server's for the remainder of the session. The critical observation: the server had no way to distinguish "client went away" from "client is slow." Both manifest as a dropped write. The client had no way to distinguish "server is applying backpressure" from "server is dead." Both manifest as a read timeout. The resumption handshake assumed the latter interpretation on both sides. A second, subtler observation: when the server *did* have pending backpressure and the client resumed, the server's replay buffer had already been partially drained by the orphaned write path. Replay from `Last-Event-ID` returned a *gap* — events after the cursor that had been consumed by the dead connection were not re-sent, because the server's retention logic considered them "delivered" (they had been written to a socket, even if that socket was never read). The client resumed into a hole and never knew. ## Condition of Validity The resumption path is valid only when all of the following hold: - **The server holds an explicit liveness lease on the connection**, distinct from write progress. A periodic SSE comment (`: keepalive`) or a zero-length event that bypasses the application queue is sufficient, *provided it is written on a path that is not subject to the same backpressure*. If the keepalive shares the blocked queue, it proves nothing. - **The replay buffer retention is decoupled from write completion.** An event must be retained until the client *acknowledges* it (via a subsequent request, an explicit `Last-Event-ID` advance, or a transport-level ack), not until it is written to a socket. Write-completion is not delivery. - **The client distinguishes idle from dead by a signal other than read timeout**, or the server provides one. TCP keepalive at the socket layer is insufficient — it proves the peer's kernel is alive, not that the application is reading. - **Session state is monotonic in the event cursor**, so that a resume with a stale `Last-Event-ID` is either idempotent (replay from cursor is harmless) or rejected with a resumable error rather than silently accepted. If any of these fail, the correct behavior is to **fail the session closed** and require a fresh session, accepting the cost of re-establishing tool state, rather than to resume into an ambiguous stream. ## Decision Boundary The decision procedure at the client, on idle timeout, is: ``` on idle_timeout(T): if server_supports_keepalive and keepalive_seen_within(T/2): # stream is quiet but alive; backpressure is intentional extend_deadline(); do_not_resume() elif last_event_id is None: # nothing to resume from; treat as fresh failure fail_closed() elif server_advertises(monotonic_cursor) and server_advertises(ack_based_retention): resume(last_event_id) # safe: replay is idempotent, gap-free else: fail_closed() # resume would risk gap or duplicate ``` The decision procedure at the server, on receiving a resume with `Last-Event-ID`: ``` on resume(last_event_id): if last_event_id < retention_floor: raise SessionExpired(retention_floor) # gap unavoidable; force fresh session if last_event_id > current_cursor: raise CursorAhead(current_cursor) # client claims future state; corrupt if connection_with_pending_backpressure_exists(session): # a prior connection is still open and blocked; do not double-serve close_orphan(session); drain_to_retention_floor() replay_from(last_event_id) ``` The non-obvious boundary: `last_event_id < retention_floor` is not an error to paper over with a best-effort replay. It is a hard signal that the client's state is unrecoverable, and the only correct action is to invalidate the session and make the client re-initialize. Silent gap-filling is the failure mode that produced the divergence above. ## Operational Effect When the boundary is respected — keepalive decoupled from the backpressured queue, ack-based retention, and fail-closed on cursor regression — the observable behavior changes in three ways: 1. **Backpressure becomes stable.** A slow consumer no longer triggers a reconnect storm; the server holds the stream open, the client's queue drains at its own rate, and throughput is governed by the consumer rather than by the timeout. In the deployment above, p99 event latency under sustained load dropped from "unbounded, with periodic 30s cliffs" to the consumer's drain rate, and duplicate-delivery rate went to zero. 2. **Resumption becomes rare and meaningful.** Because idle no longer implies dead, resumes occur only on genuine connection loss. The replay buffer's retention window can shrink, because it only needs to cover true disconnect-reconnect intervals, not backpressure stalls. 3. **Failures become loud.** Sessions that cannot be safely resumed now raise a distinct, terminal error instead of silently resuming into a hole. Operators see the error rate; the alternative was a silent correctness bug. The cost is that a server must maintain per-connection liveness state independent of its write path, and a client must implement keepalive parsing. This is the price of distinguishing quiet from dead. Implementations that skip it will, under load, deliver the wrong answer with high confidence — which is strictly worse than delivering an error. ```python class McpResumeBoundaryError(RuntimeError): """Raised when an MCP streamable HTTP session cannot be safely resumed because the client's cursor has fallen below the server's retention floor, or because resumption would double-serve a connection still under intentional backpressure.""" class McpSession: def __init__(self, retention_floor: int, current_cursor: int, has_blocked_orphan: bool): self.retention_floor = retention_floor self.current_cursor = current_cursor self.has_blocked_orphan = has_blocked_orphan def resume(self, last_event_id: int) -> list: if last_event_id > self.current_cursor: raise McpResumeBoundaryError( f"cursor ahead of server: client={last_event_id} server={self.current_cursor}" ) if last_event_id < self.retention_floor: # Gap is unavoidable; resuming would silently skip events. raise McpResumeBoundaryError( f"cursor {last_event_id} below retention floor {self.retention_floor}; " "session must be re-initialized, not resumed" ) if self.has_blocked_orphan: # A prior connection is still open and blocked on backpressure. # Replaying now would double-serve and race the orphan's cleanup. raise McpResumeBoundaryError( "cannot resume while an orphaned connection holds pending " "backpressured writes; close orphan and drain first" ) return list(range(last_event_id + 1, self.current_cursor + 1)) ```