From 25eab69aba7548170f18d1d2a58401ff3bada9bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ond=C5=99ej=20=C3=9Alehla?= <ondrejulehla@gmail.com>
Date: Sun, 26 Jul 2026 20:50:51 +0200
Subject: [PATCH] fix(client): settle stdio send() from the write callback

A backpressured `StdioClientTransport.send()` waited for a `'drain'` event, but
a pipe destroyed by the server process exiting never drains, so the promise
stayed pending for the lifetime of the process and the `'drain'` listener
leaked. Settle from the `write()` callback instead, which Node invokes on flush
or on failure, so the send rejects with the underlying write error. This is what
`StdioServerTransport.send()` already does for its own stdout.
---
 .changeset/stdio-client-send-drain-hang.md |  9 +++++
 packages/client/src/client/stdio.ts        | 10 +++---
 packages/client/test/client/stdio.test.ts  | 38 ++++++++++++++++++++++
 3 files changed, 53 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/stdio-client-send-drain-hang.md

diff --git a/.changeset/stdio-client-send-drain-hang.md b/.changeset/stdio-client-send-drain-hang.md
new file mode 100644
index 0000000000..724ea7a59a
--- /dev/null
+++ b/.changeset/stdio-client-send-drain-hang.md
@@ -0,0 +1,9 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Fix `StdioClientTransport.send()` never settling when a backpressured write is still in flight and the pipe to the server dies. `send()` waited for a `'drain'` event, but a destroyed stream never drains, so the returned promise stayed pending and the `'drain'` listener was never removed. It now settles from the `write()` callback, which Node invokes on flush or on failure, so the send rejects with the underlying write error instead. This is what `StdioServerTransport.send()` already does for its own stdout.
+
+The visible symptom was `await client.notification(...)`, which never returned: the notification path awaits the transport send with no timeout, and the connection-closed teardown settles pending responses but not pending sends. Requests were already rescued by that teardown, so `callTool()` and friends now report the actual write error (`EPIPE`, `EOF`) rather than a generic connection-closed error.
+
+Reaching this needs a write the pipe will not accept in one go, which starts anywhere from tens to hundreds of KB depending on the platform pipe buffer and the Node version, sizes that base64 image payloads and file contents in tool arguments reach routinely.
diff --git a/packages/client/src/client/stdio.ts b/packages/client/src/client/stdio.ts
index a4664e1c93..7a74828ada 100644
--- a/packages/client/src/client/stdio.ts
+++ b/packages/client/src/client/stdio.ts
@@ -313,16 +313,18 @@ export class StdioClientTransport implements Transport {
     }
 
     send(message: JSONRPCMessage): Promise<void> {
-        return new Promise(resolve => {
+        return new Promise((resolve, reject) => {
             if (!this._process?.stdin) {
                 throw new SdkError(SdkErrorCode.NotConnected, 'Not connected');
             }
 
             const json = serializeMessage(message);
-            if (this._process.stdin.write(json)) {
+            // The write callback runs once the chunk is flushed or the write fails,
+            // so a backpressured send still settles when the server exits and
+            // destroys the pipe. Waiting on 'drain' alone parks forever there,
+            // because a destroyed stream never drains.
+            if (this._process.stdin.write(json, error => (error ? reject(error) : resolve()))) {
                 resolve();
-            } else {
-                this._process.stdin.once('drain', resolve);
             }
         });
     }
diff --git a/packages/client/test/client/stdio.test.ts b/packages/client/test/client/stdio.test.ts
index 315b8a2595..bfa418223f 100644
--- a/packages/client/test/client/stdio.test.ts
+++ b/packages/client/test/client/stdio.test.ts
@@ -150,3 +150,41 @@ test('_dispose releases the parent-side pipe handles even when a helper process
     expect(proc.stdout?.destroyed).toBe(true);
     expect(proc.stdin?.destroyed).toBe(true);
 }, 10_000);
+
+test('send() rejects instead of hanging when the server exits before a large write flushes', async () => {
+    // A server that never reads stdin and then exits: the write stays buffered,
+    // and the exit destroys the pipe, so the stream can never flush or drain.
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: ['-e', 'setTimeout(() => process.exit(0), 200)']
+    });
+    transport.onerror = () => {};
+    await transport.start();
+    const stdin = (transport as unknown as { _process: import('node:child_process').ChildProcess })._process.stdin!;
+
+    // 8 MB of params, far past stdin's 16 KB high water mark, so write() returns
+    // false and the send has to wait for the stream instead of resolving at once.
+    const pending = transport.send({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name: 'echo', arguments: { blob: 'x'.repeat(8 * 1024 * 1024) } }
+    });
+
+    // Bounded so the unfixed behaviour reports as 'hung' rather than as a suite
+    // timeout. The rejection reason is platform specific (EPIPE, EOF), so only
+    // the fact that it settles is asserted.
+    const outcome = await Promise.race([
+        pending.then(
+            () => 'resolved' as const,
+            () => 'rejected' as const
+        ),
+        new Promise<'hung'>(resolve => {
+            setTimeout(() => resolve('hung'), 3000).unref();
+        })
+    ]);
+
+    expect(outcome).toBe('rejected');
+    expect(stdin.listenerCount('drain')).toBe(0);
+    await transport.close();
+}, 15_000);