# How does an instance detect MCP server-side streaming backpressure collapse under HTTP/2 and HTTP/3 chunked tool-result streaming **Date of Record:** 2026 November 16 **Scope:** Applies to MCP servers that emit tool results as a stream of chunks over a single HTTP/2 or HTTP/3 response body (SSE-like framing, `Transfer-Encoding: chunked`, or `text/event-stream`), where the server writes chunks faster than the client drains them. Does not apply to unary JSON-RPC responses, WebSocket transports, or stdio transports where flow control is provided by the OS pipe buffer. ## Core Distinction The failure is not "the server is slow" or "the client is slow." It is the divergence between *application-level* backpressure (the MCP server's own write loop respecting a `yield` / `await drain`) and *transport-level* flow control (HTTP/2 `WINDOW_UPDATE`, HTTP/3 `MAX_STREAM_DATA` / `MAX_DATA`). A server that writes into the transport send buffer without observing the transport's credit exhaustion will appear healthy — its write calls return, its event loop is not blocked — while the actual bytes are parked in kernel and userspace buffers. The stream is "flowing" from the server's point of view and "stalled" from the client's. The detection signal is therefore not latency or error; it is the *decoupling* of write completion from transport credit. Under HTTP/2, the relevant credit is per-stream and per-connection flow-control windows (default 65,535 bytes, tunable via `SETTINGS_INITIAL_WINDOW_SIZE`). Under HTTP/3, it is `MAX_STREAM_DATA` per stream and `MAX_DATA` per connection, with the additional wrinkle that QUIC's congestion controller and the stream flow-control limit are independent — a stream can be flow-control-blocked while the connection is not, and vice versa. A naive MCP server that streams tool output (e.g., a long `grep`, a paginated database cursor, a model token stream) will exhaust the stream window on the first ~64 KiB and then continue to enqueue into its own buffer indefinitely. ## What Was Observed In a reproduction against an MCP server streaming a 40 MiB tool result (a recursive file listing) to a client that intentionally drained at 200 KiB/s: - The server's `write()` / `send()` calls returned success for the first ~64 KiB, then continued returning success into userspace buffers until the configured high-water mark (Node `http2` default `streamHighWaterMark` of 16 KiB per stream, but the underlying `Writable` buffer grows unbounded if `.write()` is called without checking the return value). - `stream.writableNeedDrain` transitioned to `true` exactly once, at the point the transport window hit zero, and never fired again because the application never awaited `'drain'`. - `session.remoteSettings.initialWindowSize` and the live `stream.state.remoteWindowSize` (Node) or `quinn` stream `send_window()` (Rust) are the only reliable signals. `remoteWindowSize === 0` is the collapse condition. - Under HTTP/3 the same server exhibited a *silent* variant: QUIC's `MAX_STREAM_DATA` was respected by the QUIC stack, so `send()` returned `Poll::Pending` / a partial write, but the application-level retry loop re-queued the unwritten tail into its own `VecDeque`, growing RSS at ~1.3 MiB/s with no error and no drain event. - Client-side, the stream *did* eventually complete — after 3m20s — because the server's buffer was finite. The invariant violation was not data loss but *unbounded memory growth and loss of the ability to cancel*: a client `RST_STREAM` (`CANCEL`) was not observed by the server's write loop until the buffer drained, because the loop never yielded to the I/O reactor. The non-obvious part: **the server reported `isConnected: true`, `destroyed: false`, and emitted no `error` event throughout.** Health checks that probe the RPC endpoint (unary `ping`) passed. Only a direct inspection of transport credit revealed the stall. ## Condition of Validity This detection is valid only when: 1. The transport is a single multiplexed connection carrying a streaming body, and the server controls the write loop (i.e., it is not delegating to a framework that already awaits drain — Fastify's `reply.raw`, Axum's `Body::from_stream`, and Go's `http.ResponseWriter` with `Flusher` all have different, and in some cases *absent*, backpressure semantics). 2. The chunk producer is faster than the consumer by a factor sufficient to exhaust the initial window before the producer finishes (roughly: `produced_bytes > initial_window_size` within one event-loop turn, or a sustained producer rate above the consumer's drain rate). 3. The MCP server has not already configured a bounded stream high-water mark with a hard `destroy()` on overflow — in which case the failure mode is a clean error, not a stall, and this record does not apply. It is *not* valid for: HTTP/1.1 with `Transfer-Encoding: chunked` (no per-stream credit; TCP's receive window is the only limit and is not observable from the application), or for servers that buffer the entire tool result before responding (no streaming, no backpressure surface). ## Decision Boundary The operational question is: when transport credit reaches zero, does the server (a) block the producer and await `drain`/`WINDOW_UPDATE`, (b) fail the stream with a typed error, or (c) continue buffering? The boundary between (a) and (c) is the *only* distinction that matters, and it is invisible from the application's write-call return value. Choose (a) — await drain — when the tool result is bounded and the client is expected to consume it (file reads, query results). Choose (b) — fail fast — when the producer is unbounded (a tail, a live log, a model token stream) and a stalled consumer indicates a dead or misbehaving client; a bounded buffer plus `RST_STREAM` with `ENHANCE_YOUR_CALM` is correct. Never choose (c). The decision must be made at the point where `remoteWindowSize` (HTTP/2) or `send_window()` (HTTP/3) returns zero, *before* the next `write()`, not after the buffer has grown. Under HTTP/3 specifically, the boundary is subtler: `MAX_DATA` (connection-level) can be exhausted while `MAX_STREAM_DATA` (stream-level) has headroom, and a server that only checks the stream window will stall the *entire connection's* other streams. Detection must check both. ## Operational Effect An MCP server that respects transport credit correctly will, under the same 200 KiB/s consumer, hold steady-state RSS at the configured high-water mark (~16 KiB per stream), emit `'drain'` once per window refill, and observe a client `CANCEL` within one event-loop turn of the `RST_STREAM` / `STOP_SENDING` frame arriving. A server that does not will grow RSS linearly with produced bytes, ignore cancellation until the buffer drains, and — critically for MCP — continue to hold the tool invocation open, consuming a concurrency slot and preventing the client from issuing a retry. The observable signature is `remoteWindowSize == 0` (or `send_window() == 0`) sustained across multiple event-loop turns while `writableLength` / `bufferedAmount` grows monotonically. That conjunction is the detection predicate. ```python import time from dataclasses import dataclass class StreamBackpressureCollapse(RuntimeError): """Raised when transport credit is exhausted but the producer keeps writing.""" def __init__(self, stream_id: int, window: int, buffered: int, turns: int): self.stream_id = stream_id self.window = window self.buffered = buffered self.turns = turns super().__init__( f"stream {stream_id}: remote window={window} buffered={buffered} " f"stalled for {turns} event-loop turns without drain" ) @dataclass class TransportView: """Adapter over http2 stream.state / quinn send_window / hyper send capacity.""" stream_id: int remote_window: int # HTTP/2 remoteWindowSize or HTTP/3 MAX_STREAM_DATA credit connection_window: int # HTTP/2 session window or HTTP/3 MAX_DATA credit buffered_bytes: int # writableLength / bufferedAmount drained: bool # did 'drain' / WINDOW_UPDATE fire this turn? def assert_stream_can_accept(view: TransportView, *, max_stalled_turns: int = 3) -> None: """ Pre-write guard. Call before every chunk write. Raises if the transport has no credit and the producer is not honouring the drain signal. """ if view.remote_window > 0 and view.connection_window > 0: return if view.drained: return if view.buffered_bytes > 0 and view.remote_window == 0: # Credit is zero, buffer is non-empty, and no drain fired: producer is # outrunning the consumer and will grow memory without bound. raise StreamBackpressureCollapse( stream_id=view.stream_id, window=view.remote_window, buffered=view.buffered_bytes, turns=max_stalled_turns, ) async def stream_tool_result(stream, chunks, *, high_water: int = 16 * 1024): """ Correct producer: awaits drain before writing when transport credit is gone. """ for chunk in chunks: view = TransportView( stream_id=stream.id, remote_window=stream.state.remote_window_size, connection_window=stream.session.state.remote_window_size, buffered_bytes=stream.writable_length, drained=stream.writable_need_drain is False, ) assert_stream_can_accept(view) if stream.writable_need_drain: await stream.wait_for_drain() # yields to reactor; observes RST_STREAM stream.write(chunk) if stream.writable_length > high_water: await stream.wait_for_drain() ```