如何将 MCP Server 的工具接入 AI SDK 并选择 HTTP 或 stdio 传输-育师

如何将 MCP Server 的工具接入 AI SDK 并选择 HTTP 或 stdio 传输

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai

如果你的应用需要调用某个 MCP Server 暴露的工具（例如查询用户信息的get-user-info、查询宝可梦的get-pokemon），本文给出在 AI SDK 中完成接入的一条连续路径：安装@ai-sdk/mcp，用createMCPClient建立连接，用mcpClient.tools()把 MCP 工具转换成 AI SDK 工具传给generateText/streamText，并在结束时关闭客户端。AI SDK 文档明确建议：生产部署使用 HTTP 传输；stdio 传输仅用于连接本地服务器，因为它无法部署到生产环境。因此传输方式的选择首先取决于你的 MCP Server 是远程服务还是本机进程。

安装依赖

MCP 客户端在@ai-sdk/mcp模块中，与 AI SDK 核心包和zod一起安装：

npm i @ai-sdk/mcp ai zod

如果打算使用 MCP 官方 TypeScript SDK 的传输实现（StdioClientTransport、StreamableHTTPClientTransport、SSEClientTransport），再额外安装官方 SDK：

pnpm install @modelcontextprotocol/sdk

两种来源的传输可以混用：文档同时展示了「直接传transport配置对象」和「传入官方 SDK 的 transport 实例」两种写法，AI SDK 自带的 stdio 传输（Experimental_StdioMCPTransport，从@ai-sdk/mcp/mcp-stdio子路径导入）则是本地开发时的可选替代。

传输方式如何选

文档给出的选择标准只有一条硬边界：

HTTP 传输（推荐，生产部署）：通过transport: { type: 'http', url: ... }直接配置，或使用官方 SDK 的StreamableHTTPClientTransport。支持headers鉴权头、authProviderOAuth 自动授权，redirect默认'error'以防止 SSRF，可按需改为'follow'。
SSE 传输：另一种基于 HTTP 的传输，配置方式为type: 'sse'加url，同样支持headers和authProvider，适用于使用 Server-Sent Events 的 MCP Server。
stdio 传输（仅限本地）：通过标准输入/输出流连接本机 MCP 进程，只适用于本地开发，文档明确警告不要用于生产。

关于协议版本，AI SDK MCP 客户端同时支持基于initialize握手的旧版协议和无状态的 MCP2026-07-28：内置 stdio 传输会先用server/discover探测，旧服务器自动回退到传统initialize握手；自定义传输可通过supportsProtocolVersionDiscovery: true加入同样的协商。

连接远程 MCP Server：HTTP 传输

最短主路径是直接传 transport 配置，无需官方 SDK：

