@ai-sdk/xai 3.0.30 → 3.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "3.0.30",
+  "version": "3.0.32",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,10 +8,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
     "src",
     "CHANGELOG.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -21,9 +25,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.4",
+    "@ai-sdk/openai-compatible": "2.0.17",
     "@ai-sdk/provider-utils": "4.0.8",
-    "@ai-sdk/openai-compatible": "2.0.17"
+    "@ai-sdk/provider": "3.0.4"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
@@ -56,7 +60,7 @@
   "scripts": {
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
-    "clean": "del-cli dist *.tsbuildinfo",
+    "clean": "del-cli dist docs *.tsbuildinfo",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
     "prettier-check": "prettier --check \"./**/*.ts*\"",

package/src/index.ts

@@ -5,6 +5,7 @@ export { createXai, xai } from './xai-provider';
 export type { XaiProvider, XaiProviderSettings } from './xai-provider';
 export {
   codeExecution,
+  mcpServer,
   viewImage,
   viewXVideo,
   webSearch,

package/src/responses/xai-responses-api.ts

@@ -83,7 +83,15 @@ export type XaiResponsesTool =
   | { type: 'view_image' }
   | { type: 'view_x_video' }
   | { type: 'file_search' }
-  | { type: 'mcp' }
+  | {
+      type: 'mcp';
+      server_url: string;
+      server_label?: string;
+      server_description?: string;
+      allowed_tools?: string[];
+      headers?: Record<string, string>;
+      authorization?: string;
+    }
   | {
       type: 'function';
       name: string;
@@ -124,6 +132,16 @@ const toolCallSchema = z.object({
   action: z.any().optional(),
 });
 
+const mcpCallSchema = z.object({
+  name: z.string().optional(),
+  arguments: z.string().optional(),
+  output: z.string().optional(),
+  error: z.string().optional(),
+  id: z.string(),
+  status: z.string(),
+  server_label: z.string().optional(),
+});
+
 const outputItemSchema = z.discriminatedUnion('type', [
   z.object({
     type: z.literal('web_search_call'),
@@ -153,6 +171,10 @@ const outputItemSchema = z.discriminatedUnion('type', [
     type: z.literal('custom_tool_call'),
     ...toolCallSchema.shape,
   }),
+  z.object({
+    type: z.literal('mcp_call'),
+    ...mcpCallSchema.shape,
+  }),
   z.object({
     type: z.literal('message'),
     role: z.string(),
@@ -378,6 +400,62 @@ export const xaiResponsesChunkSchema = z.union([
     output_index: z.number(),
     code: z.string(),
   }),
+  z.object({
+    type: z.literal('response.custom_tool_call_input.delta'),
+    item_id: z.string(),
+    output_index: z.number(),
+    delta: z.string(),
+  }),
+  z.object({
+    type: z.literal('response.custom_tool_call_input.done'),
+    item_id: z.string(),
+    output_index: z.number(),
+    input: z.string(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call.in_progress'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call.executing'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call.completed'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call.failed'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call_arguments.delta'),
+    item_id: z.string(),
+    output_index: z.number(),
+    delta: z.string(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call_arguments.done'),
+    item_id: z.string(),
+    output_index: z.number(),
+    arguments: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call_output.delta'),
+    item_id: z.string(),
+    output_index: z.number(),
+    delta: z.string(),
+  }),
+  z.object({
+    type: z.literal('response.mcp_call_output.done'),
+    item_id: z.string(),
+    output_index: z.number(),
+    output: z.string().optional(),
+  }),
   z.object({
     type: z.literal('response.done'),
     response: xaiResponsesResponseSchema,

package/src/responses/xai-responses-language-model.ts

@@ -99,6 +99,10 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       tool => tool.type === 'provider' && tool.id === 'xai.code_execution',
     )?.name;
 
+    const mcpToolName = tools?.find(
+      tool => tool.type === 'provider' && tool.id === 'xai.mcp',
+    )?.name;
+
     const { input, inputWarnings } = await convertToXaiResponsesInput({
       prompt,
       store: true,
@@ -162,6 +166,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       webSearchToolName,
       xSearchToolName,
       codeExecutionToolName,
+      mcpToolName,
     };
   }
 
@@ -174,6 +179,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       webSearchToolName,
       xSearchToolName,
       codeExecutionToolName,
+      mcpToolName,
     } = await this.getArgs(options);
 
     const {
@@ -214,7 +220,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
         part.type === 'code_execution_call' ||
         part.type === 'view_image_call' ||
         part.type === 'view_x_video_call' ||
-        part.type === 'custom_tool_call'
+        part.type === 'custom_tool_call' ||
+        part.type === 'mcp_call'
       ) {
         let toolName = part.name ?? '';
         if (
@@ -233,13 +240,17 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
           part.type === 'code_execution_call'
         ) {
           toolName = codeExecutionToolName ?? 'code_execution';
+        } else if (part.type === 'mcp_call') {
+          toolName = mcpToolName ?? part.name ?? 'mcp';
         }
 
         // custom_tool_call uses 'input' field, others use 'arguments'
         const toolInput =
           part.type === 'custom_tool_call'
             ? (part.input ?? '')
-            : (part.arguments ?? '');
+            : part.type === 'mcp_call'
+              ? (part.arguments ?? '')
+              : (part.arguments ?? '');
 
         content.push({
           type: 'tool-call',
@@ -352,6 +363,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       webSearchToolName,
       xSearchToolName,
       codeExecutionToolName,
+      mcpToolName,
     } = await this.getArgs(options);
     const body = {
       ...args,
@@ -533,6 +545,14 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
               return;
             }
 
+            // Custom tool call input streaming - already handled by output_item events
+            if (
+              event.type === 'response.custom_tool_call_input.delta' ||
+              event.type === 'response.custom_tool_call_input.done'
+            ) {
+              return;
+            }
+
             if (
               event.type === 'response.output_item.added' ||
               event.type === 'response.output_item.done'
@@ -564,7 +584,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
                 part.type === 'code_execution_call' ||
                 part.type === 'view_image_call' ||
                 part.type === 'view_x_video_call' ||
-                part.type === 'custom_tool_call'
+                part.type === 'custom_tool_call' ||
+                part.type === 'mcp_call'
               ) {
                 const webSearchSubTools = [
                   'web_search',
@@ -595,13 +616,17 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
                   part.type === 'code_execution_call'
                 ) {
                   toolName = codeExecutionToolName ?? 'code_execution';
+                } else if (part.type === 'mcp_call') {
+                  toolName = mcpToolName ?? part.name ?? 'mcp';
                 }
 
                 // custom_tool_call uses 'input' field, others use 'arguments'
                 const toolInput =
                   part.type === 'custom_tool_call'
                     ? (part.input ?? '')
-                    : (part.arguments ?? '');
+                    : part.type === 'mcp_call'
+                      ? (part.arguments ?? '')
+                      : (part.arguments ?? '');
 
                 // for custom_tool_call, input is only available on 'done' event
                 // for other types, input is available on 'added' event
@@ -647,6 +672,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
                   if (contentPart.text && contentPart.text.length > 0) {
                     const blockId = `text-${part.id}`;
 
+                    // Only emit text if we haven't already streamed it via output_text.delta events
                     if (contentBlocks[blockId] == null) {
                       contentBlocks[blockId] = { type: 'text' };
                       controller.enqueue({

package/src/responses/xai-responses-prepare-tools.test.ts

@@ -494,4 +494,127 @@ describe('prepareResponsesTools', () => {
       `);
     });
   });
+
+  describe('mcp', () => {
+    it('should prepare mcp tool with required args only', async () => {
+      const result = await prepareResponsesTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'xai.mcp',
+            name: 'mcp',
+            args: {
+              serverUrl: 'https://example.com/mcp',
+              serverLabel: 'test-server',
+            },
+          },
+        ],
+      });
+
+      expect(result.tools).toMatchInlineSnapshot(`
+        [
+          {
+            "allowed_tools": undefined,
+            "authorization": undefined,
+            "headers": undefined,
+            "server_description": undefined,
+            "server_label": "test-server",
+            "server_url": "https://example.com/mcp",
+            "type": "mcp",
+          },
+        ]
+      `);
+    });
+
+    it('should prepare mcp tool with all optional args', async () => {
+      const result = await prepareResponsesTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'xai.mcp',
+            name: 'mcp',
+            args: {
+              serverUrl: 'https://example.com/mcp',
+              serverLabel: 'test-server',
+              serverDescription: 'A test MCP server',
+              allowedTools: ['tool1', 'tool2'],
+              headers: { 'X-Custom': 'value' },
+              authorization: 'Bearer token123',
+            },
+          },
+        ],
+      });
+
+      expect(result.tools).toMatchInlineSnapshot(`
+        [
+          {
+            "allowed_tools": [
+              "tool1",
+              "tool2",
+            ],
+            "authorization": "Bearer token123",
+            "headers": {
+              "X-Custom": "value",
+            },
+            "server_description": "A test MCP server",
+            "server_label": "test-server",
+            "server_url": "https://example.com/mcp",
+            "type": "mcp",
+          },
+        ]
+      `);
+    });
+
+    it('should handle mcp tool choice', async () => {
+      const result = await prepareResponsesTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'xai.mcp',
+            name: 'mcp',
+            args: {
+              serverUrl: 'https://example.com/mcp',
+              serverLabel: 'test-server',
+            },
+          },
+        ],
+        toolChoice: { type: 'tool', toolName: 'mcp' },
+      });
+
+      expect(result.toolChoice).toEqual({ type: 'mcp' });
+    });
+
+    it('should handle multiple tools including mcp', async () => {
+      const result = await prepareResponsesTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'xai.web_search',
+            name: 'web_search',
+            args: {},
+          },
+          {
+            type: 'provider',
+            id: 'xai.mcp',
+            name: 'mcp',
+            args: {
+              serverUrl: 'https://example.com/mcp',
+              serverLabel: 'test-server',
+            },
+          },
+          {
+            type: 'function',
+            name: 'calculator',
+            description: 'calculate numbers',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ],
+      });
+
+      expect(result.tools).toHaveLength(3);
+      expect(result.tools?.[0].type).toBe('web_search');
+      expect(result.tools?.[1].type).toBe('mcp');
+      expect(result.tools?.[2].type).toBe('function');
+    });
+  });
 });

package/src/responses/xai-responses-prepare-tools.ts

@@ -4,6 +4,7 @@ import {
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
 import { validateTypes } from '@ai-sdk/provider-utils';
+import { mcpServerArgsSchema } from '../tool/mcp-server';
 import { webSearchArgsSchema } from '../tool/web-search';
 import { xSearchArgsSchema } from '../tool/x-search';
 import { XaiResponsesTool } from './xai-responses-api';
@@ -110,8 +111,19 @@ export async function prepareResponsesTools({
         }
 
         case 'xai.mcp': {
+          const args = await validateTypes({
+            value: tool.args,
+            schema: mcpServerArgsSchema,
+          });
+
           xaiTools.push({
             type: 'mcp',
+            server_url: args.serverUrl,
+            server_label: args.serverLabel,
+            server_description: args.serverDescription,
+            allowed_tools: args.allowedTools,
+            headers: args.headers,
+            authorization: args.authorization,
           });
           break;
         }

package/src/tool/index.ts

@@ -1,13 +1,15 @@
 import { codeExecution } from './code-execution';
+import { mcpServer } from './mcp-server';
 import { viewImage } from './view-image';
 import { viewXVideo } from './view-x-video';
 import { webSearch } from './web-search';
 import { xSearch } from './x-search';
 
-export { codeExecution, viewImage, viewXVideo, webSearch, xSearch };
+export { codeExecution, mcpServer, viewImage, viewXVideo, webSearch, xSearch };
 
 export const xaiTools = {
   codeExecution,
+  mcpServer,
   viewImage,
   viewXVideo,
   webSearch,

package/src/tool/mcp-server.ts

@@ -0,0 +1,66 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const mcpServerArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      serverUrl: z.string().describe('The URL of the MCP server'),
+      serverLabel: z.string().optional().describe('A label for the MCP server'),
+      serverDescription: z
+        .string()
+        .optional()
+        .describe('Description of the MCP server'),
+      allowedTools: z
+        .array(z.string())
+        .optional()
+        .describe('List of allowed tool names'),
+      headers: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Custom headers to send'),
+      authorization: z
+        .string()
+        .optional()
+        .describe('Authorization header value'),
+    }),
+  ),
+);
+
+// MCP tool output varies based on which tool is called
+const mcpServerOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      name: z.string(),
+      arguments: z.string(),
+      result: z.unknown(),
+    }),
+  ),
+);
+
+const mcpServerToolFactory = createProviderToolFactoryWithOutputSchema<
+  {},
+  {
+    name: string;
+    arguments: string;
+    result: unknown;
+  },
+  {
+    serverUrl: string;
+    serverLabel?: string;
+    serverDescription?: string;
+    allowedTools?: string[];
+    headers?: Record<string, string>;
+    authorization?: string;
+  }
+>({
+  id: 'xai.mcp',
+  inputSchema: lazySchema(() => zodSchema(z.object({}))),
+  outputSchema: mcpServerOutputSchema,
+});
+
+export const mcpServer = (args: Parameters<typeof mcpServerToolFactory>[0]) =>
+  mcpServerToolFactory(args);

package/src/tool/web-search.ts

@@ -31,7 +31,7 @@ const webSearchOutputSchema = lazySchema(() =>
 );
 
 const webSearchToolFactory = createProviderToolFactoryWithOutputSchema<
-  Record<string, never>,
+  {},
   {
     query: string;
     sources: Array<{

package/src/tool/x-search.ts

@@ -35,7 +35,7 @@ const xSearchOutputSchema = lazySchema(() =>
 );
 
 const xSearchToolFactory = createProviderToolFactoryWithOutputSchema<
-  Record<string, never>,
+  {},
   {
     query: string;
     posts: Array<{