@ai-sdk/mcp 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ai-sdk/mcp
 
+## 2.0.1
+
+### Patch Changes
+
+- 241a8c5: Add Streamable HTTP session hooks, cached initialize metadata, and detach-on-close support for reattaching to MCP sessions.
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -76,7 +76,7 @@ const result = streamText({
   model: 'openai/gpt-5.4',
   tools: await mcpClient.tools(),
   prompt: 'Use the available tools to answer the user question.',
-  onFinish: async () => {
+  onEnd: async () => {
     await mcpClient.close();
   },
 });
@@ -93,12 +93,35 @@ HTTP is recommended for production deployments:
 ```ts
 import { createMCPClient } from '@ai-sdk/mcp';
 
+const savedSession = await loadMcpSession();
+let currentSessionId = savedSession?.sessionId;
+
 const mcpClient = await createMCPClient({
   transport: {
     type: 'http',
     url: 'https://your-server.com/mcp',
+    initialSessionId: savedSession?.sessionId,
+    initialProtocolVersion: savedSession?.initializeResult.protocolVersion,
+    terminateSessionOnClose: false,
+    onSessionIdChange: sessionId => {
+      currentSessionId = sessionId;
+    },
+    onSessionExpired: sessionId => {
+      if (currentSessionId === sessionId) {
+        currentSessionId = undefined;
+        void clearMcpSession();
+      }
+    },
   },
+  initialInitializeResult: savedSession?.initializeResult,
 });
+
+if (currentSessionId) {
+  await saveMcpSession({
+    sessionId: currentSessionId,
+    initializeResult: mcpClient.initializeResult,
+  });
+}
 ```
 
 SSE is also supported for MCP servers that use Server-Sent Events:

package/dist/index.d.ts

@@ -273,6 +273,37 @@ type MCPTransportConfig = {
      * @default 'error'
      */
     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.
@@ -337,6 +368,34 @@ declare const ClientCapabilitiesSchema: z.ZodObject<{
     }, z.core.$loose>>;
 }, z.core.$loose>;
 type ClientCapabilities = z.infer<typeof ClientCapabilitiesSchema>;
+declare const InitializeResultSchema: z.ZodObject<{
+    _meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    protocolVersion: z.ZodString;
+    capabilities: z.ZodObject<{
+        experimental: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+        logging: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+        prompts: z.ZodOptional<z.ZodObject<{
+            listChanged: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        resources: z.ZodOptional<z.ZodObject<{
+            subscribe: z.ZodOptional<z.ZodBoolean>;
+            listChanged: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        tools: z.ZodOptional<z.ZodObject<{
+            listChanged: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+        elicitation: z.ZodOptional<z.ZodObject<{
+            applyDefaults: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    serverInfo: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+type InitializeResult = z.infer<typeof InitializeResultSchema>;
 type PaginatedRequest = Request & {
     params?: BaseParams & {
         cursor?: string;
@@ -513,6 +572,12 @@ 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;
     /**
@@ -537,6 +602,11 @@ interface MCPClient {
      * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#implementation
      */
     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.
      *
@@ -651,4 +721,4 @@ declare function readMCPAppResource({ client, uri, options, }: {
     options?: RequestOptions;
 }): Promise<MCPAppResource>;
 
-export { type CallToolResult, type Configuration, type ElicitResult, ElicitResultSchema, type ElicitationRequest, ElicitationRequestSchema, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ListToolsResult, type MCPAppResource, type MCPAppResourceCSP, type MCPAppResourceMeta, type MCPClient, type ClientCapabilities as MCPClientCapabilities, type MCPClientConfig, type MCPTransport, MCP_APP_MIME_TYPE, type McpProviderMetadata, type OAuthAuthorizationServerInformation, type OAuthClientInformation, type OAuthClientMetadata, type OAuthClientProvider, type OAuthTokens, UnauthorizedError, auth, createMCPClient, type MCPClient as experimental_MCPClient, type ClientCapabilities as experimental_MCPClientCapabilities, type MCPClientConfig as experimental_MCPClientConfig, createMCPClient as experimental_createMCPClient, mcpAppClientCapabilities, readMCPAppResource, splitMCPAppTools };
+export { type CallToolResult, type Configuration, type ElicitResult, ElicitResultSchema, type ElicitationRequest, ElicitationRequestSchema, type InitializeResult, type JSONRPCError, type JSONRPCMessage, type JSONRPCNotification, type JSONRPCRequest, type JSONRPCResponse, type ListToolsResult, type MCPAppResource, type MCPAppResourceCSP, type MCPAppResourceMeta, type MCPClient, type ClientCapabilities as MCPClientCapabilities, type MCPClientConfig, type MCPTransport, MCP_APP_MIME_TYPE, type McpProviderMetadata, type OAuthAuthorizationServerInformation, type OAuthClientInformation, type OAuthClientMetadata, type OAuthClientProvider, type OAuthTokens, UnauthorizedError, auth, createMCPClient, type MCPClient as experimental_MCPClient, type ClientCapabilities as experimental_MCPClientCapabilities, type MCPClientConfig as experimental_MCPClientConfig, createMCPClient as experimental_createMCPClient, mcpAppClientCapabilities, readMCPAppResource, splitMCPAppTools };

package/dist/index.js

@@ -1503,6 +1503,11 @@ var HttpMCPTransport = class {
     headers,
     authProvider,
     redirect = "error",
+    initialSessionId,
+    initialProtocolVersion,
+    onSessionIdChange,
+    onSessionExpired,
+    terminateSessionOnClose = true,
     fetch: fetchFn
   }) {
     this.inboundReconnectAttempts = 0;
@@ -1516,19 +1521,27 @@ var HttpMCPTransport = class {
     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 != null ? fetchFn : globalThis.fetch;
   }
   setProtocolVersion(version) {
     this.protocolVersion = version;
   }
-  async commonHeaders(base) {
+  async commonHeaders({
+    base,
+    includeSessionId = true
+  }) {
     var _a3;
     const headers = {
       ...this.headers,
       ...base,
       "mcp-protocol-version": (_a3 = this.protocolVersion) != null ? _a3 : LATEST_PROTOCOL_VERSION
     };
-    if (this.sessionId) {
+    if (includeSessionId && this.sessionId) {
       headers["mcp-session-id"] = this.sessionId;
     }
     if (this.authProvider) {
@@ -1543,6 +1556,27 @@ var HttpMCPTransport = class {
       getRuntimeEnvironmentUserAgent2()
     );
   }
+  setSessionId(sessionId) {
+    var _a3;
+    if (this.sessionId === sessionId) {
+      return;
+    }
+    this.sessionId = sessionId;
+    (_a3 = this.onSessionIdChange) == null ? void 0 : _a3.call(this, sessionId);
+  }
+  applySessionIdFromResponse(response) {
+    const sessionId = response.headers.get("mcp-session-id");
+    if (sessionId) {
+      this.setSessionId(sessionId);
+    }
+  }
+  expireSessionId(sessionId) {
+    var _a3;
+    if (this.sessionId === sessionId) {
+      this.setSessionId(void 0);
+    }
+    (_a3 = this.onSessionExpired) == null ? void 0 : _a3.call(this, sessionId);
+  }
   /**
    * Runs a single OAuth recovery flow for concurrent 401 responses.
    */
@@ -1574,8 +1608,8 @@ var HttpMCPTransport = class {
     var _a3, _b3, _c;
     (_a3 = this.inboundSseConnection) == null ? void 0 : _a3.close();
     try {
-      if (this.sessionId && this.abortController && !this.abortController.signal.aborted) {
-        const headers = await this.commonHeaders({});
+      if (this.sessionId && this.terminateSessionOnClose && this.abortController && !this.abortController.signal.aborted) {
+        const headers = await this.commonHeaders({ base: {} });
         await this.fetchFn(this.url.href, {
           method: "DELETE",
           headers,
@@ -1592,9 +1626,14 @@ var HttpMCPTransport = class {
     const attempt = async (triedAuth = false) => {
       var _a3, _b3, _c, _d, _e, _f, _g;
       try {
+        const isInitializeRequest = "method" in message && message.method === "initialize";
+        const sessionIdForRequest = isInitializeRequest ? void 0 : 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 = {
           method: "POST",
@@ -1604,10 +1643,7 @@ var HttpMCPTransport = class {
           redirect: this.redirectMode
         };
         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);
           try {
@@ -1632,7 +1668,12 @@ var HttpMCPTransport = class {
           const text = await response.text().catch(() => null);
           let errorMessage = `MCP HTTP Transport Error: POSTing to endpoint (HTTP ${response.status}): ${text}`;
           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 error2 = new MCPClientError({
             message: errorMessage,
@@ -1749,8 +1790,11 @@ var HttpMCPTransport = class {
   async openInboundSse(triedAuth = false, resumeToken) {
     var _a3, _b3, _c, _d, _e, _f;
     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;
@@ -1761,10 +1805,7 @@ var HttpMCPTransport = class {
         signal: (_a3 = this.abortController) == null ? void 0 : _a3.signal,
         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);
         try {
@@ -1784,6 +1825,9 @@ var HttpMCPTransport = class {
         return;
       }
       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,
@@ -2005,15 +2049,22 @@ var DefaultMCPClient = class {
     clientName = name3 != null ? name3 : "ai-sdk-mcp-client",
     version = CLIENT_VERSION,
     onUncaughtError,
-    capabilities
+    capabilities,
+    initialInitializeResult
   }) {
     this.requestMessageId = 0;
     this.responseHandlers = /* @__PURE__ */ new Map();
     this.serverCapabilities = {};
     this._serverInfo = { name: "", version: "" };
+    this._initializeResult = {
+      protocolVersion: LATEST_PROTOCOL_VERSION,
+      capabilities: {},
+      serverInfo: this._serverInfo
+    };
     this.isClosed = true;
     this.onUncaughtError = onUncaughtError;
     this.clientCapabilities = capabilities != null ? capabilities : {};
+    this.initialInitializeResult = initialInitializeResult;
     if (isCustomMcpTransport(transportConfig)) {
       this.transport = transportConfig;
     } else {
@@ -2044,6 +2095,9 @@ var DefaultMCPClient = class {
   get serverInfo() {
     return this._serverInfo;
   }
+  get initializeResult() {
+    return this._initializeResult;
+  }
   get instructions() {
     return this._serverInstructions;
   }
@@ -2051,6 +2105,13 @@ var DefaultMCPClient = class {
     try {
       await this.transport.start();
       this.isClosed = false;
+      if (this.initialInitializeResult) {
+        const result2 = InitializeResultSchema.parse(
+          this.initialInitializeResult
+        );
+        this.applyInitializeResult(result2);
+        return this;
+      }
       const result = await this.request({
         request: {
           method: "initialize",
@@ -2067,19 +2128,7 @@ var DefaultMCPClient = class {
           message: "Server sent invalid initialize result"
         });
       }
-      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);
       await this.notification({
         method: "notifications/initialized"
       });
@@ -2089,6 +2138,22 @@ var DefaultMCPClient = class {
       throw error;
     }
   }
+  applyInitializeResult(result) {
+    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() {
     var _a3;
     if (this.isClosed) return;