import { createMCPClient } from '@ai-sdk/mcp'; const mcpClient = await createMCPClient({ transport: { type: 'http', url: 'https://your-server.com/mcp', // 可选：配置 HTTP 请求头 headers: { Authorization: 'Bearer my-api-key' }, // 可选：提供 OAuth client provider 实现自动授权 authProvider: myOAuthClientProvider, // 可选：允许重定向（默认 'error' 用于防止 SSRF） redirect: 'follow', }, });

把https://your-server.com/mcp换成你的 MCP Server 的 Streamable HTTP 端点，my-api-key和myOAuthClientProvider分别替换为你的实际密钥和 OAuth provider 实例；不需要鉴权的 Server 可以删除headers/authProvider两行。

也可以改用官方 SDK 的StreamableHTTPClientTransport：

import { createMCPClient } from '@ai-sdk/mcp'; import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; const url = new URL('https://your-server.com/mcp'); const mcpClient = await createMCPClient({ transport: new StreamableHTTPClientTransport(url, { sessionId: 'session_123', }), });

如果连接的是使用 Streamable HTTP 会话的旧版 MCP Server，还可以用initialSessionId+initialInitializeResult恢复已保存的会话，并用onSessionIdChange/onSessionExpired回调维护会话状态；terminateSessionOnClose: false表示只关闭本地客户端而保留会话以便后续重连。MCP2026-07-28是无状态的，不使用这些选项。会话过期时传输层已清空 session id 且请求仍会以下层 HTTP 错误失败，此时应去掉initialSessionId和initialInitializeResult重新创建客户端重试。

连接本地 MCP Server：stdio 传输

stdio 传输启动一个子进程并通过 stdin/stdout 通信，因此command和args指向要启动的本地服务器入口。以仓库中的 pokemon 示例为例，服务器入口编译后位于src/stdio/dist/server.js，客户端代码为：

import { createMCPClient } from '@ai-sdk/mcp'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; // 或者使用 AI SDK 自带的 stdio 传输： // import { Experimental_StdioMCPTransport as StdioClientTransport } from '@ai-sdk/mcp/mcp-stdio'; const mcpClient = await createMCPClient({ transport: new StdioClientTransport({ command: 'node', args: ['src/stdio/dist/server.js'], }), });

把args替换为你自己 MCP Server 的实际启动脚本路径。仓库示例 examples/mcp/src/stdio/client.ts 还展示了可选的env参数（示例中传入env: { FOO: 'bar' }）用于给子进程指定环境变量。注意 stdio 传输只在本地有效，文档标注其不应部署到生产环境。

获取工具并调用模型

客户端的tools方法是 MCP 工具与 AI SDK 工具之间的适配器，有两种取法。

Schema Discovery：列出服务器提供的全部工具，输入参数类型依据服务器给出的 schema 推断：

const tools = await mcpClient.tools();

实现简单、自动跟随服务器变更，但没有 TypeScript 类型安全，且会加载服务器上的所有工具。

显式定义 Schema：在客户端代码中用 zod 声明需要的工具与输入 schema，客户端只拉取显式定义的工具，能获得完整的类型安全与 IDE 补全：

import { z } from 'zod'; const tools = await mcpClient.tools({ schemas: { 'get-data': { inputSchema: z.object({ query: z.string().describe('The data query'), format: z.enum(['json', 'text']).optional(), }), }, // 无入参的工具使用空对象 'tool-with-no-args': { inputSchema: z.object({}), }, }, });

工具拿到后直接传给 AI SDK 调用。非流式调用用 try/finally 保证客户端关闭：

import { createMCPClient, type MCPClient } from '@ai-sdk/mcp'; import { generateText, isStepCount } from 'ai'; let mcpClient: MCPClient | undefined; try { mcpClient = await createMCPClient({ transport: { type: 'http', url: 'https://your-server.com/mcp', }, }); 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(); }

（模型标识'openai/gpt-5.4'取自仓库文档示例，按你实际使用的 provider 与模型替换。）

关闭 MCP 客户端

客户端是轻量客户端，用完必须关闭以释放资源，关闭时机取决于使用模式：

短时使用（如单次请求）：响应结束后关闭。
长驻客户端（如命令行应用）：保持打开，但确保应用退出时关闭。

使用streamText流式响应时，在onEnd回调里关闭：

const mcpClient = await createMCPClient({ // ... }); const tools = await mcpClient.tools(); const result = await streamText({ model: __MODEL__, // 替换为你的模型 tools, prompt: 'What is the weather in Brooklyn, New York?', onEnd: async () => { await mcpClient.close(); }, });

非流式生成则使用 try/finally 或框架的清理函数（见上一节完整示例）。

用仓库示例验证接入是否成功

仓库内置了可直接运行的 MCP 示例（examples/mcp），可以把它当作「HTTP 服务器 + 客户端」端到端的参考实现：

在仓库根目录创建/配置.env，至少包含模型 API key，示例文档给出的内容为：

OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

安装并构建：

pnpm install pnpm build

一个终端启动 HTTP MCP Server（监听 3000 端口，见 examples/mcp/src/http/server.ts）：

pnpm server:http

另一个终端运行客户端（examples/mcp/src/http/client.ts）：

pnpm client:http

客户端会连接http://localhost:3000/mcp，调用示例服务器提供的get-user-info工具，并在控制台打印每一步的工具结果和最终答案：

STEP RESULTS: ... FINAL ANSWER: ...

看到STEP RESULTS（工具调用步骤结果）与FINAL ANSWER（模型最终回答）输出，说明 MCP 工具已经成功接入并被模型调用。（上述输出标签来自示例代码的console.log，具体内容为运行结果，非固定文案。）

stdio 路径的验证方式是仓库中的 pokemon 示例：先编译服务器入口，再运行客户端：

pnpm stdio:build pnpm client:stdio

stdio:build会把src/stdio/server.ts编译到src/stdio/dist，client:stdio启动该服务器子进程并让模型调用get-pokemon工具，同样以STEP RESULTS与FINAL ANSWER输出作为验证点。

限制与注意点

createMCPClient返回的是轻量客户端，面向工具转换场景，不支持完整 MCP 客户端的全部能力（如自动会话持久化、可恢复流、接收通知）。
stdio 传输仅限本地服务器，文档明确不建议用于生产。
临时性工具调用失败（限流、临时过载、网关超时等）可传入maxRetries对tools/call请求自动重试，重试默认关闭；但只对幂等安全的工具开启——文档警告，对发送邮件、创建记录这类非幂等工具重试会产生重复副作用。JSON-RPC 应用层错误（如非法工具参数）和isError: true的响应不会重试，直接返回模型。
MCP 工具注解（readOnlyHint、destructiveHint等）是服务器提供的不可信提示，客户端不会自动把它们变成审批策略；需要审批控制时应结合工具白名单、限权凭据和 AI SDK 的toolApproval策略自行实现。