Skip to content

Conversation

@aayush-kapoor
Copy link
Contributor

@aayush-kapoor aayush-kapoor commented Oct 1, 2025

Background

Refactor mcp into it's own separate package + add OAuth for MCP clients

Summary

Created new package @ai-sdk/mcp, added OAuth provider

Manual Verification

Manual tests added, e2e example added to verify oauth works in example/mcp/mcp-with-auth/client.ts

Checklist

  • Tests have been added / updated (for bug fixes / features)
  • Documentation has been added / updated (for bug fixes / features)
  • A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
  • Formatting issues have been fixed (run pnpm prettier-fix in the project root)

Future Work

  • Continue refactoring, add docs
  • log warning or throw error if wrong transport protocol is set for an mcp server

Related Issues

towards #8717, #9337 and #6717

Copy link
Contributor

@vercel vercel bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional Comments:

packages/ai/package.json (lines 49-54):
The package exports still include ./mcp-stdio which references files that will no longer be built after the source deletion. Users importing from 'ai/mcp-stdio' will get module not found errors.

View Details
📝 Patch Details
diff --git a/packages/ai/mcp-stdio.d.ts b/packages/ai/mcp-stdio.d.ts
deleted file mode 100644
index 8e853fa3a..000000000
--- a/packages/ai/mcp-stdio.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from './dist/mcp-stdio';
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 7436045ff..052d84617 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -11,7 +11,6 @@
     "dist/**/*",
     "CHANGELOG.md",
     "internal.d.ts",
