feat(openai): MCP tool approval (#11110)

## Background

OpenAI's in built mcp tool allowed for human approval before executing
it. This change integrates it in the existing tool definition.

## Summary

- spec changed
- flow changed to allow for passing provider executed tools responses
- parse the `mcp_approval_request` from OpenAI's model and ensure it's
processed properly
- pass a proper `mcp_approval_response` back to the model.

## Manual Verification

- [ ] UI example
`http://localhost:3000/test-openai-responses-mcp-approval`
- [ ] static examples added
- [ ] test that non mcp (old) approval ui example still works

## Checklist

- [x] Tests have been added / updated (for bug fixes / features)
- [x] Documentation has been added / updated (for bug fixes / features)
- [x] A _patch_ changeset for relevant packages has been added (for bug
fixes / features - run `pnpm changeset` in the project root)

## Related Issues

Fixes #11001

---------

Co-authored-by: Lars Grammel <lars.grammel@gmail.com>

Author: aayush-kapoor

.changeset/nasty-falcons-double.md

@@ -0,0 +1,7 @@
+---
+'@ai-sdk/provider-utils': patch
+'@ai-sdk/openai': patch
+'ai': patch
+---
+
+feat: add MCP tool approval

content/docs/07-reference/05-ai-sdk-errors/ai-invalid-tool-approval-error.mdx

@@ -0,0 +1,25 @@
+---
+title: AI_InvalidToolApprovalError
+description: Learn how to fix AI_InvalidToolApprovalError
+---
+
+# AI_InvalidToolApprovalError
+
+This error occurs when a tool approval response references an unknown `approvalId`. No matching `tool-approval-request` was found in the message history.
+
+## Properties
+
+- `approvalId`: The approval ID that was not found
+- `message`: The error message
+
+## Checking for this Error
+
+You can check if an error is an instance of `AI_InvalidToolApprovalError` using:
+
+```typescript
+import { InvalidToolApprovalError } from 'ai';
+
+if (InvalidToolApprovalError.isInstance(error)) {
+  // Handle the error
+}
+```

content/docs/07-reference/05-ai-sdk-errors/ai-tool-call-not-found-for-approval-error.mdx

@@ -0,0 +1,26 @@
+---
+title: AI_ToolCallNotFoundForApprovalError
+description: Learn how to fix AI_ToolCallNotFoundForApprovalError
+---
+
+# AI_ToolCallNotFoundForApprovalError
+
+This error occurs when a tool approval request references a tool call that was not found. This can happen when processing provider-emitted approval requests (e.g., MCP flows) where the referenced tool call ID does not exist.
+
+## Properties
+
+- `toolCallId`: The tool call ID that was not found
+- `approvalId`: The approval request ID
+- `message`: The error message
+
+## Checking for this Error
+
+You can check if an error is an instance of `AI_ToolCallNotFoundForApprovalError` using:
+
+```typescript
+import { ToolCallNotFoundForApprovalError } from 'ai';
+
+if (ToolCallNotFoundForApprovalError.isInstance(error)) {
+  // Handle the error
+}
+```

content/docs/07-reference/05-ai-sdk-errors/index.mdx

@@ -15,6 +15,7 @@ collapsed: true
 - [AI_InvalidMessageRoleError](/docs/reference/ai-sdk-errors/ai-invalid-message-role-error)
 - [AI_InvalidPromptError](/docs/reference/ai-sdk-errors/ai-invalid-prompt-error)
 - [AI_InvalidResponseDataError](/docs/reference/ai-sdk-errors/ai-invalid-response-data-error)
+- [AI_InvalidToolApprovalError](/docs/reference/ai-sdk-errors/ai-invalid-tool-approval-error)
 - [AI_InvalidToolInputError](/docs/reference/ai-sdk-errors/ai-invalid-tool-input-error)
 - [AI_JSONParseError](/docs/reference/ai-sdk-errors/ai-json-parse-error)
 - [AI_LoadAPIKeyError](/docs/reference/ai-sdk-errors/ai-load-api-key-error)
@@ -30,6 +31,7 @@ collapsed: true
 - [AI_NoSuchProviderError](/docs/reference/ai-sdk-errors/ai-no-such-provider-error)
 - [AI_NoSuchToolError](/docs/reference/ai-sdk-errors/ai-no-such-tool-error)
 - [AI_RetryError](/docs/reference/ai-sdk-errors/ai-retry-error)
+- [AI_ToolCallNotFoundForApprovalError](/docs/reference/ai-sdk-errors/ai-tool-call-not-found-for-approval-error)
 - [AI_ToolCallRepairError](/docs/reference/ai-sdk-errors/ai-tool-call-repair-error)
 - [AI_TooManyEmbeddingValuesForCallError](/docs/reference/ai-sdk-errors/ai-too-many-embedding-values-for-call-error)
 - [AI_TypeValidationError](/docs/reference/ai-sdk-errors/ai-type-validation-error)

content/providers/01-ai-sdk-providers/03-openai.mdx

@@ -569,10 +569,26 @@ The MCP tool can be configured with:
 
   Optional HTTP headers to include in requests to the MCP server.
 
+- **requireApproval** _'always' | 'never' | object_ (optional)
+
+  Controls which MCP tool calls require user approval before execution. Can be:
+
+  - `'always'`: All MCP tool calls require approval
+  - `'never'`: No MCP tool calls require approval (default)
+  - An object with filters:
+    ```ts
+    {
+      never: {
+        toolNames: ['safe_tool', 'another_safe_tool']; // Skip approval for these tools
+      }
+    }
+    ```
+
+  When approval is required, the model will return a `tool-approval-request` content part that you can use to prompt the user for approval. See [Human in the Loop](/cookbook/next/human-in-the-loop) for more details on implementing approval workflows.
+
 <Note>
-  The tool calls made by the model when using the OpenAI MCP tool are approved
-  by default. Be sure to connect to only trusted MCP servers, who you trust to
-  share your data with.
+  When `requireApproval` is not set, tool calls are approved by default. Be sure
+  to connect to only trusted MCP servers, who you trust to share your data with.
 </Note>
 
 <Note>

examples/ai-core/src/generate-text/openai-responses-mcp-tool-approval.ts

@@ -0,0 +1,102 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import {
+  generateText,
+  ModelMessage,
+  stepCountIs,
+  ToolApprovalResponse,
+} from 'ai';
+import * as readline from 'node:readline/promises';
+import { run } from '../lib/run';
+
+const terminal = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const openai = createOpenAI();
+
+run(async () => {
+  const messages: ModelMessage[] = [];
+  let approvals: ToolApprovalResponse[] = [];
+
+  while (true) {
+    messages.push(
+      approvals.length > 0
+        ? { role: 'tool', content: approvals }
+        : { role: 'user', content: await terminal.question('You:\n') },
+    );
+
+    if (approvals.length === 0) {
+      const lastMessage = messages[messages.length - 1];
+      if (
+        lastMessage.role === 'user' &&
+        typeof lastMessage.content === 'string' &&
+        lastMessage.content.toLowerCase() === 'exit'
+      ) {
+        terminal.close();
+        break;
+      }
+    }
+
+    approvals = [];
+
+    const result = await generateText({
+      model: openai.responses('gpt-5-mini'),
+      system:
+        'You are a helpful assistant that can shorten links. ' +
+        'Use the MCP tools available to you to shorten links when needed. ' +
+        'When a tool execution is not approved by the user, do not retry it. ' +
+        'Just say that the tool execution was not approved.',
+      tools: {
+        mcp: openai.tools.mcp({
+          serverLabel: 'zip1',
+          serverUrl: 'https://zip1.io/mcp',
+          serverDescription: 'Link shortener',
+          requireApproval: 'always',
+        }),
+      },
+      messages,
+      stopWhen: stepCountIs(10),
+    });
+
+    // Log raw response for debugging
+    console.log('\n=== RAW RESPONSE ===');
+    console.log('Steps:', result.steps.length);
+    for (const [i, step] of result.steps.entries()) {
+      console.log(`\n--- Step ${i + 1} ---`);
+      console.log(
+        'Content parts:',
+        step.content.map(p => p.type),
+      );
+      for (const part of step.content) {
+        if (
+          part.type === 'tool-approval-request' ||
+          part.type === 'tool-call' ||
+          part.type === 'tool-result' ||
+          part.type === 'tool-error'
+        ) {
+          console.log(`Tool ${part.type}:`, JSON.stringify(part, null, 2));
+        }
+      }
+    }
+    console.log('\n=== END RAW RESPONSE ===\n');
+
+    for (const part of result.content) {
+      if (part.type === 'tool-approval-request') {
+        const answer = await terminal.question(
+          `\nApprove MCP tool call? (y/n): `,
+        );
+        approvals.push({
+          type: 'tool-approval-response',
+          approvalId: part.approvalId,
+          approved:
+            answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes',
+        });
+      } else if (part.type === 'text') {
+        console.log(`\nAssistant:\n${part.text}`);
+      }
+    }
+
+    messages.push(...result.response.messages);
+  }
+});

examples/ai-core/src/stream-text/openai-responses-mcp-tool-approval.ts

@@ -0,0 +1,89 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import {
+  ModelMessage,
+  stepCountIs,
+  streamText,
+  ToolApprovalResponse,
+} from 'ai';
+import * as readline from 'node:readline/promises';
+import { run } from '../lib/run';
+
+const terminal = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+const openai = createOpenAI();
+
+run(async () => {
+  const messages: ModelMessage[] = [];
+  let approvals: ToolApprovalResponse[] = [];
+
+  while (true) {
+    messages.push(
+      approvals.length > 0
+        ? { role: 'tool', content: approvals }
+        : { role: 'user', content: await terminal.question('You:\n') },
+    );
+
+    if (approvals.length === 0) {
+      const lastMessage = messages[messages.length - 1];
+      if (
+        lastMessage.role === 'user' &&
+        typeof lastMessage.content === 'string' &&
+        lastMessage.content.toLowerCase() === 'exit'
+      ) {
+        terminal.close();
+        break;
+      }
+    }
+
+    approvals = [];
+
+    const result = streamText({
+      model: openai.responses('gpt-5-mini'),
+      system:
+        'You are a helpful assistant that can shorten links. ' +
+        'Use the MCP tools available to you to shorten links when needed. ' +
+        'When a tool execution is not approved by the user, do not retry it. ' +
+        'Just say that the tool execution was not approved.',
+      tools: {
+        mcp: openai.tools.mcp({
+          serverLabel: 'zip1',
+          serverUrl: 'https://zip1.io/mcp',
+          serverDescription: 'Link shortener',
+          requireApproval: 'always',
+        }),
+      },
+      messages,
+      stopWhen: stepCountIs(10),
+    });
+
+    // Stream text output
+    process.stdout.write('\nAssistant: ');
+    for await (const textPart of result.textStream) {
+      process.stdout.write(textPart);
+    }
+    process.stdout.write('\n');
+
+    // Get final results
+    const content = await result.content;
+    const response = await result.response;
+
+    for (const part of content) {
+      if (part.type === 'tool-approval-request') {
+        const answer = await terminal.question(
+          `\nApprove MCP tool call? (y/n): `,
+        );
+        approvals.push({
+          type: 'tool-approval-response',
+          approvalId: part.approvalId,
+          approved:
+            answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes',
+        });
+      }
+    }
+
+    messages.push(...response.messages);
+  }
+});

examples/next-openai/agent/openai-mcp-approval-agent.ts

@@ -0,0 +1,23 @@
+import { openai } from '@ai-sdk/openai';
+import { ToolLoopAgent, InferAgentUIMessage } from 'ai';
+
+export const openaiMCPApprovalAgent = new ToolLoopAgent({
+  model: openai.responses('gpt-5'),
+  instructions:
+    'You are a helpful assistant that can shorten links. ' +
+    'Use the MCP tools available to you to shorten links when needed. ' +
+    'When a tool execution is not approved by the user, do not retry it. ' +
+    'Just say that the tool execution was not approved.',
+  tools: {
+    mcp: openai.tools.mcp({
+      serverLabel: 'zip1',
+      serverUrl: 'https://zip1.io/mcp',
+      serverDescription: 'Link shortener',
+      requireApproval: 'always',
+    }),
+  },
+});
+
+export type OpenAIMCPApprovalAgentUIMessage = InferAgentUIMessage<
+  typeof openaiMCPApprovalAgent
+>;

examples/next-openai/app/api/chat-openai-responses-mcp-approval/route.ts

@@ -0,0 +1,18 @@
+import {
+  openaiMCPApprovalAgent,
+  OpenAIMCPApprovalAgentUIMessage,
+} from '@/agent/openai-mcp-approval-agent';
+import { createAgentUIStreamResponse } from 'ai';
+
+export const maxDuration = 60;
+
+export type OpenAIResponsesMCPApprovalMessage = OpenAIMCPApprovalAgentUIMessage;
+
+export async function POST(req: Request) {
+  const body = await req.json();
+
+  return createAgentUIStreamResponse({
+    agent: openaiMCPApprovalAgent,
+    uiMessages: body.messages,
+  });
+}