@ai-sdk/mcp 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/mcp",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "pkce-challenge": "^5.0.1",
-    "@ai-sdk/provider": "4.0.0",
-    "@ai-sdk/provider-utils": "5.0.0"
+    "@ai-sdk/provider-utils": "5.0.0",
+    "@ai-sdk/provider": "4.0.0"
   },
   "devDependencies": {
     "@types/node": "22.19.19",

package/src/index.ts

@@ -27,6 +27,7 @@ export type {
   Configuration,
   ElicitationRequest,
   ElicitResult,
+  InitializeResult,
   ListToolsResult,
   McpProviderMetadata,
   ClientCapabilities as MCPClientCapabilities,

package/src/tool/mcp-client.ts

@@ -60,6 +60,7 @@ import {
   type ToolSchemas,
   type ToolMeta,
   type McpProviderMetadata,
+  type InitializeResult,
 } from './types';
 const CLIENT_VERSION = '1.0.0';
 
@@ -100,6 +101,12 @@ export interface MCPClientConfig {
   transport: MCPTransportConfig | MCPTransport;
   /** Optional callback for uncaught errors */
   onUncaughtError?: (error: unknown) => void;
+  /**
+   * Initialize result from a previous MCP session. When provided, the client
+   * starts the transport and reuses this metadata without sending a new
+   * initialize request.
+   */
+  initialInitializeResult?: InitializeResult;
   /** Optional client name, defaults to 'ai-sdk-mcp-client' */
   clientName?: string;
   /**
@@ -133,6 +140,12 @@ export interface MCPClient {
    */
   readonly serverInfo: Configuration;
 
+  /**
+   * The full initialize result used by this client, either from the server
+   * during initialization or from `initialInitializeResult`.
+   */
+  readonly initializeResult: InitializeResult;
+
   /**
    * Optional instructions provided by the server during the initialize handshake.
    *
@@ -220,7 +233,7 @@ export interface MCPClient {
  *
  * Not supported:
  * - Accepting notifications
- * - Session management (when passing a sessionId to an instance of the Streamable HTTP transport)
+ * - Automatic session persistence for Streamable HTTP transport
  * - Resumable SSE streams
  */
 class DefaultMCPClient implements MCPClient {
@@ -228,6 +241,7 @@ class DefaultMCPClient implements MCPClient {
   private onUncaughtError?: (error: unknown) => void;
   private clientInfo: ClientConfiguration;
   private clientCapabilities: ClientCapabilities;
+  private initialInitializeResult?: InitializeResult;
   private requestMessageId = 0;
   private responseHandlers: Map<
     number,
@@ -235,6 +249,11 @@ class DefaultMCPClient implements MCPClient {
   > = new Map();
   private serverCapabilities: ServerCapabilities = {};
   private _serverInfo: Configuration = { name: '', version: '' };
+  private _initializeResult: InitializeResult = {
+    protocolVersion: LATEST_PROTOCOL_VERSION,
+    capabilities: {},
+    serverInfo: this._serverInfo,
+  };
   private _serverInstructions?: string;
   private isClosed = true;
   private elicitationRequestHandler?: (
@@ -248,9 +267,11 @@ class DefaultMCPClient implements MCPClient {
     version = CLIENT_VERSION,
     onUncaughtError,
     capabilities,
+    initialInitializeResult,
   }: MCPClientConfig) {
     this.onUncaughtError = onUncaughtError;
     this.clientCapabilities = capabilities ?? {};
+    this.initialInitializeResult = initialInitializeResult;
 
     if (isCustomMcpTransport(transportConfig)) {
       this.transport = transportConfig;
@@ -287,6 +308,10 @@ class DefaultMCPClient implements MCPClient {
     return this._serverInfo;
   }
 
+  get initializeResult(): InitializeResult {
+    return this._initializeResult;
+  }
+
   get instructions(): string | undefined {
     return this._serverInstructions;
   }
@@ -296,6 +321,14 @@ class DefaultMCPClient implements MCPClient {
       await this.transport.start();
       this.isClosed = false;
 
+      if (this.initialInitializeResult) {
+        const result = InitializeResultSchema.parse(
+          this.initialInitializeResult,
+        );
+        this.applyInitializeResult(result);
+        return this;
+      }
+
       const result = await this.request({
         request: {
           method: 'initialize',
@@ -314,20 +347,7 @@ class DefaultMCPClient implements MCPClient {
         });
       }
 
-      if (!SUPPORTED_PROTOCOL_VERSIONS.includes(result.protocolVersion)) {
-        throw new MCPClientError({
-          message: `Server's protocol version is not supported: ${result.protocolVersion}`,
-        });
-      }
-
-      this.serverCapabilities = result.capabilities;
-      this._serverInfo = result.serverInfo;
-      if (this.transport.setProtocolVersion) {
-        this.transport.setProtocolVersion(result.protocolVersion);
-      } else {
-        this.transport.protocolVersion = result.protocolVersion;
-      }
-      this._serverInstructions = result.instructions;
+      this.applyInitializeResult(result);
 
       // Complete initialization handshake:
       await this.notification({
@@ -341,6 +361,24 @@ class DefaultMCPClient implements MCPClient {
     }
   }
 
+  private applyInitializeResult(result: InitializeResult): void {
+    if (!SUPPORTED_PROTOCOL_VERSIONS.includes(result.protocolVersion)) {
+      throw new MCPClientError({
+        message: `Server's protocol version is not supported: ${result.protocolVersion}`,
+      });
+    }
+
+    this.serverCapabilities = result.capabilities;
+    this._serverInfo = result.serverInfo;
+    this._initializeResult = result;
+    if (this.transport.setProtocolVersion) {
+      this.transport.setProtocolVersion(result.protocolVersion);
+    } else {
+      this.transport.protocolVersion = result.protocolVersion;
+    }
+    this._serverInstructions = result.instructions;
+  }
+
   async close(): Promise<void> {
     if (this.isClosed) return;
     await this.transport?.close();

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

@@ -43,6 +43,9 @@ export class HttpMCPTransport implements MCPTransport {
   private redirectMode: RequestRedirect;
   private fetchFn: FetchFunction;
   private authPromise?: Promise<AuthResult>;
+  private onSessionIdChange?: (sessionId: string | undefined) => void;
+  private onSessionExpired?: (sessionId: string) => void;
+  private terminateSessionOnClose: boolean;
 
   // Inbound SSE resumption and reconnection state
   private lastInboundEventId?: string;
@@ -64,18 +67,33 @@ export class HttpMCPTransport implements MCPTransport {
     headers,
     authProvider,
     redirect = 'error',
+    initialSessionId,
+    initialProtocolVersion,
+    onSessionIdChange,
+    onSessionExpired,
+    terminateSessionOnClose = true,
     fetch: fetchFn,
   }: {
     url: string;
     headers?: Record<string, string>;
     authProvider?: OAuthClientProvider;
     redirect?: 'follow' | 'error';
+    initialSessionId?: string;
+    initialProtocolVersion?: string;
+    onSessionIdChange?: (sessionId: string | undefined) => void;
+    onSessionExpired?: (sessionId: string) => void;
+    terminateSessionOnClose?: boolean;
     fetch?: FetchFunction;
   }) {
     this.url = new URL(url);
     this.headers = headers;
     this.authProvider = authProvider;
     this.redirectMode = redirect;
+    this.sessionId = initialSessionId;
+    this.protocolVersion = initialProtocolVersion;
+    this.onSessionIdChange = onSessionIdChange;
+    this.onSessionExpired = onSessionExpired;
+    this.terminateSessionOnClose = terminateSessionOnClose;
     this.fetchFn = fetchFn ?? globalThis.fetch;
   }
 
@@ -83,16 +101,20 @@ export class HttpMCPTransport implements MCPTransport {
     this.protocolVersion = version;
   }
 
-  private async commonHeaders(
-    base: Record<string, string>,
-  ): Promise<Record<string, string>> {
+  private async commonHeaders({
+    base,
+    includeSessionId = true,
+  }: {
+    base: Record<string, string>;
+    includeSessionId?: boolean;
+  }): Promise<Record<string, string>> {
     const headers: Record<string, string> = {
       ...this.headers,
       ...base,
       'mcp-protocol-version': this.protocolVersion ?? LATEST_PROTOCOL_VERSION,
     };
 
-    if (this.sessionId) {
+    if (includeSessionId && this.sessionId) {
       headers['mcp-session-id'] = this.sessionId;
     }
 
@@ -110,6 +132,30 @@ export class HttpMCPTransport implements MCPTransport {
     );
   }
 
+  private setSessionId(sessionId: string | undefined): void {
+    if (this.sessionId === sessionId) {
+      return;
+    }
+
+    this.sessionId = sessionId;
+    this.onSessionIdChange?.(sessionId);
+  }
+
+  private applySessionIdFromResponse(response: Response): void {
+    const sessionId = response.headers.get('mcp-session-id');
+    if (sessionId) {
+      this.setSessionId(sessionId);
+    }
+  }
+
+  private expireSessionId(sessionId: string): void {
+    if (this.sessionId === sessionId) {
+      this.setSessionId(undefined);
+    }
+
+    this.onSessionExpired?.(sessionId);
+  }
+
   /**
    * Runs a single OAuth recovery flow for concurrent 401 responses.
    */
@@ -148,10 +194,11 @@ export class HttpMCPTransport implements MCPTransport {
     try {
       if (
         this.sessionId &&
+        this.terminateSessionOnClose &&
         this.abortController &&
         !this.abortController.signal.aborted
       ) {
-        const headers = await this.commonHeaders({});
+        const headers = await this.commonHeaders({ base: {} });
         await this.fetchFn(this.url.href, {
           method: 'DELETE',
           headers,
@@ -168,9 +215,17 @@ export class HttpMCPTransport implements MCPTransport {
   async send(message: JSONRPCMessage): Promise<void> {
     const attempt = async (triedAuth: boolean = false): Promise<void> => {
       try {
+        const isInitializeRequest =
+          'method' in message && message.method === 'initialize';
+        const sessionIdForRequest = isInitializeRequest
+          ? undefined
+          : this.sessionId;
         const headers = await this.commonHeaders({
-          'Content-Type': 'application/json',
-          Accept: 'application/json, text/event-stream',
+          base: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+          },
+          includeSessionId: !isInitializeRequest,
         });
 
         const init = {
@@ -183,10 +238,7 @@ export class HttpMCPTransport implements MCPTransport {
 
         const response = await this.fetchFn(this.url.href, init);
 
-        const sessionId = response.headers.get('mcp-session-id');
-        if (sessionId) {
-          this.sessionId = sessionId;
-        }
+        this.applySessionIdFromResponse(response);
 
         if (response.status === 401 && this.authProvider && !triedAuth) {
           this.resourceMetadataUrl = extractResourceMetadataUrl(response);
@@ -217,10 +269,16 @@ export class HttpMCPTransport implements MCPTransport {
           const text = await response.text().catch(() => null);
           let errorMessage = `MCP HTTP Transport Error: POSTing to endpoint (HTTP ${response.status}): ${text}`;
 
-          // 404 since this is a GET request which the server does not support
           if (response.status === 404) {
-            errorMessage +=
-              '. This server does not support HTTP transport. Try using `sse` transport instead';
+            if (sessionIdForRequest) {
+              this.expireSessionId(sessionIdForRequest);
+
+              errorMessage +=
+                '. The MCP session expired. Create a new client without `initialSessionId` to start a fresh session';
+            } else {
+              errorMessage +=
+                '. This server does not support HTTP transport. Try using `sse` transport instead';
+            }
           }
 
           const error = new MCPClientError({
@@ -356,8 +414,11 @@ export class HttpMCPTransport implements MCPTransport {
     resumeToken?: string,
   ): Promise<void> {
     try {
+      const sessionIdForRequest = this.sessionId;
       const headers = await this.commonHeaders({
-        Accept: 'text/event-stream',
+        base: {
+          Accept: 'text/event-stream',
+        },
       });
       if (resumeToken) {
         headers['last-event-id'] = resumeToken;
@@ -370,10 +431,7 @@ export class HttpMCPTransport implements MCPTransport {
         redirect: this.redirectMode,
       });
 
-      const sessionId = response.headers.get('mcp-session-id');
-      if (sessionId) {
-        this.sessionId = sessionId;
-      }
+      this.applySessionIdFromResponse(response);
 
       if (response.status === 401 && this.authProvider && !triedAuth) {
         this.resourceMetadataUrl = extractResourceMetadataUrl(response);
@@ -396,6 +454,10 @@ export class HttpMCPTransport implements MCPTransport {
       }
 
       if (!response.ok || !response.body) {
+        if (response.status === 404 && sessionIdForRequest) {
+          this.expireSessionId(sessionIdForRequest);
+        }
+
         const error = new MCPClientError({
           message: `MCP HTTP Transport Error: GET SSE failed: ${response.status} ${response.statusText}`,
           statusCode: response.status,

package/src/tool/mcp-transport.ts

@@ -78,6 +78,42 @@ export type MCPTransportConfig = {
    */
   redirect?: 'follow' | 'error';
 
+  /**
+   * Initial MCP session id to send with resumed Streamable HTTP requests after
+   * initialization.
+   * Only used by the HTTP transport.
+   */
+  initialSessionId?: string;
+
+  /**
+   * Initial MCP protocol version to send before initialize negotiates one.
+   * Only used by the HTTP transport.
+   */
+  initialProtocolVersion?: string;
+
+  /**
+   * Called when the Streamable HTTP server creates, changes, or clears the MCP
+   * session id.
+   * Only used by the HTTP transport.
+   */
+  onSessionIdChange?: (sessionId: string | undefined) => void;
+
+  /**
+   * Called when a Streamable HTTP request returns 404 for an existing MCP
+   * session id. The transport clears the session id before reporting the
+   * underlying HTTP error.
+   * Only used by the HTTP transport.
+   */
+  onSessionExpired?: (sessionId: string) => void;
+
+  /**
+   * Whether close() should send DELETE for the current MCP session id.
+   * Set to false when the application intends to reattach to the session later.
+   * Only used by the HTTP transport.
+   * @default true
+   */
+  terminateSessionOnClose?: boolean;
+
   /**
    * Optional custom fetch implementation to use for HTTP requests.
    * Useful for runtimes that need a request-local fetch.

package/src/tool/oauth-types.ts

@@ -44,63 +44,57 @@ export const OAuthTokensSchema = z
   })
   .strip();
 
-export const OAuthProtectedResourceMetadataSchema = z
-  .object({
-    resource: z.string().url(),
-    authorization_servers: z.array(SafeUrlSchema).optional(),
-    jwks_uri: z.string().url().optional(),
-    scopes_supported: z.array(z.string()).optional(),
-    bearer_methods_supported: z.array(z.string()).optional(),
-    resource_signing_alg_values_supported: z.array(z.string()).optional(),
-    resource_name: z.string().optional(),
-    resource_documentation: z.string().optional(),
-    resource_policy_uri: z.string().url().optional(),
-    resource_tos_uri: z.string().url().optional(),
-    tls_client_certificate_bound_access_tokens: z.boolean().optional(),
-    authorization_details_types_supported: z.array(z.string()).optional(),
-    dpop_signing_alg_values_supported: z.array(z.string()).optional(),
-    dpop_bound_access_tokens_required: z.boolean().optional(),
-  })
-  .passthrough();
+export const OAuthProtectedResourceMetadataSchema = z.looseObject({
+  resource: z.string().url(),
+  authorization_servers: z.array(SafeUrlSchema).optional(),
+  jwks_uri: z.string().url().optional(),
+  scopes_supported: z.array(z.string()).optional(),
+  bearer_methods_supported: z.array(z.string()).optional(),
+  resource_signing_alg_values_supported: z.array(z.string()).optional(),
+  resource_name: z.string().optional(),
+  resource_documentation: z.string().optional(),
+  resource_policy_uri: z.string().url().optional(),
+  resource_tos_uri: z.string().url().optional(),
+  tls_client_certificate_bound_access_tokens: z.boolean().optional(),
+  authorization_details_types_supported: z.array(z.string()).optional(),
+  dpop_signing_alg_values_supported: z.array(z.string()).optional(),
+  dpop_bound_access_tokens_required: z.boolean().optional(),
+});
 
-export const OAuthMetadataSchema = z
-  .object({
-    issuer: z.string(),
-    authorization_endpoint: SafeUrlSchema,
-    token_endpoint: SafeUrlSchema,
-    registration_endpoint: SafeUrlSchema.optional(),
-    scopes_supported: z.array(z.string()).optional(),
-    response_types_supported: z.array(z.string()),
-    grant_types_supported: z.array(z.string()).optional(),
-    code_challenge_methods_supported: z.array(z.string()),
-    token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
-    token_endpoint_auth_signing_alg_values_supported: z
-      .array(z.string())
-      .optional(),
-  })
-  .passthrough();
+export const OAuthMetadataSchema = z.looseObject({
+  issuer: z.string(),
+  authorization_endpoint: SafeUrlSchema,
+  token_endpoint: SafeUrlSchema,
+  registration_endpoint: SafeUrlSchema.optional(),
+  scopes_supported: z.array(z.string()).optional(),
+  response_types_supported: z.array(z.string()),
+  grant_types_supported: z.array(z.string()).optional(),
+  code_challenge_methods_supported: z.array(z.string()),
+  token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
+  token_endpoint_auth_signing_alg_values_supported: z
+    .array(z.string())
+    .optional(),
+});
 
 /**
  * OpenID Connect Discovery 1.0 Provider Metadata
  * see: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
  */
-export const OpenIdProviderMetadataSchema = z
-  .object({
-    issuer: z.string(),
-    authorization_endpoint: SafeUrlSchema,
-    token_endpoint: SafeUrlSchema,
-    userinfo_endpoint: SafeUrlSchema.optional(),
-    jwks_uri: SafeUrlSchema,
-    registration_endpoint: SafeUrlSchema.optional(),
-    scopes_supported: z.array(z.string()).optional(),
-    response_types_supported: z.array(z.string()),
-    grant_types_supported: z.array(z.string()).optional(),
-    subject_types_supported: z.array(z.string()),
-    id_token_signing_alg_values_supported: z.array(z.string()),
-    claims_supported: z.array(z.string()).optional(),
-    token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
-  })
-  .passthrough();
+export const OpenIdProviderMetadataSchema = z.looseObject({
+  issuer: z.string(),
+  authorization_endpoint: SafeUrlSchema,
+  token_endpoint: SafeUrlSchema,
+  userinfo_endpoint: SafeUrlSchema.optional(),
+  jwks_uri: SafeUrlSchema,
+  registration_endpoint: SafeUrlSchema.optional(),
+  scopes_supported: z.array(z.string()).optional(),
+  response_types_supported: z.array(z.string()),
+  grant_types_supported: z.array(z.string()).optional(),
+  subject_types_supported: z.array(z.string()),
+  id_token_signing_alg_values_supported: z.array(z.string()),
+  claims_supported: z.array(z.string()).optional(),
+  token_endpoint_auth_methods_supported: z.array(z.string()).optional(),
+});
 
 /**
  * OpenID Connect Discovery metadata that may include OAuth 2.0 fields