AI SDK MCP 客户端实战使用 ai-sdk/mcp 将 MCP 服务器工具接入 generateText 与 streamText【免费下载链接】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导读本文基于当前仓库中packages/mcp包的官方 README系统讲解 AI SDKThe AI Toolkit for TypeScript的Model Context ProtocolMCP客户端的完整用法。你将学会用createMCPClient()连接远程 HTTP/SSE 或本地 stdio 类型的 MCP 服务器通过mcpClient.tools()拉取服务器工具并直接喂给generateText、streamText等 AI SDK 核心调用执行工具调用同时掌握 MCP 协议版本协商、会话持久化与自定义传输层等进阶能力。读完即可在自己的 AI 应用中集成任意 MCP 服务器生态。一、MCP 客户端在 AI SDK 中的定位Model Context ProtocolMCP为 AI 应用与外部工具/数据源之间定义了标准化的通信协议。AI SDK 的 MCP 客户端ai-sdk/mcp将MCP 服务器暴露的工具转换为 AI SDK 标准工具对象从而让模型调用可以像使用普通 AI SDK 工具一样通过tools选项直接使用这些远程工具。从包入口 packages/mcp/src/index.ts 可以看到该包稳定导出的核心能力包括createMCPClient、MCPClientConfig、MCPClient客户端创建入口与类型MCPTransport、MCPTransportConfig及 HTTP/SSE/stdio 传输层auth、UnauthorizedError与 OAuth 相关类型OAuthClientProvider、OAuthTokens等完整的 MCP 结果/参数 Schema 与类型CallToolResult、InitializeResult、ListToolsResult、ElicitationRequest/ElicitResult等。同时保留experimental_createMCPClient等旧命名作为deprecated别名packages/mcp/src/index.ts老代码仍可运行但官方推荐使用新命名。二、安装与运行环境在任意支持 Node.js 的项目中安装 MCP 客户端npm i ai-sdk/mcp ai zod根据 packages/mcp/package.json 中的实际声明需要注意几点运行前提Node.js 版本engines.node要求22zod 版本peer 依赖为^3.25.76 || ^4.1.8安装zod时必须满足该范围子路径导出包提供了ai-sdk/mcp主入口与ai-sdk/mcp/mcp-stdiostdio 传输层专用子路径见 packages/mcp/package.json两个入口stdio 用法中会用到后者。三、为编码 Agent 安装 AI SDK Skill可选如果你使用 Claude Code、Cursor 等编码 Agent 来开发 AI 应用官方强烈建议将 AI SDK skill 添加到仓库让 Agent 获得准确的 API 使用知识npx skills add vercel/ai这条命令会在仓库中安装 AI SDK 的使用指南skill属于开发提效的可选项不影响运行时功能。四、快速上手用 generateText 调用 MCP 工具MCP 客户端的核心使用流程只有三步创建客户端 → 拉取工具 → 传给 AI SDK 调用。以远程 HTTP 服务器为例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(); }关键点拆解createMCPClient()返回一个已初始化的MCPClient实例源码中createMCPClient内部会调用new DefaultMCPClient(config)并执行client.init()见 packages/mcp/src/tool/mcp-client.ts因此无需手动执行握手mcpClient.tools()会请求tools/list自动处理nextCursor分页见 packages/mcp/src/tool/mcp-client.ts把 MCP 工具定义转换为 AI SDK 工具集合转换后的工具可通过标准tools选项传入generateText模型即可在对话中自主调用stopWhen: isStepCount(10)限制最多 10 步工具调用避免无限循环用完必须在finally中调用mcpClient.close()释放连接。工具转换的底层逻辑从源码看tools()生成的每个 AI SDK 工具都会携带从 MCP 定义继承的description、title取自title ?? annotations?.title、inputSchemaJSON Schema 自动推断无需手动定义参数以及_meta元数据执行时通过tools/call请求调用服务器packages/mcp/src/tool/mcp-client.ts。MCP 返回的content数组会被转换为 AI SDK 可消费的输出格式text内容映射为文本image内容映射为文件数据见 packages/mcp/src/tool/mcp-client.ts。五、MCPClient 配置与 API 全景5.1 createMCPClient 配置项MCPClientConfig定义于 packages/mcp/src/tool/mcp-client.ts支持以下配置配置项类型默认值说明transportMCPTransportConfig \| MCPTransport必填传输配置对象type: http \| sse或自定义传输实例protocolVersionDiscoverybooleantrue是否允许支持无状态发现的传输层先用server/discover探测协议版本对要求initialize必须为第一个请求的旧服务器可设为falseinitializationOptionsRequestOptions—限制/取消传输启动与initialize请求支持signal、timeout、maxTotalTimeoutonUncaughtError(error) void—未捕获错误回调maxRetriesnumber0瞬时性tools/call失败的最大重试次数须为0的整数设为 0 关闭重试initialInitializeResultInitializeResult—复用历史会话的初始化结果传入后不再发送新的initialize请求clientNamestringai-sdk-mcp-client客户端名称旧名name已弃用versionstring1.0.0客户端版本capabilitiesClientCapabilities{}初始化时向服务器广播的客户端能力如elicitation5.2 MCPClient 实例方法客户端实例提供的方法接口定义见 packages/mcp/src/tool/mcp-client.ts成员说明serverInfo初始化时服务器报告的自身信息name/versioninitializeResult本次会话使用的完整 initialize 结果来自服务器或initialInitializeResultinstructions服务器在握手时提供的使用说明可注入系统提示词以改善模型与服务器交互tools({ schemas? })拉取服务器全部工具并转换为 AI SDK 工具集合自动分页toolsFromDefinitions(definitions, { schemas? })不请求服务器直接根据工具定义列表生成 AI SDK 工具listTools()/callTool()底层 MCP 方法列出工具 / 调用指定工具listResources()/readResource()/listResourceTemplates()MCP 资源能力experimental_listPrompts()/experimental_getPrompt()MCP 提示词能力实验性complete()MCP 补全能力completion/completeonElicitationRequest(schema, handler)注册处理服务器发来的elicitation/create请求的处理器close()关闭传输并清理连接从源码看所有请求都经由统一的request()方法发送该方法会执行服务器能力校验如未声明tools能力就调用tools/list会直接报错见 packages/mcp/src/tool/mcp-client.ts、请求超时控制与 JSON-RPC 响应匹配按自增id关联请求/响应。六、协议版本协商legacy 握手与现代无状态发现MCP 协议存在多个版本。本客户端支持两条协商路径相关常量定义在 packages/mcp/src/tool/types.tsexport const LATEST_PROTOCOL_VERSION 2026-07-28; export const LATEST_LEGACY_PROTOCOL_VERSION 2025-11-25; export const SUPPORTED_PROTOCOL_VERSIONS [ LATEST_PROTOCOL_VERSION, // 2026-07-28 LATEST_LEGACY_PROTOCOL_VERSION, // 2025-11-25 2025-06-18, 2025-03-26, 2024-11-05, ];Legacy 版本通过传统的initialize握手协商支持2025-11-25及更早的协议版本SUPPORTED_PROTOCOL_VERSIONS列出的全部版本现代版本2026-07-28通过无状态协议发现stateless protocol discovery完成。客户端先发送server/discover探测请求服务器在supportedVersions中声明支持的版本发现过程默认超时为 1000ms源码常量DEFAULT_PROTOCOL_DISCOVERY_TIMEOUT见 packages/mcp/src/tool/mcp-client.ts。协商流程创建客户端后若protocolVersionDiscovery为true且传输层声明supportsProtocolVersionDiscovery则先尝试server/discoverpackages/mcp/src/tool/mcp-client.ts若发现成功进入 modern 时代若服务器不支持返回非现代协议错误码则自动回退到 legacyinitialize握手流程内置的stdio 传输同样会先探测server/discover连接旧版服务器时自动回退到 legacy 握手自定义传输可通过设置supportsProtocolVersionDiscovery: true主动选择加入同样的协商机制。在现代协议下每次请求都会在params._meta中携带协议版本、客户端能力与客户端信息io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientCapabilities、io.modelcontextprotocol/clientInfo由服务器按需读取见 packages/mcp/src/tool/mcp-client.ts。七、传输层详解HTTP、SSE 与 stdio7.1 HTTPStreamable HTTP—— 生产环境推荐HTTP 是官方推荐用于生产部署的传输方式。其实现HttpMCPTransport见 packages/mcp/src/tool/mcp-http-transport.ts遵循 MCP Streamable HTTP 规范POST 发送 JSON-RPC 消息GET Server-Sent Events 接收消息同时内置入站 SSE 断线重连指数退避最多重试 2 次。transport配置对象支持以下参数定义于 packages/mcp/src/tool/mcp-transport.ts参数默认值说明type必填http或sseurl必填MCP 服务器地址headers—随请求发送的附加 HTTP 头如认证令牌authProvider—可选 OAuth 客户端提供者用于 MCP 服务器认证redirecterrorHTTP 重定向策略follow跟随标准 fetch 行为或error拒绝重定向initialSessionId—恢复会话时发送的初始 MCP 会话 ID仅 HTTP 传输initialProtocolVersion—协商前的初始协议版本仅 HTTP 传输缺省用最新 legacy 版本onSessionIdChange—服务器创建/变更/清除会话 ID 时回调仅 HTTPonSessionExpired—服务器对既有会话 ID 返回 404 时回调仅 HTTPterminateSessionOnClosetrueclose()时是否发送 DELETE 终止当前会话设为false以允许后续重连复用会话仅 HTTPfetchglobalThis.fetch自定义 fetch 实现适合需要请求局部 fetch 的运行时会话持久化仅 Legacy 协议会话持久化只适用于 legacy MCP 协议版本。2026-07-28是无状态协议不使用会话 ID也不缓存 initialize 结果。下面是一个完整的会话保存/恢复示例继承自官方 READMEloadMcpSession/saveMcpSession/clearMcpSession为应用侧自定义的持久化函数import { createMCPClient } from ai-sdk/mcp; const savedSession await loadMcpSession(); let currentSessionId savedSession?.sessionId; const mcpClient await createMCPClient({ transport: { type: http, url: https://your-server.com/mcp, initialSessionId: savedSession?.sessionId, initialProtocolVersion: savedSession?.initializeResult.protocolVersion, terminateSessionOnClose: false, onSessionIdChange: sessionId { currentSessionId sessionId; }, onSessionExpired: sessionId { if (currentSessionId sessionId) { currentSessionId undefined; void clearMcpSession(); } }, }, initialInitializeResult: savedSession?.initializeResult, }); if (currentSessionId) { await saveMcpSession({ sessionId: currentSessionId, initializeResult: mcpClient.initializeResult, }); }要点terminateSessionOnClose: false表示关闭客户端时不发送 DELETE之后可用保存的sessionId重新附着initialInitializeResult复用上次的握手元数据跳过新的 initialize 请求直接进入可用状态见 packages/mcp/src/tool/mcp-client.ts服务器换发新会话 ID 时触发onSessionIdChange会话失效404时触发onSessionExpired据此更新或清空持久化状态。7.2 SSEServer-Sent Events对使用 Server-Sent Events 的 MCP 服务器可切换type: sseconst mcpClient await createMCPClient({ transport: { type: sse, url: https://your-server.com/sse, }, });SSE 传输实现见 packages/mcp/src/tool/mcp-sse-transport.ts。7.3 stdio —— 本地 MCP 服务器对于本地 MCP 服务器以子进程方式启动使用ai-sdk/mcp/mcp-stdio子路径提供的Experimental_StdioMCPTransportimport { 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], }), });从源码看StdioMCPTransportpackages/mcp/src/tool/mcp-stdio/mcp-stdio-transport.ts以子进程方式启动command通过stdin/stdout 传输以换行分隔的 JSON-RPC 消息每行一条消息JSON.stringify(message) \n并声明supportsProtocolVersionDiscovery true即会先尝试server/discover再回退 legacy 握手。其构造函数接受StdioConfig参数说明command要启动的可执行命令args命令参数数组env附加环境变量stderrstderr 的 IO 类型如pipe、流或文件描述符cwd子进程工作目录仓库示例 examples/mcp/src/stdio/client.ts 展示了完整用法包括通过env注入环境变量以及用tools({ schemas })显式声明工具入参 SchemamcpClient await createMCPClient({ transport: stdioTransport, }); const { text: answer } await generateText({ model: openai(gpt-4o-mini), tools: await mcpClient.tools({ schemas: { get-pokemon: { inputSchema: z.object({ name: z.string() }), }, }, }), stopWhen: isStepCount(10), ... });八、流式输出streamText 及时关闭对于流式场景使用streamText并在流结束时关闭 MCP 客户端onEnd回调中执行mcpClient.close()避免连接泄漏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., onEnd: async () { await mcpClient.close(); }, }); for await (const textPart of result.textStream) { process.stdout.write(textPart); }九、进阶主题9.1 自定义传输层MCPTransport是连接 MCP 协议与底层 I/O 的抽象接口packages/mcp/src/tool/mcp-transport.ts实现自定义传输需提供start()、send(message, options?)、close(options?)三个核心方法事件回调onmessage、onclose、onerror可选能力标记supportsProtocolVersionDiscovery是否支持server/discover探测与supportsMcpToolParameterHeaders是否支持将工具的x-mcp-header参数镜像到请求头HTTP 传输已启用该项可选protocolVersion/setProtocolVersion()用于版本协商。createMCPClient会自动识别自定义传输只要对象同时具备start/send/close方法就按MCPTransport处理否则按内置配置创建见 packages/mcp/src/tool/mcp-transport.ts。例如使用官方 MCP SDK 的StdioClientTransport、StreamableHTTPClientTransport等实例也可直接传入仓库示例 examples/mcp/src/http/client.ts 与 examples/mcp/src/stdio/client.ts 均有演示。9.2 OAuth 认证对需要 OAuth 的 MCP 服务器可通过authProvider配置 OAuth 客户端提供者OAuthClientProvider。认证逻辑集中在 packages/mcp/src/tool/oauth.tsHTTP 传输在收到401及WWW-Authenticate头时会自动驱动授权流程extractWWWAuthenticateParams、auth等失败抛出UnauthorizedError。参考示例examples/mcp/src/mcp-with-auth/client.ts。9.3 工具重试策略maxRetries控制tools/call的瞬时失败重试。默认关闭0开启后仅对可重试的瞬时错误生效HTTP 状态码408、409、429及 500或错误码命中ConnectionRefused、ECONNRESET、ECONNREFUSED、ETIMEDOUT、EPIPE等见 packages/mcp/src/tool/mcp-client.ts。JSON-RPC 应用层错误如 invalid params不会重试。重试采用指数退避策略。9.4 服务器指令与输出 Schemaclient.instructions携带服务器握手时返回的使用说明可将其注入系统提示词帮助模型正确使用服务器示例见 examples/mcp/src/server-instructions/client.tstools({ schemas })可显式覆盖工具入参/出参 SchemazodoutputSchema提供时客户端会校验并提取服务器的structuredContent缺失时回退解析 text 内容见 packages/mcp/src/tool/mcp-client.ts。十、仓库中的验证与更多示例仓库提供了大量可直接运行的一手示例与测试可作为学习与验证依据示例集合examples/mcp目录包含 http、sse、stdio、http-2026现代协议、server-info、server-instructions、output-schema、provider-metadata、mcp-resources、mcp-prompts、elicitation、image-content、tool-annotations、tool-meta、shopify-mcp、mcp-with-auth 等 16 个客户端示例单元测试客户端核心逻辑见 packages/mcp/src/tool/mcp-client.test.tsstdio 传输见 packages/mcp/src/tool/mcp-stdio/mcp-stdio-transport.test.ts另含 JSON-RPC 消息解析、HTTP 头、OAuth、MCP App 指纹等专项测试包配置构建、类型检查与测试脚本见 packages/mcp/package.jsonpnpm build、pnpm test:node、pnpm test:edge等仓库内通过 pnpm workspace 统一管理依赖。总结ai-sdk/mcp是 AI SDK 与 MCP 生态之间的桥梁createMCPClient()一条命令即可建立连接tools()将服务器工具无缝转换为 AI SDK 工具配合generateText/streamText即可让模型自主使用任意 MCP 服务器的能力。生产部署优先选择 HTTP 传输并善用会话持久化接入本地工具链则使用 stdio 传输遇到特殊协议可借助自定义MCPTransport与协议版本协商机制灵活适配。结合本仓库examples/mcp的完整示例与各传输层的单元测试你可以快速落地一个生产可用的 MCP 工具调用链路。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AI SDK MCP 客户端实战：使用 @ai-sdk/mcp 将 MCP 服务器工具接入 generateText 与 streamText
AI SDK MCP 客户端实战使用 ai-sdk/mcp 将 MCP 服务器工具接入 generateText 与 streamText【免费下载链接】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导读本文基于当前仓库中packages/mcp包的官方 README系统讲解 AI SDKThe AI Toolkit for TypeScript的Model Context ProtocolMCP客户端的完整用法。你将学会用createMCPClient()连接远程 HTTP/SSE 或本地 stdio 类型的 MCP 服务器通过mcpClient.tools()拉取服务器工具并直接喂给generateText、streamText等 AI SDK 核心调用执行工具调用同时掌握 MCP 协议版本协商、会话持久化与自定义传输层等进阶能力。读完即可在自己的 AI 应用中集成任意 MCP 服务器生态。一、MCP 客户端在 AI SDK 中的定位Model Context ProtocolMCP为 AI 应用与外部工具/数据源之间定义了标准化的通信协议。AI SDK 的 MCP 客户端ai-sdk/mcp将MCP 服务器暴露的工具转换为 AI SDK 标准工具对象从而让模型调用可以像使用普通 AI SDK 工具一样通过tools选项直接使用这些远程工具。从包入口 packages/mcp/src/index.ts 可以看到该包稳定导出的核心能力包括createMCPClient、MCPClientConfig、MCPClient客户端创建入口与类型MCPTransport、MCPTransportConfig及 HTTP/SSE/stdio 传输层auth、UnauthorizedError与 OAuth 相关类型OAuthClientProvider、OAuthTokens等完整的 MCP 结果/参数 Schema 与类型CallToolResult、InitializeResult、ListToolsResult、ElicitationRequest/ElicitResult等。同时保留experimental_createMCPClient等旧命名作为deprecated别名packages/mcp/src/index.ts老代码仍可运行但官方推荐使用新命名。二、安装与运行环境在任意支持 Node.js 的项目中安装 MCP 客户端npm i ai-sdk/mcp ai zod根据 packages/mcp/package.json 中的实际声明需要注意几点运行前提Node.js 版本engines.node要求22zod 版本peer 依赖为^3.25.76 || ^4.1.8安装zod时必须满足该范围子路径导出包提供了ai-sdk/mcp主入口与ai-sdk/mcp/mcp-stdiostdio 传输层专用子路径见 packages/mcp/package.json两个入口stdio 用法中会用到后者。三、为编码 Agent 安装 AI SDK Skill可选如果你使用 Claude Code、Cursor 等编码 Agent 来开发 AI 应用官方强烈建议将 AI SDK skill 添加到仓库让 Agent 获得准确的 API 使用知识npx skills add vercel/ai这条命令会在仓库中安装 AI SDK 的使用指南skill属于开发提效的可选项不影响运行时功能。四、快速上手用 generateText 调用 MCP 工具MCP 客户端的核心使用流程只有三步创建客户端 → 拉取工具 → 传给 AI SDK 调用。以远程 HTTP 服务器为例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(); }关键点拆解createMCPClient()返回一个已初始化的MCPClient实例源码中createMCPClient内部会调用new DefaultMCPClient(config)并执行client.init()见 packages/mcp/src/tool/mcp-client.ts因此无需手动执行握手mcpClient.tools()会请求tools/list自动处理nextCursor分页见 packages/mcp/src/tool/mcp-client.ts把 MCP 工具定义转换为 AI SDK 工具集合转换后的工具可通过标准tools选项传入generateText模型即可在对话中自主调用stopWhen: isStepCount(10)限制最多 10 步工具调用避免无限循环用完必须在finally中调用mcpClient.close()释放连接。工具转换的底层逻辑从源码看tools()生成的每个 AI SDK 工具都会携带从 MCP 定义继承的description、title取自title ?? annotations?.title、inputSchemaJSON Schema 自动推断无需手动定义参数以及_meta元数据执行时通过tools/call请求调用服务器packages/mcp/src/tool/mcp-client.ts。MCP 返回的content数组会被转换为 AI SDK 可消费的输出格式text内容映射为文本image内容映射为文件数据见 packages/mcp/src/tool/mcp-client.ts。五、MCPClient 配置与 API 全景5.1 createMCPClient 配置项MCPClientConfig定义于 packages/mcp/src/tool/mcp-client.ts支持以下配置配置项类型默认值说明transportMCPTransportConfig \| MCPTransport必填传输配置对象type: http \| sse或自定义传输实例protocolVersionDiscoverybooleantrue是否允许支持无状态发现的传输层先用server/discover探测协议版本对要求initialize必须为第一个请求的旧服务器可设为falseinitializationOptionsRequestOptions—限制/取消传输启动与initialize请求支持signal、timeout、maxTotalTimeoutonUncaughtError(error) void—未捕获错误回调maxRetriesnumber0瞬时性tools/call失败的最大重试次数须为0的整数设为 0 关闭重试initialInitializeResultInitializeResult—复用历史会话的初始化结果传入后不再发送新的initialize请求clientNamestringai-sdk-mcp-client客户端名称旧名name已弃用versionstring1.0.0客户端版本capabilitiesClientCapabilities{}初始化时向服务器广播的客户端能力如elicitation5.2 MCPClient 实例方法客户端实例提供的方法接口定义见 packages/mcp/src/tool/mcp-client.ts成员说明serverInfo初始化时服务器报告的自身信息name/versioninitializeResult本次会话使用的完整 initialize 结果来自服务器或initialInitializeResultinstructions服务器在握手时提供的使用说明可注入系统提示词以改善模型与服务器交互tools({ schemas? })拉取服务器全部工具并转换为 AI SDK 工具集合自动分页toolsFromDefinitions(definitions, { schemas? })不请求服务器直接根据工具定义列表生成 AI SDK 工具listTools()/callTool()底层 MCP 方法列出工具 / 调用指定工具listResources()/readResource()/listResourceTemplates()MCP 资源能力experimental_listPrompts()/experimental_getPrompt()MCP 提示词能力实验性complete()MCP 补全能力completion/completeonElicitationRequest(schema, handler)注册处理服务器发来的elicitation/create请求的处理器close()关闭传输并清理连接从源码看所有请求都经由统一的request()方法发送该方法会执行服务器能力校验如未声明tools能力就调用tools/list会直接报错见 packages/mcp/src/tool/mcp-client.ts、请求超时控制与 JSON-RPC 响应匹配按自增id关联请求/响应。六、协议版本协商legacy 握手与现代无状态发现MCP 协议存在多个版本。本客户端支持两条协商路径相关常量定义在 packages/mcp/src/tool/types.tsexport const LATEST_PROTOCOL_VERSION 2026-07-28; export const LATEST_LEGACY_PROTOCOL_VERSION 2025-11-25; export const SUPPORTED_PROTOCOL_VERSIONS [ LATEST_PROTOCOL_VERSION, // 2026-07-28 LATEST_LEGACY_PROTOCOL_VERSION, // 2025-11-25 2025-06-18, 2025-03-26, 2024-11-05, ];Legacy 版本通过传统的initialize握手协商支持2025-11-25及更早的协议版本SUPPORTED_PROTOCOL_VERSIONS列出的全部版本现代版本2026-07-28通过无状态协议发现stateless protocol discovery完成。客户端先发送server/discover探测请求服务器在supportedVersions中声明支持的版本发现过程默认超时为 1000ms源码常量DEFAULT_PROTOCOL_DISCOVERY_TIMEOUT见 packages/mcp/src/tool/mcp-client.ts。协商流程创建客户端后若protocolVersionDiscovery为true且传输层声明supportsProtocolVersionDiscovery则先尝试server/discoverpackages/mcp/src/tool/mcp-client.ts若发现成功进入 modern 时代若服务器不支持返回非现代协议错误码则自动回退到 legacyinitialize握手流程内置的stdio 传输同样会先探测server/discover连接旧版服务器时自动回退到 legacy 握手自定义传输可通过设置supportsProtocolVersionDiscovery: true主动选择加入同样的协商机制。在现代协议下每次请求都会在params._meta中携带协议版本、客户端能力与客户端信息io.modelcontextprotocol/protocolVersion、io.modelcontextprotocol/clientCapabilities、io.modelcontextprotocol/clientInfo由服务器按需读取见 packages/mcp/src/tool/mcp-client.ts。七、传输层详解HTTP、SSE 与 stdio7.1 HTTPStreamable HTTP—— 生产环境推荐HTTP 是官方推荐用于生产部署的传输方式。其实现HttpMCPTransport见 packages/mcp/src/tool/mcp-http-transport.ts遵循 MCP Streamable HTTP 规范POST 发送 JSON-RPC 消息GET Server-Sent Events 接收消息同时内置入站 SSE 断线重连指数退避最多重试 2 次。transport配置对象支持以下参数定义于 packages/mcp/src/tool/mcp-transport.ts参数默认值说明type必填http或sseurl必填MCP 服务器地址headers—随请求发送的附加 HTTP 头如认证令牌authProvider—可选 OAuth 客户端提供者用于 MCP 服务器认证redirecterrorHTTP 重定向策略follow跟随标准 fetch 行为或error拒绝重定向initialSessionId—恢复会话时发送的初始 MCP 会话 ID仅 HTTP 传输initialProtocolVersion—协商前的初始协议版本仅 HTTP 传输缺省用最新 legacy 版本onSessionIdChange—服务器创建/变更/清除会话 ID 时回调仅 HTTPonSessionExpired—服务器对既有会话 ID 返回 404 时回调仅 HTTPterminateSessionOnClosetrueclose()时是否发送 DELETE 终止当前会话设为false以允许后续重连复用会话仅 HTTPfetchglobalThis.fetch自定义 fetch 实现适合需要请求局部 fetch 的运行时会话持久化仅 Legacy 协议会话持久化只适用于 legacy MCP 协议版本。2026-07-28是无状态协议不使用会话 ID也不缓存 initialize 结果。下面是一个完整的会话保存/恢复示例继承自官方 READMEloadMcpSession/saveMcpSession/clearMcpSession为应用侧自定义的持久化函数import { createMCPClient } from ai-sdk/mcp; const savedSession await loadMcpSession(); let currentSessionId savedSession?.sessionId; const mcpClient await createMCPClient({ transport: { type: http, url: https://your-server.com/mcp, initialSessionId: savedSession?.sessionId, initialProtocolVersion: savedSession?.initializeResult.protocolVersion, terminateSessionOnClose: false, onSessionIdChange: sessionId { currentSessionId sessionId; }, onSessionExpired: sessionId { if (currentSessionId sessionId) { currentSessionId undefined; void clearMcpSession(); } }, }, initialInitializeResult: savedSession?.initializeResult, }); if (currentSessionId) { await saveMcpSession({ sessionId: currentSessionId, initializeResult: mcpClient.initializeResult, }); }要点terminateSessionOnClose: false表示关闭客户端时不发送 DELETE之后可用保存的sessionId重新附着initialInitializeResult复用上次的握手元数据跳过新的 initialize 请求直接进入可用状态见 packages/mcp/src/tool/mcp-client.ts服务器换发新会话 ID 时触发onSessionIdChange会话失效404时触发onSessionExpired据此更新或清空持久化状态。7.2 SSEServer-Sent Events对使用 Server-Sent Events 的 MCP 服务器可切换type: sseconst mcpClient await createMCPClient({ transport: { type: sse, url: https://your-server.com/sse, }, });SSE 传输实现见 packages/mcp/src/tool/mcp-sse-transport.ts。7.3 stdio —— 本地 MCP 服务器对于本地 MCP 服务器以子进程方式启动使用ai-sdk/mcp/mcp-stdio子路径提供的Experimental_StdioMCPTransportimport { 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], }), });从源码看StdioMCPTransportpackages/mcp/src/tool/mcp-stdio/mcp-stdio-transport.ts以子进程方式启动command通过stdin/stdout 传输以换行分隔的 JSON-RPC 消息每行一条消息JSON.stringify(message) \n并声明supportsProtocolVersionDiscovery true即会先尝试server/discover再回退 legacy 握手。其构造函数接受StdioConfig参数说明command要启动的可执行命令args命令参数数组env附加环境变量stderrstderr 的 IO 类型如pipe、流或文件描述符cwd子进程工作目录仓库示例 examples/mcp/src/stdio/client.ts 展示了完整用法包括通过env注入环境变量以及用tools({ schemas })显式声明工具入参 SchemamcpClient await createMCPClient({ transport: stdioTransport, }); const { text: answer } await generateText({ model: openai(gpt-4o-mini), tools: await mcpClient.tools({ schemas: { get-pokemon: { inputSchema: z.object({ name: z.string() }), }, }, }), stopWhen: isStepCount(10), ... });八、流式输出streamText 及时关闭对于流式场景使用streamText并在流结束时关闭 MCP 客户端onEnd回调中执行mcpClient.close()避免连接泄漏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., onEnd: async () { await mcpClient.close(); }, }); for await (const textPart of result.textStream) { process.stdout.write(textPart); }九、进阶主题9.1 自定义传输层MCPTransport是连接 MCP 协议与底层 I/O 的抽象接口packages/mcp/src/tool/mcp-transport.ts实现自定义传输需提供start()、send(message, options?)、close(options?)三个核心方法事件回调onmessage、onclose、onerror可选能力标记supportsProtocolVersionDiscovery是否支持server/discover探测与supportsMcpToolParameterHeaders是否支持将工具的x-mcp-header参数镜像到请求头HTTP 传输已启用该项可选protocolVersion/setProtocolVersion()用于版本协商。createMCPClient会自动识别自定义传输只要对象同时具备start/send/close方法就按MCPTransport处理否则按内置配置创建见 packages/mcp/src/tool/mcp-transport.ts。例如使用官方 MCP SDK 的StdioClientTransport、StreamableHTTPClientTransport等实例也可直接传入仓库示例 examples/mcp/src/http/client.ts 与 examples/mcp/src/stdio/client.ts 均有演示。9.2 OAuth 认证对需要 OAuth 的 MCP 服务器可通过authProvider配置 OAuth 客户端提供者OAuthClientProvider。认证逻辑集中在 packages/mcp/src/tool/oauth.tsHTTP 传输在收到401及WWW-Authenticate头时会自动驱动授权流程extractWWWAuthenticateParams、auth等失败抛出UnauthorizedError。参考示例examples/mcp/src/mcp-with-auth/client.ts。9.3 工具重试策略maxRetries控制tools/call的瞬时失败重试。默认关闭0开启后仅对可重试的瞬时错误生效HTTP 状态码408、409、429及 500或错误码命中ConnectionRefused、ECONNRESET、ECONNREFUSED、ETIMEDOUT、EPIPE等见 packages/mcp/src/tool/mcp-client.ts。JSON-RPC 应用层错误如 invalid params不会重试。重试采用指数退避策略。9.4 服务器指令与输出 Schemaclient.instructions携带服务器握手时返回的使用说明可将其注入系统提示词帮助模型正确使用服务器示例见 examples/mcp/src/server-instructions/client.tstools({ schemas })可显式覆盖工具入参/出参 SchemazodoutputSchema提供时客户端会校验并提取服务器的structuredContent缺失时回退解析 text 内容见 packages/mcp/src/tool/mcp-client.ts。十、仓库中的验证与更多示例仓库提供了大量可直接运行的一手示例与测试可作为学习与验证依据示例集合examples/mcp目录包含 http、sse、stdio、http-2026现代协议、server-info、server-instructions、output-schema、provider-metadata、mcp-resources、mcp-prompts、elicitation、image-content、tool-annotations、tool-meta、shopify-mcp、mcp-with-auth 等 16 个客户端示例单元测试客户端核心逻辑见 packages/mcp/src/tool/mcp-client.test.tsstdio 传输见 packages/mcp/src/tool/mcp-stdio/mcp-stdio-transport.test.ts另含 JSON-RPC 消息解析、HTTP 头、OAuth、MCP App 指纹等专项测试包配置构建、类型检查与测试脚本见 packages/mcp/package.jsonpnpm build、pnpm test:node、pnpm test:edge等仓库内通过 pnpm workspace 统一管理依赖。总结ai-sdk/mcp是 AI SDK 与 MCP 生态之间的桥梁createMCPClient()一条命令即可建立连接tools()将服务器工具无缝转换为 AI SDK 工具配合generateText/streamText即可让模型自主使用任意 MCP 服务器的能力。生产部署优先选择 HTTP 传输并善用会话持久化接入本地工具链则使用 stdio 传输遇到特殊协议可借助自定义MCPTransport与协议版本协商机制灵活适配。结合本仓库examples/mcp的完整示例与各传输层的单元测试你可以快速落地一个生产可用的 MCP 工具调用链路。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考