# Where must an instance of a streamable MCP session re-derive its backpressure credit after HTTP-native resumption, and why the EventSource `Last-Event-ID` alone is insufficient **Date of Record:** 2026 November 16 **Scope:** Applies to MCP servers and clients using the HTTP-native (Streamable HTTP) transport where a session is resumed after a transport-level interruption via `Last-Event-ID` replay, and where the server applies per-session flow control (credit windows, in-flight request caps, or write-buffer watermarks). Does not apply to stdio transports, to WebSocket transports with native TCP backpressure, or to sessions that are resumed by full re-initialization rather than event replay. ## Core Distinction The distinction that matters is between **event continuity** and **credit continuity**. `Last-Event-ID` guarantees the former: the server can replay every SSE event with a sequence number greater than the client's last acknowledged ID, so the client observes no logical gap in the message stream. It says nothing about the latter. Credit — the count of bytes or messages the server is currently permitted to push to that session before the client has drained its receive buffer — is a property of the *socket and the client's read loop*, not of the event log. When a session breaks and resumes, the old socket's credit is destroyed with the socket, but the event log still contains events that were *emitted* (and thus consumed credit) yet never *delivered*. Replay re-emits those events on a new socket, and the new socket begins with fresh, full credit. The instance therefore double-counts: once when the event was first written into a buffer that died, and again when it is replayed. The non-obvious invariant is this: **the credit ledger must be reconstructed from the replay boundary, not from the event log, and the reconstruction point is the first event ID strictly greater than the client's acknowledged `Last-Event-ID`, evaluated against the server's *sent* watermark — not its *committed* watermark.** Any implementation that treats the event log as the source of truth for both ordering and flow control will, under load, either over-send (credit leak) or stall (credit starvation). ## What Was Observed In a deployment serving long-running tool-call sessions over Streamable HTTP, sessions were interrupted by a load balancer recycling backend connections at a 300-second idle timeout. Clients reconnected with `Last-Event-ID` and received correct replay. Two failure signatures appeared, both traceable to the credit ledger: 1. **Credit leak on replay.** After resumption, the server's per-session in-flight counter was observed to be *lower* than the number of events actually queued to the client's kernel buffer, because the pre-disconnect events had decremented the counter at emit time and the replayed copies decremented it again at re-emit time. Under sustained tool-call traffic, sessions that resumed more than twice hit the in-flight cap (default 64) and stopped accepting new `tools/call` requests while the client believed the session healthy — a silent stall with no error frame, because the cap was enforced before the JSON-RPC error path. 2. **Credit starvation on partial drain.** When a client reconnected but its read loop was slow (large replay backlog), the server's write buffer watermark tripped and it stopped emitting *new* events. The client, having received all replayed events up to its `Last-Event-ID` and then nothing, interpreted the silence as a completed stream and closed the session. The server saw a clean disconnect and released the session's credit — but the client had not actually processed the tail of the replay, only buffered it. The next resume replayed from the same `Last-Event-ID`, and the cycle repeated. This is a livelock, not a crash, and it is invisible in per-request latency metrics because each individual request succeeds. The common root cause in both cases: the server conflated "the event exists in the log" with "the event has been delivered and its credit is settled." `Last-Event-ID` is an *acknowledgement of receipt*, which is strictly stronger than *acknowledgement of processing* and strictly weaker than *acknowledgement of credit settlement*. The gap between receipt and settlement is exactly the replay window, and it must be accounted for explicitly. ## Condition of Validity The single-ledger model (one counter for both ordering and credit) is valid only under the conjunction of: - the transport provides reliable, ordered delivery with no replay (i.e., no resumption ever occurs), **or** - the server never applies backpressure (credit is infinite; the ledger is purely advisory), **or** - replay is idempotent with respect to credit because credit is recomputed from scratch at every resume boundary from the client's advertised receive window. In any deployment where resumption is possible *and* backpressure is enforced, none of these hold, and the conflation is a latent defect that manifests only under the specific interleaving of (disconnect during in-flight write) × (replay backlog exceeds watermark) × (client read loop slower than replay rate). It will not appear in single-connection tests, in tests with fast local clients, or in tests where the LB idle timeout exceeds the longest tool-call duration. ## Decision Boundary The operational rule is a hard boundary, not a heuristic: > **On resumption, the server MUST reset the session's credit ledger to the client's advertised receive window (or the server's configured initial window, whichever is smaller), and MUST treat every replayed event as consuming credit *at replay time*, not at original emit time. The pre-disconnect emit-time decrements are void and must be discarded, not reconciled.** The corollary, which is where most implementations fail: **the replay boundary must be computed as `max(acknowledged Last-Event-ID, sent-watermark-at-disconnect) + 1` for credit purposes, while replay for *delivery* purposes starts at `acknowledged Last-Event-ID + 1`.** These two boundaries differ by exactly the events that were sent-but-not-acknowledged at disconnect. Those events consume *new* credit on replay (correct) and must not consume *old* credit (which is void). If an implementation uses a single boundary for both, it either under-counts (leak) or over-counts (starvation). If the server cannot determine the sent-watermark at disconnect — because it discarded it with the socket — it must conservatively assume the watermark equals the last event ID it *attempted* to write, and it must therefore reset credit to the full window and re-send from the acknowledged ID. The cost is duplicate replay; the alternative is a ledger that cannot be trusted. ## Operational Effect With the corrected boundary, three observable changes appear: - **In-flight counters track delivered, not emitted, events.** The cap becomes a true concurrency limit on client-visible work rather than a proxy for server-side emit rate, which is the property operators actually want when sizing per-session limits. - **Replay is bounded by the client's receive window, not by the log.** A slow client cannot force unbounded replay; it forces a bounded replay followed by a pause, which is the correct backpressure signal and is visible as a `429`-equivalent on the SSE stream (a `retry:` hint plus a stall) rather than as silent truncation. - **The livelock signature disappears.** The client's "stream completed" inference is defeated because the server, having reset credit, will emit a heartbeat or a `session/heartbeat` notification after the replay window closes, preventing the client from treating post-replay silence as termination. The residual risk is duplicate delivery of events in the `(acknowledged, sent]` interval. This is unavoidable and must be handled by client-side idempotency keyed on event ID — which MCP clients are required to do anyway for `Last-Event-ID` replay, so the corrected boundary adds no new client obligation. What it adds is a server-side obligation: the credit ledger is per-socket and dies with the socket; it must never be persisted across a resume. ```python from dataclasses import dataclass, field from typing import Optional class CreditLedgerInvariantError(RuntimeError): """Raised when a resumed session's credit ledger cannot be reconstructed without violating the sent-watermark / acknowledged-ID boundary.""" @dataclass class SessionCreditState: session_id: str window: int in_flight: int = 0 sent_watermark: int = 0 acknowledged_id: int = 0 socket_generation: int = 0 def resume_session( state: SessionCreditState, client_last_event_id: int, client_receive_window: Optional[int], ) -> SessionCreditState: """Re-derive credit after HTTP-native resumption. Invariant: the new socket starts with full credit; pre-disconnect emit-time decrements are void. Replay boundary for *delivery* is acknowledged_id + 1; replay boundary for *credit* is max(acknowledged_id, sent_watermark) + 1. """ if client_last_event_id > state.sent_watermark: raise CreditLedgerInvariantError( f"session {state.session_id}: client acknowledged event " f"{client_last_event_id} beyond server sent-watermark " f"{state.sent_watermark}; ledger cannot be trusted, " f"refusing to resume" ) if client_last_event_id < 0: raise CreditLedgerInvariantError( f"session {state.session_id}: negative Last-Event-ID " f"{client_last_event_id} is not a valid acknowledgement" ) new_window = state.window if client_receive_window is not None: if client_receive_window < 0: raise CreditLedgerInvariantError( f"session {state.session_id}: client advertised negative " f"receive window {client_receive_window}" ) new_window = min(state.window, client_receive_window) # Credit ledger is per-socket: discard, do not reconcile. state.in_flight = 0 state.window = new_window state.acknowledged_id = client_last_event_id state.socket_generation += 1 # sent_watermark is preserved as a *replay* hint, not as a credit # source; the first replayed event re-consumes credit at replay time. return state ```