fix: async onclose, stdin EOF detection, SIGTERM in examples

.changeset/async-onclose-stdin-eof.md

@@ -0,0 +1,11 @@
+---
+"@modelcontextprotocol/core": patch
+"@modelcontextprotocol/server": patch
+"@modelcontextprotocol/client": patch
+---
+
+Allow async `onclose` callbacks on Transport and Protocol. The signature changes from `() => void` to `() => void | Promise<void>`, and all call sites now await the callback. This lets MCP servers perform async cleanup (e.g., releasing browser sessions or database connections) when the transport closes.
+
+Close `StdioServerTransport` when stdin reaches EOF, so containerized servers exit cleanly on client disconnect.
+
+Add SIGTERM handlers alongside SIGINT in all examples, since MCP servers run as background processes stopped by SIGTERM, not interactively via Ctrl+C.

examples/client/src/elicitationUrlExample.ts

@@ -813,6 +813,10 @@ process.on('SIGINT', async () => {
     console.log('\nReceived SIGINT. Cleaning up...');
     await cleanup();
 });
+process.on('SIGTERM', async () => {
+    console.log('\nReceived SIGINT. Cleaning up...');
+    await cleanup();
+});
 
 // Start the interactive client
 try {

examples/client/src/simpleOAuthClient.ts

@@ -448,6 +448,11 @@ async function main(): Promise<void> {
         client.close();
         process.exit(0);
     });
