@ai-sdk/mcp 2.0.18 → 2.0.20

package/dist/mcp-stdio/index.d.ts

@@ -36,6 +36,30 @@ type JSONRPCMessage = z.infer<typeof JSONRPCMessageSchema>;
  * Transport interface for MCP (Model Context Protocol) communication.
  * Maps to the `Transport` interface in the MCP spec.
  */
+type MCPTransportSendOptions = {
+    /**
+     * Cancels the transport operation for this message.
+     */
+    signal?: AbortSignal;
+    /**
+     * Associates an outgoing message with an incoming request.
+     */
+    relatedRequestId?: string | number;
+    /**
+     * Resumes a previously interrupted request.
+     */
+    resumptionToken?: string;
+    /**
+     * Receives updated resumption tokens from transports that support them.
+     */
+    onresumptiontoken?: (token: string) => void;
+};
+type MCPTransportCloseOptions = {
+    /**
+     * Cancels transport cleanup.
+     */
+    signal?: AbortSignal;
+};
 interface MCPTransport {
     /**
      * Initialize and start the transport
@@ -44,12 +68,14 @@ interface MCPTransport {
     /**
      * Send a JSON-RPC message through the transport
      * @param message The JSON-RPC message to send
+     * @param options Optional request-scoped cancellation options
      */
-    send(message: JSONRPCMessage): Promise<void>;
+    send(message: JSONRPCMessage, options?: MCPTransportSendOptions): Promise<void>;
     /**
      * Clean up and close the transport
+     * @param options Optional cancellation options for transport cleanup
      */
-    close(): Promise<void>;
+    close(options?: MCPTransportCloseOptions): Promise<void>;
     /**
      * Event handler for transport closure
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/mcp",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -33,7 +33,7 @@
   "dependencies": {
     "pkce-challenge": "^5.0.1",
     "@ai-sdk/provider": "4.0.4",
-    "@ai-sdk/provider-utils": "5.0.14"
+    "@ai-sdk/provider-utils": "5.0.16"
   },
   "devDependencies": {
     "@types/node": "22.19.19",
@@ -41,7 +41,7 @@
     "typescript": "5.8.3",
     "vitest": "^4.1.6",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.0",
+    "@ai-sdk/test-server": "2.0.1",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {

package/src/index.ts

@@ -49,7 +49,11 @@ export type {
   OAuthClientMetadata,
   OAuthTokens,
 } from './tool/oauth-types';
-export type { MCPTransport } from './tool/mcp-transport';
+export type {
+  MCPTransport,
+  MCPTransportCloseOptions,
+  MCPTransportSendOptions,
+} from './tool/mcp-transport';
 
 /**
  * @deprecated Use `createMCPClient` instead. Will be removed in a future version.

package/src/tool/mcp-client.ts

@@ -16,6 +16,7 @@ import type { z } from 'zod/v4';
 import { MCPClientError } from '../error/mcp-client-error';
 import type {
   JSONRPCError,
+  JSONRPCMessage,
   JSONRPCNotification,
   JSONRPCRequest,
   JSONRPCResponse,
@@ -144,6 +145,56 @@ function prepareMaxRetries(maxRetries: number | undefined): number {
   return maxRetries;
 }
 
+function getEffectiveTimeout({
+  timeout,
+  maxTotalTimeout,
+}: RequestOptions): number | undefined {
+  if (timeout == null) {
+    return maxTotalTimeout;
+  }
+
+  if (maxTotalTimeout == null) {
+    return timeout;
+  }
+
+  return Math.min(timeout, maxTotalTimeout);
+}
+
+function waitForAbort<T>(
+  promise: Promise<T>,
+  signal: AbortSignal | undefined,
+): Promise<T> {
+  if (signal == null) {
+    return promise;
+  }
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      signal.removeEventListener('abort', onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(signal.reason);
+    };
+
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise
+      .then(value => {
+        cleanup();
+        resolve(value);
+      })
+      .catch(error => {
+        cleanup();
+        reject(error);
+      });
+  });
+}
+
 function mcpToModelOutput({
   output,
 }: {
@@ -179,6 +230,10 @@ function mcpToModelOutput({
 export interface MCPClientConfig {
   /** Transport configuration for connecting to the MCP server */
   transport: MCPTransportConfig | MCPTransport;
+  /**
+   * Options that bound or cancel transport startup and the initialize request.
+   */
+  initializationOptions?: RequestOptions;
   /** Optional callback for uncaught errors */
   onUncaughtError?: (error: unknown) => void;
   /**
@@ -338,6 +393,7 @@ class DefaultMCPClient implements MCPClient {
   private clientInfo: ClientConfiguration;
   private clientCapabilities: ClientCapabilities;
   private initialInitializeResult?: InitializeResult;
+  private initializationOptions?: RequestOptions;
   private requestMessageId = 0;
   private responseHandlers: Map<
     number,
@@ -365,11 +421,13 @@ class DefaultMCPClient implements MCPClient {
     maxRetries,
     capabilities,
     initialInitializeResult,
+    initializationOptions,
   }: MCPClientConfig) {
     this.onUncaughtError = onUncaughtError;
     this.maxRetries = prepareMaxRetries(maxRetries);
     this.clientCapabilities = capabilities ?? {};
     this.initialInitializeResult = initialInitializeResult;
+    this.initializationOptions = initializationOptions;
 
     if (isCustomMcpTransport(transportConfig)) {
       this.transport = transportConfig;
@@ -415,9 +473,34 @@ class DefaultMCPClient implements MCPClient {
   }
 
   async init(): Promise<this> {
+    const externalSignal = this.initializationOptions?.signal;
+    const timeout = this.initializationOptions
+      ? getEffectiveTimeout(this.initializationOptions)
+      : undefined;
+    const timeoutController =
+      timeout == null ? undefined : new AbortController();
+    const signal =
+      externalSignal == null
+        ? timeoutController?.signal
+        : timeoutController == null
+          ? externalSignal
+          : AbortSignal.any([externalSignal, timeoutController.signal]);
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let timeoutError: MCPClientError | undefined;
+
+    if (timeout != null) {
+      timeoutId = setTimeout(() => {
+        timeoutError = new MCPClientError({
+          message: `MCP client initialization timed out after ${timeout}ms`,
+        });
+        timeoutController?.abort(timeoutError);
+      }, timeout);
+    }
+
     try {
-      await this.transport.start();
       this.isClosed = false;
+      signal?.throwIfAborted();
+      await waitForAbort(this.transport.start(), signal);
 
       if (this.initialInitializeResult) {
         const result = InitializeResultSchema.parse(
@@ -437,6 +520,7 @@ class DefaultMCPClient implements MCPClient {
           },
         },
         resultSchema: InitializeResultSchema,
+        options: { signal },
       });
 
       if (result === undefined) {
@@ -448,14 +532,36 @@ class DefaultMCPClient implements MCPClient {
       this.applyInitializeResult(result);
 
       // Complete initialization handshake:
-      await this.notification({
-        method: 'notifications/initialized',
-      });
+      await this.notification(
+        {
+          method: 'notifications/initialized',
+        },
+        { signal },
+      );
 
       return this;
     } catch (error) {
-      await this.close();
+      try {
+        await waitForAbort(this.transport.close({ signal }), signal);
+      } catch {}
+      this.onClose();
+
+      if (timeoutError != null) {
+        throw timeoutError;
+      }
+
+      if (externalSignal?.aborted) {
+        throw new MCPClientError({
+          message: 'MCP client initialization was aborted',
+          cause: externalSignal.reason,
+        });
+      }
+
       throw error;
+    } finally {
+      if (timeoutId != null) {
+        clearTimeout(timeoutId);
+      }
     }
   }
 
@@ -483,6 +589,16 @@ class DefaultMCPClient implements MCPClient {
     this.onClose();
   }
 
+  private send(
+    message: JSONRPCMessage,
+    signal: AbortSignal | undefined,
+  ): Promise<void> {
+    return this.transport.send(
+      message,
+      signal == null ? undefined : { signal },
+    );
+  }
+
   private assertCapability(method: string): void {
     switch (method) {
       case 'initialize':
@@ -548,6 +664,17 @@ class DefaultMCPClient implements MCPClient {
 
       const signal = options?.signal;
       signal?.throwIfAborted();
+      const timeout =
+        options == null ? undefined : getEffectiveTimeout(options);
+      const timeoutController =
+        timeout == null ? undefined : new AbortController();
+      const transportSignal =
+        signal == null
+          ? timeoutController?.signal
+          : timeoutController == null
+            ? signal
+            : AbortSignal.any([signal, timeoutController.signal]);
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
 
       const messageId = this.requestMessageId++;
       const jsonrpcRequest: JSONRPCRequest = {
@@ -568,6 +695,9 @@ class DefaultMCPClient implements MCPClient {
       const cleanup = () => {
         this.responseHandlers.delete(messageId);
         signal?.removeEventListener('abort', onAbort);
+        if (timeoutId != null) {
+          clearTimeout(timeoutId);
+        }
       };
 
       const rejectAndCleanup = (error: unknown) => {
@@ -580,6 +710,14 @@ class DefaultMCPClient implements MCPClient {
         rejectWithAbortError();
       };
 
+      const onTimeout = () => {
+        const error = new MCPClientError({
+          message: `Request timed out after ${timeout}ms`,
+        });
+        timeoutController?.abort(error);
+        rejectAndCleanup(error);
+      };
+
       this.responseHandlers.set(messageId, response => {
         if (signal?.aborted) {
           cleanup();
@@ -605,7 +743,16 @@ class DefaultMCPClient implements MCPClient {
 
       signal?.addEventListener('abort', onAbort, { once: true });
 
-      this.transport.send(jsonrpcRequest).catch(error => {
+      if (timeout != null) {
+        timeoutId = setTimeout(onTimeout, timeout);
+      }
+
+      const sendPromise =
+        transportSignal == null
+          ? this.transport.send(jsonrpcRequest)
+          : this.send(jsonrpcRequest, transportSignal);
+
+      sendPromise.catch(error => {
         rejectAndCleanup(error);
       });
     });
@@ -778,12 +925,18 @@ class DefaultMCPClient implements MCPClient {
     });
   }
 
-  private async notification(notification: Notification): Promise<void> {
+  private async notification(
+    notification: Notification,
+    options?: { signal?: AbortSignal },
+  ): Promise<void> {
     const jsonrpcNotification: JSONRPCNotification = {
       ...notification,
       jsonrpc: '2.0',
     };
-    await this.transport.send(jsonrpcNotification);
+    await waitForAbort(
+      this.send(jsonrpcNotification, options?.signal),
+      options?.signal,
+    );
   }
 
   /**

package/src/tool/mcp-http-transport.ts

@@ -189,30 +189,45 @@ export class HttpMCPTransport implements MCPTransport {
     this.startInboundSse();
   }
 
-  async close(): Promise<void> {
+  async close(options?: { signal?: AbortSignal }): Promise<void> {
     this.inboundSseConnection?.close();
+    this.abortController?.abort();
+
     try {
       if (
         this.sessionId &&
         this.terminateSessionOnClose &&
-        this.abortController &&
-        !this.abortController.signal.aborted
+        this.abortController
       ) {
+        options?.signal?.throwIfAborted();
         const headers = await this.commonHeaders({ base: {} });
+        options?.signal?.throwIfAborted();
         await this.fetchFn(this.url.href, {
           method: 'DELETE',
           headers,
-          signal: this.abortController.signal,
+          signal: options?.signal,
           redirect: this.redirectMode,
         }).catch(() => undefined);
       }
     } catch {}
 
-    this.abortController?.abort();
     this.onclose?.();
   }
 
-  async send(message: JSONRPCMessage): Promise<void> {
+  async send(
+    message: JSONRPCMessage,
+    options?: { signal?: AbortSignal },
+  ): Promise<void> {
+    options?.signal?.throwIfAborted();
+
+    const transportSignal = this.abortController?.signal;
+    const requestSignal =
+      options?.signal == null
+        ? transportSignal
+        : transportSignal == null
+          ? options.signal
+          : AbortSignal.any([transportSignal, options.signal]);
+
     const attempt = async (triedAuth: boolean = false): Promise<void> => {
       try {
         const isInitializeRequest =
@@ -232,7 +247,7 @@ export class HttpMCPTransport implements MCPTransport {
           method: 'POST',
           headers,
           body: JSON.stringify(message),
-          signal: this.abortController?.signal,
+          signal: requestSignal,
           redirect: this.redirectMode,
         } satisfies RequestInit;
 
@@ -348,7 +363,10 @@ export class HttpMCPTransport implements MCPTransport {
                 }
               }
             } catch (error) {
-              if (error instanceof Error && error.name === 'AbortError') {
+              if (
+                options?.signal?.aborted ||
+                (error instanceof Error && error.name === 'AbortError')
+              ) {
                 return;
               }
               this.onerror?.(error);
@@ -356,7 +374,10 @@ export class HttpMCPTransport implements MCPTransport {
           };
 
           void processEvents().catch(error => {
-            if (error instanceof Error && error.name === 'AbortError') {
+            if (
+              options?.signal?.aborted ||
+              (error instanceof Error && error.name === 'AbortError')
+            ) {
               return;
             }
             this.onerror?.(error);
@@ -372,6 +393,9 @@ export class HttpMCPTransport implements MCPTransport {
         this.onerror?.(error);
         throw error;
       } catch (error) {
+        if (options?.signal?.aborted) {
+          throw error;
+        }
         this.onerror?.(error);
         throw error;
       }

package/src/tool/mcp-sse-transport.ts

@@ -236,7 +236,12 @@ export class SseMCPTransport implements MCPTransport {
     this.onclose?.();
   }
 
-  async send(message: JSONRPCMessage): Promise<void> {
+  async send(
+    message: JSONRPCMessage,
+    options?: { signal?: AbortSignal },
+  ): Promise<void> {
+    options?.signal?.throwIfAborted();
+
     if (!this.endpoint || !this.connected) {
       throw new MCPClientError({
         message: 'MCP SSE Transport Error: Not connected',
@@ -244,6 +249,13 @@ export class SseMCPTransport implements MCPTransport {
     }
 
     const endpoint = this.endpoint as URL;
+    const transportSignal = this.abortController?.signal;
+    const requestSignal =
+      options?.signal == null
+        ? transportSignal
+        : transportSignal == null
+          ? options.signal
+          : AbortSignal.any([transportSignal, options.signal]);
 
     const attempt = async (triedAuth: boolean = false): Promise<void> => {
       try {
@@ -254,7 +266,7 @@ export class SseMCPTransport implements MCPTransport {
           method: 'POST',
           headers,
           body: JSON.stringify(message),
-          signal: this.abortController?.signal,
+          signal: requestSignal,
           redirect: this.redirectMode,
         };
 
@@ -289,6 +301,9 @@ export class SseMCPTransport implements MCPTransport {
           return;
         }
       } catch (error) {
+        if (options?.signal?.aborted) {
+          throw error;
+        }
         this.onerror?.(error);
         return;
       }

package/src/tool/mcp-transport.ts

@@ -9,6 +9,35 @@ import type { OAuthClientProvider } from './oauth';
  * Transport interface for MCP (Model Context Protocol) communication.
  * Maps to the `Transport` interface in the MCP spec.
  */
+export type MCPTransportSendOptions = {
+  /**
+   * Cancels the transport operation for this message.
+   */
+  signal?: AbortSignal;
+
+  /**
+   * Associates an outgoing message with an incoming request.
+   */
+  relatedRequestId?: string | number;
+
+  /**
+   * Resumes a previously interrupted request.
+   */
+  resumptionToken?: string;
+
+  /**
+   * Receives updated resumption tokens from transports that support them.
+   */
+  onresumptiontoken?: (token: string) => void;
+};
+
+export type MCPTransportCloseOptions = {
+  /**
+   * Cancels transport cleanup.
+   */
+  signal?: AbortSignal;
+};
+
 export interface MCPTransport {
   /**
    * Initialize and start the transport
@@ -18,13 +47,18 @@ export interface MCPTransport {
   /**
    * Send a JSON-RPC message through the transport
    * @param message The JSON-RPC message to send
+   * @param options Optional request-scoped cancellation options
    */
-  send(message: JSONRPCMessage): Promise<void>;
+  send(
+    message: JSONRPCMessage,
+    options?: MCPTransportSendOptions,
+  ): Promise<void>;
 
   /**
    * Clean up and close the transport
+   * @param options Optional cancellation options for transport cleanup
    */
-  close(): Promise<void>;
+  close(options?: MCPTransportCloseOptions): Promise<void>;
 
   /**
    * Event handler for transport closure