@ai-sdk/mcp 2.0.0-canary.65 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @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
+
+- 23fa161: fix(mcp): setting redirect: error for MCP transport
+- ef992f8: Remove CommonJS exports from all packages. All packages are now ESM-only (`"type": "module"`). Consumers using `require()` must switch to ESM `import` syntax.
+- 8359612: Start v7 pre-release
+
+### Patch Changes
+
+- b79094c: Add `resource_link` content type to `CallToolResultSchema` and `PromptMessageSchema` per MCP spec. Fixes hard rejection when MCP servers return `resource_link` content parts with zod ≥ 4.4.x.
+- 78e0023: fix(mcp): await addClientAuthentication in token exchange and refresh
+- b567a6c: dependency updates
+- e33ad0b: fix(mcp): add optional hook to validate authorization servers
+- e3ea484: fix(mcp): bypass outputSchema validation when tool returns isError
+- 93afb28: feat(mcp): expose server instructions to be accessible through client
+- a00d1d3: feat(mcp): allow custom fetch for HTTP and SSE transports
+- a98bf66: feat(mcp): surface 'serverInfo' exposed from the MCP server
+- 2a150f8: fix(mcp): lock first sse endpoint received via event
+- 2655da8: fix(mcp): use negotiated protocol version in transport request headers
+- 9f0e36c: trigger release for all packages after provenance setup
+- f7bc0b4: feat(mcp): expose `statusCode`, `url`, and `responseBody` on `MCPClientError` for HTTP transport failures
+
+  `MCPClientError` now carries structured HTTP context when it originates from the
+  streamable HTTP transport. This lets downstream consumers (e.g. agent frameworks
+  that need to decide whether to fall back from streamable HTTP to legacy SSE
+  transport per the MCP spec) branch on the actual response status without parsing
+  the error message string.
+
+  Fields are optional — they remain `undefined` for stdio transport errors and for
+  non-response failures (network errors, aborts).
+
+- dcefad3: fix(mcp): respond to ping requests with an empty result per JSON-RPC spec (closes #6282)
+- b44b051: fix(mcp): prevent prototype-named tools from bypassing the `schemas` allowlist
+
+  When using `client.tools({ schemas })` to expose only an explicitly allowed
+  subset of an MCP server's tools, the allowlist check used the `in` operator,
+  which also matches inherited `Object.prototype` properties. A server-advertised
+  tool named `constructor`, `toString`, `__proto__`, etc. would pass the check
+  even though the developer never defined it in `schemas`, and was then exposed to
+  the model and executable. The check now uses `Object.hasOwn`, so only
+  explicitly defined tools are returned.
+
+- f634bac: feat(mcp): add new McpProviderMetadata type
+- b9b3899: changeset for #13384
+- 1e89d62: fix(mcp): strip trailing slash from OAuth resource parameter
+- 3e0b82f: fix(mcp): support official sdk protocol version negotiation
+- 1451759: feat(mcp): deprecate name and use clientName for MCPClient
+- 7fc6bd6: Raise minimum supported Node.js version to 22. Supported versions: 22, 24, and 26.
+- 08d2129: feat(mcp): propagate the server name through dynamic tool parts
+- 58c9eb1: feat(mcp): add `redirect` option to `MCPTransportConfig` for controlling HTTP redirect behavior
+- 0c4c275: trigger initial canary release
+- 611f621: feat(mcp): feat(mcp): add support for MCP Apps
+- 9ecd8ae: fix(mcp): add MCP protocol version 2025-11-25 to supported versions
+- 6c17a9f: fix(mcp): deduplicate auth refresh on http transport
+- 69254e0: feat(ai): add toolMetadata for tool specific metdata
+- 258c093: chore: ensure consistent import handling and avoid import duplicates or cycles
+- f0c6770: fix(mcp): prevent mcp oauth credential exfiltration during rediscovery
+- 5463d0d: feat(provider): align tool result output content file part types with top-level message file part types
+- b8396f0: trigger initial beta release
+- b29e087: fix (mcp): handle SSE messages without explicit event fields
+- 90e2d8a: chore: fix unused vars not being flagged by our lint tooling
+- 024a6b4: fix(mcp): validate oauth metadata issuer during discovery
+- 9b0bc8a: fix(mcp): prevent prototype pollution by using secureJsonParse
+- ff5eba1: feat: roll `image-*` tool output types into their equivalent `file-*` types
+
+## 2.0.0-beta.67
+
+### Patch Changes
+
+- Updated dependencies [0416e3e]
+  - @ai-sdk/provider@4.0.0-beta.20
+  - @ai-sdk/provider-utils@5.0.0-beta.50
+
+## 2.0.0-beta.66
+
+### Patch Changes
+
+- b8396f0: trigger initial beta release
+- Updated dependencies [b8396f0]
+  - @ai-sdk/provider-utils@5.0.0-beta.49
+  - @ai-sdk/provider@4.0.0-beta.19
+
 ## 2.0.0-canary.65
 
 ### Patch 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;