+    process.on('SIGTERM', () => {
+        console.log('\n\n👋 Goodbye!');
+        client.close();
+        process.exit(0);
+    });
 
     try {
         await client.connect();

examples/client/src/simpleStreamableHttp.ts

@@ -997,6 +997,10 @@ process.on('SIGINT', async () => {
     console.log('\nReceived SIGINT. Cleaning up...');
     await cleanup();
 });
+process.on('SIGTERM', async () => {
+    console.log('\nReceived SIGINT. Cleaning up...');
+    await cleanup();
+});
 
 // Start the interactive client
 try {

examples/server/src/elicitationFormExample.ts

@@ -453,6 +453,22 @@ async function main() {
     process.on('SIGINT', async () => {
         console.log('Shutting down server...');
 
+        // Close all active transports to properly clean up resources
+        for (const sessionId in transports) {
+            try {
+                console.log(`Closing transport for session ${sessionId}`);
+                await transports[sessionId]!.close();
+                delete transports[sessionId];
+            } catch (error) {
+                console.error(`Error closing transport for session ${sessionId}:`, error);
+            }
+        }
+        console.log('Server shutdown complete');
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        console.log('Shutting down server...');
+
         // Close all active transports to properly clean up resources
         for (const sessionId in transports) {
             try {

examples/server/src/elicitationUrlExample.ts

@@ -731,3 +731,20 @@ process.on('SIGINT', async () => {
     console.log('Server shutdown complete');
     process.exit(0);
 });
+process.on('SIGTERM', async () => {
+    console.log('Shutting down server...');
+
+    // Close all active transports to properly clean up resources
+    for (const sessionId in transports) {
+        try {
+            console.log(`Closing transport for session ${sessionId}`);
+            await transports[sessionId]!.close();
+            delete transports[sessionId];
+            delete sessionsNeedingElicitation[sessionId];
+        } catch (error) {
+            console.error(`Error closing transport for session ${sessionId}:`, error);
+        }
+    }
+    console.log('Server shutdown complete');
+    process.exit(0);
+});

examples/server/src/jsonResponseStreamableHttp.ts

@@ -163,3 +163,7 @@ process.on('SIGINT', async () => {
     console.log('Shutting down server...');
     process.exit(0);
 });
+process.on('SIGTERM', async () => {
+    console.log('Shutting down server...');
+    process.exit(0);
+});

examples/server/src/simpleStatelessStreamableHttp.ts

@@ -169,3 +169,8 @@ process.on('SIGINT', async () => {
     // eslint-disable-next-line unicorn/no-process-exit
     process.exit(0);
 });
+process.on('SIGTERM', async () => {
+    console.log('Shutting down server...');
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(0);
+});

examples/server/src/simpleStreamableHttp.ts

@@ -815,3 +815,19 @@ process.on('SIGINT', async () => {
     console.log('Server shutdown complete');
     process.exit(0);
 });
+process.on('SIGTERM', async () => {
+    console.log('Shutting down server...');
+
+    // Close all active transports to properly clean up resources
+    for (const sessionId in transports) {
+        try {
+            console.log(`Closing transport for session ${sessionId}`);
+            await transports[sessionId]!.close();
+            delete transports[sessionId];
+        } catch (error) {
+            console.error(`Error closing transport for session ${sessionId}:`, error);
+        }
+    }
+    console.log('Server shutdown complete');
+    process.exit(0);
+});

examples/server/src/simpleTaskInteractive.ts

@@ -741,3 +741,18 @@ process.on('SIGINT', async () => {
     console.log('Server shutdown complete');
     process.exit(0);
 });
+process.on('SIGTERM', async () => {
+    console.log('\nShutting down server...');
+    for (const sessionId of Object.keys(transports)) {
+        try {
+            await transports[sessionId]!.close();
+            delete transports[sessionId];
+        } catch (error) {
+            console.error(`Error closing session ${sessionId}:`, error);
+        }
+    }
+    taskStore.cleanup();
+    messageQueue.cleanup();
+    console.log('Server shutdown complete');
+    process.exit(0);
+});

examples/server/src/standaloneSseWithGetStreamableHttp.ts

@@ -159,3 +159,21 @@ process.on('SIGINT', async () => {
     console.log('Server shutdown complete');
     process.exit(0);
 });
+process.on('SIGTERM', async () => {
+    console.log('Shutting down server...');
+    clearInterval(resourceChangeInterval);
+
+    // Close all active transports to properly clean up resources
+    for (const sessionId in transports) {
+        try {
+            console.log(`Closing transport for session ${sessionId}`);
+            await transports[sessionId]!.close();
+            delete transports[sessionId];
+            delete servers[sessionId];
+        } catch (error) {
+            console.error(`Error closing transport for session ${sessionId}:`, error);
+        }
+    }
+    console.log('Server shutdown complete');
+    process.exit(0);
+});

packages/client/src/client/sse.ts

@@ -78,7 +78,7 @@ export class SSEClientTransport implements Transport {
     private _fetchWithInit: FetchLike;
     private _protocolVersion?: string;
 
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
 
@@ -242,7 +242,7 @@ export class SSEClientTransport implements Transport {
     async close(): Promise<void> {
         this._abortController?.abort();
         this._eventSource?.close();
-        this.onclose?.();
+        await this.onclose?.();
     }
 
     async send(message: JSONRPCMessage): Promise<void> {

packages/client/src/client/stdio.ts

@@ -96,7 +96,7 @@ export class StdioClientTransport implements Transport {
     private _serverParams: StdioServerParameters;
     private _stderrStream: PassThrough | null = null;
 
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
 
@@ -139,9 +139,9 @@ export class StdioClientTransport implements Transport {
                 resolve();
             });
 
-            this._process.on('close', _code => {
+            this._process.on('close', async _code => {
                 this._process = undefined;
-                this.onclose?.();
+                await this.onclose?.();
             });
 
             this._process.stdin?.on('error', error => {

packages/client/src/client/streamableHttp.ts

@@ -152,7 +152,7 @@ export class StreamableHTTPClientTransport implements Transport {
     private _serverRetryMs?: number; // Server-provided retry delay from SSE retry field
     private _reconnectionTimeout?: ReturnType<typeof setTimeout>;
 
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
 
@@ -463,7 +463,7 @@ export class StreamableHTTPClientTransport implements Transport {
             this._reconnectionTimeout = undefined;
         }
         this._abortController?.abort();
-        this.onclose?.();
+        await this.onclose?.();
     }
 
     async send(

packages/client/src/client/websocket.ts

@@ -10,7 +10,7 @@ export class WebSocketClientTransport implements Transport {
     private _socket?: WebSocket;
     private _url: URL;
 
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage) => void;
 
@@ -38,8 +38,8 @@ export class WebSocketClientTransport implements Transport {
                 resolve();
             };
 
-            this._socket.onclose = () => {
-                this.onclose?.();
+            this._socket.onclose = async () => {
+                await this.onclose?.();
             };
 
             this._socket.onmessage = (event: MessageEvent) => {

packages/core/src/shared/protocol.ts

@@ -316,7 +316,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
      *
      * This is invoked when {@linkcode Protocol.close | close()} is called as well.
      */
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
 
     /**
      * Callback for when an error occurs.
@@ -456,11 +456,11 @@ export abstract class Protocol<ContextT extends BaseContext> {
     async connect(transport: Transport): Promise<void> {
         this._transport = transport;
         const _onclose = this.transport?.onclose;
-        this._transport.onclose = () => {
+        this._transport.onclose = async () => {
             try {
-                _onclose?.();
+                if (_onclose) await _onclose();
             } finally {
-                this._onclose();
+                await this._onclose();
             }
         };
 
@@ -490,12 +490,15 @@ export abstract class Protocol<ContextT extends BaseContext> {
         await this._transport.start();
     }
 
-    private _onclose(): void {
+    private async _onclose(): Promise<void> {
         const responseHandlers = this._responseHandlers;
         this._responseHandlers = new Map();
         this._progressHandlers.clear();
         this._taskManager.onClose();
         this._pendingDebouncedNotifications.clear();
+        this._transport = undefined;
+
+        await this.onclose?.();
 
         for (const info of this._timeoutInfo.values()) {
             clearTimeout(info.timeoutId);
@@ -507,18 +510,12 @@ export abstract class Protocol<ContextT extends BaseContext> {
 
         const error = new SdkError(SdkErrorCode.ConnectionClosed, 'Connection closed');
 
-        this._transport = undefined;
-
-        try {
-            this.onclose?.();
-        } finally {
-            for (const handler of responseHandlers.values()) {
-                handler(error);
-            }
+        for (const handler of responseHandlers.values()) {
+            handler(error);
+        }
 
-            for (const controller of requestHandlerAbortControllers.values()) {
-                controller.abort(error);
-            }
+        for (const controller of requestHandlerAbortControllers.values()) {
+            controller.abort(error);
         }
     }
 

packages/core/src/shared/transport.ts

@@ -98,7 +98,7 @@ export interface Transport {
      *
      * This should be invoked when {@linkcode Transport.close | close()} is called as well.
      */
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
 
     /**
      * Callback for when an error occurs.

packages/core/src/util/inMemory.ts

@@ -15,7 +15,7 @@ export class InMemoryTransport implements Transport {
     private _messageQueue: QueuedMessage[] = [];
     private _closed = false;
 
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
     onerror?: (error: Error) => void;
     onmessage?: (message: JSONRPCMessage, extra?: { authInfo?: AuthInfo }) => void;
     sessionId?: string;
@@ -48,7 +48,7 @@ export class InMemoryTransport implements Transport {
         try {
             await other?.close();
         } finally {
-            this.onclose?.();
+            await this.onclose?.();
         }
     }
 

packages/core/test/inMemory.test.ts

@@ -103,8 +103,12 @@ describe('InMemoryTransport', () => {
         let clientCloseCount = 0;
         let serverCloseCount = 0;
 
-        clientTransport.onclose = () => clientCloseCount++;
-        serverTransport.onclose = () => serverCloseCount++;
+        clientTransport.onclose = () => {
+            clientCloseCount++;
+        };
+        serverTransport.onclose = () => {
+            serverCloseCount++;
+        };
 
         await clientTransport.close();
 
@@ -114,7 +118,9 @@ describe('InMemoryTransport', () => {
 
     test('should handle double close idempotently', async () => {
         let clientCloseCount = 0;
-        clientTransport.onclose = () => clientCloseCount++;
+        clientTransport.onclose = () => {
+            clientCloseCount++;
+        };
 
         await clientTransport.close();
         await clientTransport.close();
@@ -126,8 +132,12 @@ describe('InMemoryTransport', () => {
         let clientCloseCount = 0;
         let serverCloseCount = 0;
 
-        clientTransport.onclose = () => clientCloseCount++;
-        serverTransport.onclose = () => serverCloseCount++;
+        clientTransport.onclose = () => {
+            clientCloseCount++;
+        };
+        serverTransport.onclose = () => {
+            serverCloseCount++;
+        };
 
         await Promise.all([clientTransport.close(), serverTransport.close()]);
 
@@ -137,7 +147,9 @@ describe('InMemoryTransport', () => {
 
     test('should fire onclose even if peer onclose throws', async () => {
         let clientCloseCount = 0;
-        clientTransport.onclose = () => clientCloseCount++;
+        clientTransport.onclose = () => {
+            clientCloseCount++;
+        };
         serverTransport.onclose = () => {
             throw new Error('boom');
         };

packages/core/test/shared/protocol.test.ts

@@ -69,7 +69,7 @@ interface TestProtocolInternals {
 
 // Mock Transport class
 class MockTransport implements Transport {
-    onclose?: () => void;
+    onclose?: () => void | Promise<void>;
     onerror?: (error: Error) => void;
     onmessage?: (message: unknown) => void;