# Why does an instance negotiate a streaming capability but then deadlock on flow control? **Date of Record:** 2026 November 17 **Scope:** Applies to MCP servers and clients negotiating streaming HTTP transport (SSE / chunked transfer) where capability advertisement is decoupled from per-stream flow-control parameters. Does not apply to stdio transport, nor to request/response-only JSON-RPC over a single HTTP body where no incremental stream is opened. ## Core Distinction Capability negotiation and flow-control negotiation are two different handshakes that happen at two different layers, and MCP's `initialize` / `capabilities` exchange only performs the first one. A server advertising `"streaming": true` (or the equivalent streaming tool/resource capability) is asserting that it *can* emit incremental frames on a persistent HTTP response. It is **not** asserting anything about how much it will emit before the client drains the socket, nor about whether it honors `WINDOW_UPDATE`-style credit, nor about the size of the transport's internal write buffer. The non-obvious invariant is this: **a streaming capability advertisement is a liveness claim, not a flow-control contract.** An instance that treats `capabilities.streaming == true` as permission to write unboundedly into the response body will pass negotiation and then deadlock the moment the client's read side is slower than the server's write side, because neither peer has agreed on a credit or backpressure protocol. The connection stays open, the capability check reports success, and yet no progress is made — the classic "successful negotiation, stalled stream" failure. ## What Was Observed During an integration run, a client opened a `tools/call` that returned a `text/event-stream` response. The `initialize` handshake completed cleanly: the server returned `capabilities: { streaming: true, tools: {...} }`, and the client recorded the session as stream-capable. The tool produced a large audit log — roughly 40 MB of newline-delimited events — written to the response writer in a tight loop with no `flush()` gating on client consumption. The client, meanwhile, processed each SSE frame through a downstream pipeline that periodically paused (a batch commit every N frames). Because the client stopped calling `read()` on the socket during those pauses, the kernel receive buffer filled, then the TCP window closed, then the server's socket send buffer filled. The server's `write()` blocked inside the event loop. The server had a single-threaded async runtime; the blocked write held the loop, so it could no longer service the client's heartbeat or the client's eventual `WINDOW_UPDATE`-equivalent (here, the resumed `read()`). Both sides waited on each other. Diagnostics were misleading. `capabilities.streaming` was `true`. The HTTP status was `200`. No error was logged. The only signal was a rising `ss -ti` send-queue depth on the server and a flat `bytes_read` counter on the client. The session was eventually killed by an idle timeout, not by any protocol-level failure — which is exactly why the boundary is non-obvious: the negotiation succeeded, and the failure surfaced as a timeout far from its cause. A second variant appeared with a proxy in the path: the intermediary buffered the SSE body to compute `Content-Length`, defeating streaming entirely, so the client saw no frames until the server finished writing — which it never did, because the proxy's upstream buffer was full. Again: capability true, negotiation clean, deadlock. ## Condition of Validity The deadlock manifests only when **all** of the following hold: 1. The transport is a single persistent HTTP response with incremental framing (SSE or chunked), not a request/response body. 2. The server writes into the response without consulting a credit/window or without yielding to the event loop between bounded chunks. 3. The client can pause reads (application-level batching, slow consumer, or a buffering intermediary). 4. The server's write path is coupled to the same execution context that must service the client's resumption (single-threaded loop, or a shared lock). If any one is false, the system degrades gracefully instead. If the server chunks writes and `await`s a drain signal, a slow client merely slows the server. If the client never pauses, the buffers never fill. If the server has a dedicated writer thread that does not block the control path, the loop keeps servicing. The boundary is the *conjunction*, which is why capability flags alone cannot predict it. ## Decision Boundary The operational rule is: **do not derive flow-control behavior from the streaming capability bit.** Treat `capabilities.streaming == true` as necessary but not sufficient. Before opening a stream that may exceed the transport's default buffer (empirically, anything larger than a few hundred KB is suspect), an instance must establish an explicit backpressure contract out of band: - Either the client advertises a maximum in-flight frame count / byte window during `initialize` (an extension field, e.g. `streaming.max_inflight_bytes`), and the server refuses to exceed it; - Or the server bounds each write to a small chunk and `await`s a transport-level drain before writing the next; - Or the deployment guarantees a non-blocking writer decoupled from the control loop. If none of these can be established, the correct decision is to **downgrade to non-streaming** (buffer the full result and return a single response with a known length) rather than to trust the capability bit. The negotiation result should be recorded as `streaming: negotiated` only when the backpressure contract is also present; otherwise record `streaming: capability_only` and route through the bounded path. ## Operational Effect Instances that conflate the two handshakes exhibit a specific signature: high negotiation success rate, `200` responses, zero protocol errors, and a long tail of sessions that terminate on idle timeout with the server's send queue non-empty. The failure is invisible to capability-based health checks, so dashboards report "healthy" while throughput collapses. The corrective action is to make backpressure explicit in the negotiation payload and to fail loud when a stream is requested without a declared window — never to silently proceed on the capability bit alone. The check below encodes that: it rejects a streaming session whose negotiated parameters lack a bounded window, rather than trusting the capability advertisement. ```python class BackpressureContractError(RuntimeError): """Raised when a streaming session is opened without a bounded flow-control window.""" pass DEFAULT_MAX_INFLIGHT_BYTES = 256 * 1024 def open_stream_session(negotiated: dict) -> dict: """ Validate that a negotiated MCP session has an explicit backpressure contract before permitting streaming. `negotiated` is the parsed initialize result augmented with any transport-extension fields. """ caps = negotiated.get("capabilities", {}) if not caps.get("streaming", False): # Non-streaming is always safe: caller buffers and returns a bounded body. return {"mode": "buffered", "max_inflight_bytes": 0} window = negotiated.get("streaming", {}).get("max_inflight_bytes") if window is None: # Capability bit set, but no flow-control contract: do NOT trust it. raise BackpressureContractError( "server advertised streaming=true but no streaming.max_inflight_bytes " "was negotiated; refusing to open an unbounded stream " "(would deadlock on a slow or pausing client)" ) if not isinstance(window, int) or window <= 0: raise BackpressureContractError( f"invalid streaming.max_inflight_bytes={window!r}; must be a positive int" ) if window > DEFAULT_MAX_INFLIGHT_BYTES: # Clamp to the transport-safe ceiling rather than honoring an oversized claim. window = DEFAULT_MAX_INFLIGHT_BYTES return {"mode": "streaming", "max_inflight_bytes": window} def write_chunk(session: dict, payload: bytes, inflight: int) -> int: """Write one chunk, enforcing the negotiated window; returns new inflight count.""" if session["mode"] != "streaming": raise BackpressureContractError("write_chunk called on a buffered session") limit = session["max_inflight_bytes"] if inflight + len(payload) > limit: raise BackpressureContractError( f"chunk of {len(payload)}B would exceed negotiated window " f"({inflight}+{len(payload)} > {limit}); await drain before writing" ) return inflight + len(payload) ```