@ai-sdk/mcp 1.0.41 → 1.0.43

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @ai-sdk/mcp
 
+## 1.0.43
+
+### Patch Changes
+
+- e2b923f: fix(mcp): deduplicate auth refresh on http transport
+
+## 1.0.42
+
+### Patch Changes
+
+- 725f2ed: feat(mcp): expose server instructions to be accessible through client
+- 7281592: fix(mcp): use negotiated protocol version in transport request headers
+
 ## 1.0.41
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,134 @@
+# AI SDK - Model Context Protocol Client
+
+The **Model Context Protocol (MCP) client** for the
+[AI SDK](https://ai-sdk.dev/docs) lets you connect to MCP servers and use their
+tools with AI SDK functions like `generateText` and `streamText`.
+
+## Setup
+
+The MCP client is available in the `@ai-sdk/mcp` module. You can install it with
+
+```bash
+npm i @ai-sdk/mcp ai zod
+```
+
+## Skill for Coding Agents
+
+If you use coding agents such as Claude Code or Cursor, we highly recommend
+adding the AI SDK skill to your repository:
+
+```shell
+npx skills add vercel/ai
+```
+
+## Usage
+
+Create an MCP client with `createMCPClient()`, fetch the server tools with
+`mcpClient.tools()`, and pass them to an AI SDK call:
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp';
+import { generateText, isStepCount } from 'ai';
+
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://your-server.com/mcp',
+    headers: {
+      Authorization: `Bearer ${process.env.MCP_API_KEY}`,
+    },
+  },
+});
+
+try {
+  const tools = await mcpClient.tools();
+
+  const { text } = await generateText({
+    model: 'openai/gpt-5.4',
+    tools,
+    stopWhen: isStepCount(10),
+    prompt: 'Use the available tools to answer the user question.',
+  });
+
+  console.log(text);
+} finally {
+  await mcpClient.close();
+}
+```
+
+The client converts MCP tool definitions into AI SDK tools, so model calls can
+use them through the standard `tools` option.
+
+For streaming responses, close the MCP client when the stream finishes:
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp';
+import { streamText } from 'ai';
+
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://your-server.com/mcp',
+  },
+});
+
+const result = streamText({
+  model: 'openai/gpt-5.4',
+  tools: await mcpClient.tools(),
+  prompt: 'Use the available tools to answer the user question.',
+  onFinish: async () => {
+    await mcpClient.close();
+  },
+});
+
+for await (const textPart of result.textStream) {
+  process.stdout.write(textPart);
+}
+```
+
+## Transports
+
+HTTP is recommended for production deployments:
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp';
+
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'http',
+    url: 'https://your-server.com/mcp',
+  },
+});
+```
+
+SSE is also supported for MCP servers that use Server-Sent Events:
+
+```ts
+const mcpClient = await createMCPClient({
+  transport: {
+    type: 'sse',
+    url: 'https://your-server.com/sse',
+  },
+});
+```
+
+For local MCP servers, you can use stdio transport from the `@ai-sdk/mcp/mcp-stdio`
+subpath:
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp';
+import { Experimental_StdioMCPTransport } from '@ai-sdk/mcp/mcp-stdio';
+
+const mcpClient = await createMCPClient({
+  transport: new Experimental_StdioMCPTransport({
+    command: 'node',
+    args: ['server.js'],
+  }),
+});
+```
+
+## Documentation
+
+Please check out the
+[AI SDK MCP documentation](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools) for
+more information.

package/dist/index.d.mts

@@ -228,6 +228,10 @@ interface MCPTransport {
      * Event handler for received messages
      */
     onmessage?: (message: JSONRPCMessage) => void;
+    /**
+     * The protocol version negotiated during initialization.
+     */
+    protocolVersion?: string;
 }
 type MCPTransportConfig = {
     type: 'sse' | 'http';
@@ -508,6 +512,15 @@ interface MCPClient {
      * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#implementation
      */
     readonly serverInfo: Configuration;
+    /**
+     * Optional instructions provided by the server during the initialize handshake.
+     *
+     * These describe how to use the server and its features, and can be used by clients
+     * to improve LLM interactions (e.g. by including them in the system prompt).
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#initializeresult
+     */
+    readonly instructions?: string;
     tools<TOOL_SCHEMAS extends ToolSchemas = 'automatic'>(options?: {
         schemas?: TOOL_SCHEMAS;
     }): Promise<McpToolSet<TOOL_SCHEMAS>>;

package/dist/index.d.ts

@@ -228,6 +228,10 @@ interface MCPTransport {
      * Event handler for received messages
      */
     onmessage?: (message: JSONRPCMessage) => void;
+    /**
+     * The protocol version negotiated during initialization.
+     */
+    protocolVersion?: string;
 }
 type MCPTransportConfig = {
     type: 'sse' | 'http';
@@ -508,6 +512,15 @@ interface MCPClient {
      * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#implementation
      */
     readonly serverInfo: Configuration;
+    /**
+     * Optional instructions provided by the server during the initialize handshake.
+     *
+     * These describe how to use the server and its features, and can be used by clients
+     * to improve LLM interactions (e.g. by including them in the system prompt).
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-11-25/schema#initializeresult
+     */
+    readonly instructions?: string;
     tools<TOOL_SCHEMAS extends ToolSchemas = 'automatic'>(options?: {
         schemas?: TOOL_SCHEMAS;
     }): Promise<McpToolSet<TOOL_SCHEMAS>>;

package/dist/index.js

@@ -1115,10 +1115,11 @@ var SseMCPTransport = class {
     this.fetchFn = fetchFn != null ? fetchFn : globalThis.fetch;
   }
   async commonHeaders(base) {
+    var _a3;
     const headers = {
       ...this.headers,
       ...base,
-      "mcp-protocol-version": LATEST_PROTOCOL_VERSION
+      "mcp-protocol-version": (_a3 = this.protocolVersion) != null ? _a3 : LATEST_PROTOCOL_VERSION
     };
     if (this.authProvider) {
       const tokens = await this.authProvider.tokens();
@@ -1329,10 +1330,11 @@ var HttpMCPTransport = class {
     this.fetchFn = fetchFn != null ? fetchFn : globalThis.fetch;
   }
   async commonHeaders(base) {
+    var _a3;
     const headers = {
       ...this.headers,
       ...base,
-      "mcp-protocol-version": LATEST_PROTOCOL_VERSION
+      "mcp-protocol-version": (_a3 = this.protocolVersion) != null ? _a3 : LATEST_PROTOCOL_VERSION
     };
     if (this.sessionId) {
       headers["mcp-session-id"] = this.sessionId;
@@ -1349,6 +1351,24 @@ var HttpMCPTransport = class {
       (0, import_provider_utils4.getRuntimeEnvironmentUserAgent)()
     );
   }
+  /**
+   * Runs a single OAuth recovery flow for concurrent 401 responses.
+   */
+  authorizeOnce(resourceMetadataUrl) {
+    if (!this.authProvider) {
+      return Promise.resolve("REDIRECT");
+    }
+    if (!this.authPromise) {
+      this.authPromise = auth(this.authProvider, {
+        serverUrl: this.url,
+        resourceMetadataUrl,
+        fetchFn: this.fetchFn
+      }).finally(() => {
+        this.authPromise = void 0;
+      });
+    }
+    return this.authPromise;
+  }
   async start() {
     if (this.abortController) {
       throw new MCPClientError({
@@ -1399,11 +1419,7 @@ var HttpMCPTransport = class {
         if (response.status === 401 && this.authProvider && !triedAuth) {
           this.resourceMetadataUrl = extractResourceMetadataUrl(response);
           try {
-            const result = await auth(this.authProvider, {
-              serverUrl: this.url,
-              resourceMetadataUrl: this.resourceMetadataUrl,
-              fetchFn: this.fetchFn
-            });
+            const result = await this.authorizeOnce(this.resourceMetadataUrl);
             if (result !== "AUTHORIZED") {
               const error2 = new UnauthorizedError();
               throw error2;
@@ -1549,11 +1565,7 @@ var HttpMCPTransport = class {
       if (response.status === 401 && this.authProvider && !triedAuth) {
         this.resourceMetadataUrl = extractResourceMetadataUrl(response);
         try {
-          const result = await auth(this.authProvider, {
-            serverUrl: this.url,
-            resourceMetadataUrl: this.resourceMetadataUrl,
-            fetchFn: this.fetchFn
-          });
+          const result = await this.authorizeOnce(this.resourceMetadataUrl);
           if (result !== "AUTHORIZED") {
             const error = new UnauthorizedError();
             (_b3 = this.onerror) == null ? void 0 : _b3.call(this, error);
@@ -1721,6 +1733,9 @@ var DefaultMCPClient = class {
   get serverInfo() {
     return this._serverInfo;
   }
+  get instructions() {
+    return this._serverInstructions;
+  }
   async init() {
     try {
       await this.transport.start();
@@ -1748,6 +1763,8 @@ var DefaultMCPClient = class {
       }
       this.serverCapabilities = result.capabilities;
       this._serverInfo = result.serverInfo;
+      this._serverInstructions = result.instructions;
+      this.transport.protocolVersion = result.protocolVersion;
       await this.notification({
         method: "notifications/initialized"
       });