-    "mcp-stdio.d.ts",
     "test.d.ts"
   ],
   "scripts": {
@@ -45,12 +44,6 @@
       "import": "./dist/test/index.mjs",
       "module": "./dist/test/index.mjs",
       "require": "./dist/test/index.js"
-    },
-    "./mcp-stdio": {
-      "types": "./dist/mcp-stdio/index.d.ts",
-      "import": "./dist/mcp-stdio/index.mjs",
-      "module": "./dist/mcp-stdio/index.mjs",
-      "require": "./dist/mcp-stdio/index.js"
     }
   },
   "dependencies": {

Analysis

Package exports reference deleted mcp-stdio source files causing module resolution failures

What fails: The package.json exports section declares ./mcp-stdio pointing to ./dist/mcp-stdio/* files that are no longer built after the source deletion in commit bde0cd61c.

How to reproduce:

# After building the ai package:
cd packages/ai && pnpm build
# The dist/mcp-stdio directory does not exist:
ls dist/mcp-stdio
# Returns: No such file or directory

# Any code importing from 'ai/mcp-stdio' fails:
node --input-type=module --eval "import('./packages/ai/dist/mcp-stdio/index.mjs')"
# Returns: Error: Cannot find module

Result: Module not found errors for any code importing from 'ai/mcp-stdio', affecting:

  • content/cookbook/01-next/73-mcp-tools.mdx
  • content/cookbook/05-node/54-mcp-tools.mdx
  • content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx
  • content/docs/07-reference/01-ai-sdk-core/24-mcp-stdio-transport.mdx

Expected: The ./mcp-stdio export should be removed from package.json exports along with the mcp-stdio.d.ts file reference, matching the source deletion in tsup.config.ts that removed the mcp-stdio build entry.

Fix: Removed ./mcp-stdio export from package.json and mcp-stdio.d.ts from files list to maintain package integrity.


packages/ai/mcp-stdio.d.ts (line 1):
This type definition file exports from './dist/mcp-stdio' which will no longer exist after the source code is deleted and the build configuration is removed.

View Details
📝 Patch Details
diff --git a/packages/ai/mcp-stdio.d.ts b/packages/ai/mcp-stdio.d.ts
deleted file mode 100644
index 8e853fa3a..000000000
--- a/packages/ai/mcp-stdio.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from './dist/mcp-stdio';
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 7436045ff..052d84617 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -11,7 +11,6 @@
     "dist/**/*",
     "CHANGELOG.md",
     "internal.d.ts",
-    "mcp-stdio.d.ts",
     "test.d.ts"
   ],
   "scripts": {
@@ -45,12 +44,6 @@
       "import": "./dist/test/index.mjs",
       "module": "./dist/test/index.mjs",
       "require": "./dist/test/index.js"
-    },
-    "./mcp-stdio": {
-      "types": "./dist/mcp-stdio/index.d.ts",
-      "import": "./dist/mcp-stdio/index.mjs",
-      "module": "./dist/mcp-stdio/index.mjs",
-      "require": "./dist/mcp-stdio/index.js"
     }
   },
   "dependencies": {
diff --git a/packages/ai/tsconfig.json b/packages/ai/tsconfig.json
index 7dedfdb70..fcf889404 100644
--- a/packages/ai/tsconfig.json
+++ b/packages/ai/tsconfig.json
@@ -15,7 +15,6 @@
     "node_modules",
     "tsup.config.ts",
     "internal.d.ts",
-    "mcp-stdio.d.ts",
     "test.d.ts"
   ],
   "references": [

Analysis

Broken type definition export after mcp-stdio source removal

What fails: The mcp-stdio.d.ts file exports from './dist/mcp-stdio' which doesn't exist, causing TypeScript compilation to fail with error TS2307: Cannot find module './dist/mcp-stdio'

How to reproduce:

cd packages/ai
pnpm build
pnpm exec tsc --noEmit mcp-stdio.d.ts

Result: TypeScript error: mcp-stdio.d.ts(1,15): error TS2307: Cannot find module './dist/mcp-stdio' or its corresponding type declarations.

Expected: TypeScript compilation should succeed. The mcp-stdio.d.ts file and its references should have been removed as part of commit bde0cd61c that deleted the mcp-stdio source code and build configuration.

Root cause: Commit bde0cd61c ("stdio transport removed") deleted the entire packages/ai/mcp-stdio/ source directory and removed its build configuration from tsup.config.ts, but failed to remove:

  • mcp-stdio.d.ts (which references the now-missing ./dist/mcp-stdio)
  • The ./mcp-stdio export in package.json exports field
  • The mcp-stdio.d.ts entry in tsconfig.json exclude array

Fix: Remove all orphaned references to the deleted mcp-stdio functionality


content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx (lines 164-174):
This documentation example imports and uses Experimental_StdioMCPTransport from 'ai/mcp-stdio', which will no longer exist after this deletion, making the code example broken.

View Details
📝 Patch Details
diff --git a/content/cookbook/01-next/73-mcp-tools.mdx b/content/cookbook/01-next/73-mcp-tools.mdx
index f6ea16363..ec129fa2a 100644
--- a/content/cookbook/01-next/73-mcp-tools.mdx
+++ b/content/cookbook/01-next/73-mcp-tools.mdx
@@ -18,7 +18,6 @@ To use the `StreamableHTTPClientTransport`, you will need to install the officia
 
 ```ts filename="app/api/completion/route.ts"
 import { experimental_createMCPClient, streamText } from 'ai';
-import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
 import { openai } from '@ai-sdk/openai';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse';
diff --git a/content/cookbook/05-node/54-mcp-tools.mdx b/content/cookbook/05-node/54-mcp-tools.mdx
index 8b8bb0018..69b1d51de 100644
--- a/content/cookbook/05-node/54-mcp-tools.mdx
+++ b/content/cookbook/05-node/54-mcp-tools.mdx
@@ -14,7 +14,6 @@ Use the official Model Context Protocol Typescript SDK to create the connection
 
 ```ts
 import { experimental_createMCPClient, generateText, stepCountIs } from 'ai';
-import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
 import { openai } from '@ai-sdk/openai';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse';
diff --git a/content/docs/03-ai-sdk-core/16-mcp-tools.mdx b/content/docs/03-ai-sdk-core/16-mcp-tools.mdx
index 05d40b9a7..4f85bfb70 100644
--- a/content/docs/03-ai-sdk-core/16-mcp-tools.mdx
+++ b/content/docs/03-ai-sdk-core/16-mcp-tools.mdx
@@ -64,13 +64,11 @@ const mcpClient = await createMCPClient({
   The stdio transport should only be used for local servers.
 </Note>
 
-The Stdio transport can be imported from either the MCP SDK or the AI SDK:
+The Stdio transport should be imported from the official MCP SDK:
 
 ```typescript
 import { experimental_createMCPClient as createMCPClient } from 'ai';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-// Or use the AI SDK's stdio transport:
-// import { Experimental_StdioMCPTransport as StdioClientTransport } from 'ai/mcp-stdio';
 
 const mcpClient = await createMCPClient({
   transport: new StdioClientTransport({
diff --git a/content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx b/content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx
index 9a2a19ea8..6df0ad585 100644
--- a/content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx
+++ b/content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx
@@ -161,15 +161,16 @@ Returns a Promise that resolves to an `MCPClient` with the following methods:
 
 ```typescript
 import { experimental_createMCPClient, generateText } from 'ai';
-import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { openai } from '@ai-sdk/openai';
 
 let client;
 
 try {
   client = await experimental_createMCPClient({
-    transport: new Experimental_StdioMCPTransport({
-      command: 'node server.js',
+    transport: new StdioClientTransport({
+      command: 'node',
+      args: ['server.js'],
     }),
   });
 
diff --git a/content/docs/07-reference/01-ai-sdk-core/24-mcp-stdio-transport.mdx b/content/docs/07-reference/01-ai-sdk-core/24-mcp-stdio-transport.mdx
deleted file mode 100644
index a4bdbe76c..000000000
--- a/content/docs/07-reference/01-ai-sdk-core/24-mcp-stdio-transport.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Experimental_StdioMCPTransport
-description: Create a transport for Model Context Protocol (MCP) clients to communicate with MCP servers using standard input and output streams
----
-
-# `Experimental_StdioMCPTransport`
-
-Creates a transport for Model Context Protocol (MCP) clients to communicate with MCP servers using standard input and output streams. This transport is only supported in Node.js environments.
-
-This feature is experimental and may change or be removed in the future.
-
-## Import
-
-<Snippet
-  text={`import { Experimental_StdioMCPTransport } from "ai/mcp-stdio"`}
-  prompt={false}
-/>
-
-## API Signature
-
-### Parameters
-
-<PropertiesTable
-  content={[
-    {
-      name: 'config',
-      type: 'StdioConfig',
-      description: 'Configuration for the MCP client.',
-      properties: [
-        {
-          type: 'StdioConfig',
-          parameters: [
-            {
-              name: 'command',
-              type: 'string',
-              description: 'The command to run the MCP server.',
-            },
-            {
-              name: 'args',
-              type: 'string[]',
-              isOptional: true,
-              description: 'The arguments to pass to the MCP server.',
-            },
-            {
-              name: 'env',
-              type: 'Record<string, string>',
-              isOptional: true,
-              description:
-                'The environment variables to set for the MCP server.',
-            },
-            {
-              name: 'stderr',
-              type: 'IOType | Stream | number',
-              isOptional: true,
-              description: "The stream to write the MCP server's stderr to.",
-            },
-            {
-              name: 'cwd',
-              type: 'string',
-              isOptional: true,
-              description: 'The current working directory for the MCP server.',
-            },
-          ],
-        },
-      ],
-    },
-  ]}
-/>
diff --git a/examples/mcp/src/stdio/client.ts b/examples/mcp/src/stdio/client.ts
index b3f5e137e..f84193f97 100644
--- a/examples/mcp/src/stdio/client.ts
+++ b/examples/mcp/src/stdio/client.ts
@@ -8,8 +8,6 @@ async function main() {
   let mcpClient;
 
   try {
-    // Or use the AI SDK's stdio transport by importing:
-    // import { Experimental_StdioMCPTransport as StdioClientTransport } from 'ai/mcp-stdio'
     const stdioTransport = new StdioClientTransport({
       command: 'node',
       args: ['src/stdio/dist/server.js'],
diff --git a/packages/ai/mcp-stdio.d.ts b/packages/ai/mcp-stdio.d.ts
deleted file mode 100644
index 8e853fa3a..000000000
--- a/packages/ai/mcp-stdio.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from './dist/mcp-stdio';
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 7436045ff..052d84617 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -11,7 +11,6 @@
     "dist/**/*",
     "CHANGELOG.md",
     "internal.d.ts",
-    "mcp-stdio.d.ts",
     "test.d.ts"
   ],
   "scripts": {
@@ -45,12 +44,6 @@
       "import": "./dist/test/index.mjs",
       "module": "./dist/test/index.mjs",
       "require": "./dist/test/index.js"
-    },
-    "./mcp-stdio": {
-      "types": "./dist/mcp-stdio/index.d.ts",
-      "import": "./dist/mcp-stdio/index.mjs",
-      "module": "./dist/mcp-stdio/index.mjs",
-      "require": "./dist/mcp-stdio/index.js"
     }
   },
   "dependencies": {

Analysis

Broken documentation examples reference deleted ai/mcp-stdio module

What fails: Documentation in content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx imports and uses Experimental_StdioMCPTransport from 'ai/mcp-stdio', which no longer exists after source code deletion in commit bde0cd61c

How to reproduce:

# Check that the mcp-stdio source was deleted:
git show bde0cd61c --name-status

# Verify the module no longer exists:
ls packages/ai/mcp-stdio/  # Returns: No such file or directory
ls packages/ai/dist/mcp-stdio/  # Returns: No such file or directory

Result: The import import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio'; will fail with a module not found error because:

  • Source files in packages/ai/mcp-stdio/ were deleted
  • Build configuration in packages/ai/tsup.config.ts was removed
  • No dist/mcp-stdio/ directory exists to satisfy the package.json export

Expected: Documentation should use the official MCP SDK's StdioClientTransport from @modelcontextprotocol/sdk/client/stdio.js as the recommended replacement

Fixed:

  • Updated content/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx to use StdioClientTransport from @modelcontextprotocol/sdk
  • Updated content/docs/03-ai-sdk-core/16-mcp-tools.mdx to remove outdated comment and clarify import source
  • Removed unused import in content/cookbook/01-next/73-mcp-tools.mdx
  • Removed unused import in content/cookbook/05-node/54-mcp-tools.mdx
  • Removed outdated comment in examples/mcp/src/stdio/client.ts
  • Deleted content/docs/07-reference/01-ai-sdk-core/24-mcp-stdio-transport.mdx (dedicated to documenting the removed feature)
  • Removed packages/ai/mcp-stdio.d.ts type definition file
  • Removed ./mcp-stdio export from packages/ai/package.json

@gr2m
Copy link
Collaborator

gr2m commented Oct 1, 2025

Users importing from 'ai/mcp-stdio' will get module not found errors

looks like some usage is out there for this export: https://github.com/search?q=%22ai%2Fmcp-stdio%22&type=code. It's a breaking change, we should document it and create a codemod if possible?

@aayush-kapoor
Copy link
Contributor Author

yeah i didn't realise that - lars said that we don't have any examples for this particular endpoint. So i'm wondering if we should add examples for it or remove it completely and add the codemod?

@gr2m
Copy link
Collaborator

gr2m commented Oct 2, 2025

I'd have to do more research myself. I wonder why it's ai/mcp-stdio and not its own package? Maybe that would make sense as a first step, to remove it from ai core?

@aayush-kapoor
Copy link
Contributor Author

I think it's not that important for us to make it into a separate package given the fact that we just define it in our docs (and don't even have an e2e example for it yet)

i'm also surprised people use it since we, in our docs, also use the official MCP endpoint for this (ref)

also, this transport method is kept separate from other transport methods such as http and sse (which i believe is because of its import of node:child_process api)

Copy link
Contributor

@vercel vercel bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional Comments:

packages/ai/package.json (lines 49-54):
The package.json still exports ./mcp-stdio module (lines 49-54) and includes mcp-stdio.d.ts in the files array (line 14), but all the source files for this module have been deleted in this PR.

View Details
📝 Patch Details
diff --git a/packages/ai/mcp-stdio.d.ts b/packages/ai/mcp-stdio.d.ts
deleted file mode 100644
index 8e853fa3a..000000000
--- a/packages/ai/mcp-stdio.d.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from './dist/mcp-stdio';
diff --git a/packages/ai/package.json b/packages/ai/package.json
index e8dd3658a..23683985e 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -11,7 +11,6 @@
     "dist/**/*",
     "CHANGELOG.md",
     "internal.d.ts",
-    "mcp-stdio.d.ts",
     "test.d.ts"
   ],
   "scripts": {
@@ -45,12 +44,6 @@
       "import": "./dist/test/index.mjs",
       "module": "./dist/test/index.mjs",
       "require": "./dist/test/index.js"
-    },
-    "./mcp-stdio": {
-      "types": "./dist/mcp-stdio/index.d.ts",
-      "import": "./dist/mcp-stdio/index.mjs",
-      "module": "./dist/mcp-stdio/index.mjs",
-      "require": "./dist/mcp-stdio/index.js"
     }
   },
   "dependencies": {
diff --git a/packages/ai/tsconfig.json b/packages/ai/tsconfig.json
index 7dedfdb70..fcf889404 100644
--- a/packages/ai/tsconfig.json
+++ b/packages/ai/tsconfig.json
@@ -15,7 +15,6 @@
     "node_modules",
     "tsup.config.ts",
     "internal.d.ts",
-    "mcp-stdio.d.ts",
     "test.d.ts"
   ],
   "references": [

Analysis

Stale package.json exports reference deleted mcp-stdio module

What fails: The ai/mcp-stdio export in package.json points to non-existent dist/mcp-stdio/ files, causing module not found errors when users try to import this subpath.

How to reproduce:

# After building the package:
cd packages/ai && pnpm build
node -e "require('./dist/mcp-stdio/index.js')"

Result: MODULE_NOT_FOUND: Cannot find module './dist/mcp-stdio/index.js'

Expected: Import should either work or the export should not exist in package.json

Root cause: Commit bde0cd61c deleted all mcp-stdio source files and removed the build configuration from tsup.config.ts, but failed to update package.json exports and files array.

Fixed:

  • Removed "mcp-stdio.d.ts" from files array in package.json
  • Removed "./mcp-stdio" export entry from package.json
  • Deleted packages/ai/mcp-stdio.d.ts file
  • Removed "mcp-stdio.d.ts" from tsconfig.json exclude array

@aayush-kapoor
Copy link
Contributor Author

i've updated the example so that auth window doesn't open on server-side and instead just stores the authURL. on the client side, we use onData to catch the data-oauth part sent by the server and then open the popup directly.

one can also add a small UI fallback button to open the URL manually if a popup blocker prevents opening

This change adds OAuth support for MCP clients and refactors the import path for Experimental_StdioMCPTransport.
Updated import paths for MCP client and transport.
Copy link
Collaborator

@gr2m gr2m left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great work!

@gr2m gr2m added the backport label Oct 24, 2025
@gr2m gr2m merged commit eca63f3 into main Oct 24, 2025
18 checks passed
@gr2m gr2m deleted the aayush/mcp-update branch October 24, 2025 16:42
vercel-ai-sdk bot pushed a commit that referenced this pull request Oct 24, 2025
@vercel-ai-sdk vercel-ai-sdk bot removed the backport label Oct 24, 2025
@vercel-ai-sdk
Copy link
Contributor

vercel-ai-sdk bot commented Oct 24, 2025

⚠️ Backport to release-v5.0 created but has conflicts: #9782

AVtheking pushed a commit to AVtheking/ai that referenced this pull request Oct 25, 2025
…#9127)

## Background

Refactor mcp into it's own separate package + add OAuth for MCP clients

## Summary

Created new package `@ai-sdk/mcp`, added OAuth provider

## Manual Verification

Manual tests added, e2e example added to verify oauth works in
`example/mcp/mcp-with-auth/client.ts`

## 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)
- [x] Formatting issues have been fixed (run `pnpm prettier-fix` in the
project root)

## Future Work

- Continue refactoring, add docs
- log warning or throw error if wrong transport protocol is set for an
mcp server

## Related Issues

towards vercel#8717, vercel#9337 and vercel#6717

---------

Co-authored-by: Gregor Martynus <[email protected]>
gr2m added a commit that referenced this pull request Oct 25, 2025
…ge (#9782)

This is an automated backport of #9127 to the release-v5.0 branch.

---------

Co-authored-by: Aayush Kapoor <[email protected]>
Co-authored-by: Gregor Martynus <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

major marker for PRs with major version bump

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants