ai-sdk/mcp 包演进全解析AI SDK 中 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-sdk/mcp包的完整变更记录packages/mcp/CHANGELOG.md为主线结合该包源码packages/mcp/src与使用文档packages/mcp/README.md系统梳理 AI SDK 官方 MCP 客户端从独立成包、稳定发布到 2.0 大版本重构的完整演进路径。读完你将掌握ai-sdk/mcp支持哪些传输方式与协议版本、OAuth 认证与 MCP Apps 如何工作、工具转换与结构化输出的实现机制、以及官方在原型链污染、OAuth 凭据泄露等安全问题上做了哪些加固——这些结论均可在仓库源码与测试文件中逐条验证。从ai包拆分ai-sdk/mcp的诞生1.0.0MCP 客户端最初作为实验性 API 内嵌在ai主包中使用方式如下import { experimental_createMCPClient } from ai; import { Experimental_StdioMCPTransport } from ai/mcp-stdio;在 1.0.0 里程碑中变更记录eca63f3官方将 MCP 客户端重构为独立的ai-sdk/mcp包并同时引入 OAuth 支持。新的导入路径为import { experimental_createMCPClient } from ai-sdk/mcp; import { Experimental_StdioMCPTransport } from ai-sdk/mcp/mcp-stdio;这一拆分的意义在于MCP 客户端不再依赖ai主包的运行时可以独立发布与升级ai-sdk/mcp的依赖仅包含ai-sdk/provider、ai-sdk/provider-utils、cross-spawn与pkce-challenge见 packages/mcp/package.json其中pkce-challenge正是为 OAuth PKCE 流程准备的。1.0.0 版本同时完成了一系列能力补全这些能力在后续版本中持续演化MCPClient 转正稳定90ede04客户端 API 从实验性转为稳定接口服务器 Prompts 支持1cff766可列举并调用 MCP 服务器暴露的 prompt 模板Resources 支持5939b92可列举资源、读取资源与资源模板客户端 Elicitation 支持f702df2服务器可向客户端发起信息补全请求如要求用户提供凭据可自定义客户端版本ba2ca2d与暴露_meta字段17c04d4结构化输出基础后续 1.0.5 的9cc0f88支持structuredContent/outputSchema的类型化工具输出工具结果图片返回1.0.16 的8d022fd与服务器标题捕获1.0.11 的d80fc3b。值得注意的是旧入口experimental_createMCPClient至今仍保留但已在源码中标记为deprecated建议使用createMCPClient见 packages/mcp/src/index.ts。2.0.0 大版本ESM-only、Node 22 与 v7 预发布2.0.0 是配合 AI SDK v7 预发布的一次破坏性大版本8359612包含三项 Major Changes默认拒绝 HTTP 重定向23fa161MCP 传输层默认设置redirect: error防止意外跟随重定向导致请求被转发到非预期端点全面 ESM-onlyef992f8所有包移除 CommonJS 导出type: modulerequire()使用者必须迁移到 ESMimport语法启动 v7 预发布8359612。同时最低 Node.js 版本提升到 227fc6bd6官方支持的版本为 22、24、26。这一要求同样体现在 packages/mcp/package.json 的engines字段中。从源码看createMCPClient的默认客户端名为ai-sdk-mcp-client、版本号为1.0.0默认工具调用重试次数为 0见 packages/mcp/src/tool/mcp-client.ts。2.0.0 的 Patch 列表还透露出一个重要的架构调整MCPClientError现在会携带结构化的 HTTP 上下文f7bc0b4// MCPClientError 新增可选字段statusCode、url、responseBody // 当错误来源于 streamable HTTP 传输时填充 // 对 stdio 传输错误、网络错误与 abort 场景保持 undefined。这允许下游消费者例如需要按 MCP 规范决定是否从 streamable HTTP 回退到传统 SSE 的 Agent 框架直接根据响应状态码分支而无需解析错误消息字符串。三种传输方式与 HTTP 会话管理ai-sdk/mcp的传输层抽象为MCPTransport接口packages/mcp/src/tool/mcp-transport.ts统一提供start()、send()、close()以及onclose/onerror/onmessage事件。内置三种实现// HTTP 传输推荐用于生产 const mcpClient await createMCPClient({ transport: { type: http, url: https://your-server.com/mcp, headers: { Authorization: Bearer ${process.env.MCP_API_KEY} }, }, }); // SSE 传输兼容使用 Server-Sent Events 的服务器 const mcpClient await createMCPClient({ transport: { type: sse, url: https://your-server.com/sse }, }); // stdio 传输本地服务器需从子路径导入 import { Experimental_StdioMCPTransport } from ai-sdk/mcp/mcp-stdio; const mcpClient await createMCPClient({ transport: new Experimental_StdioMCPTransport({ command: node, args: [server.js], }), });完整示例见 packages/mcp/README.md。createMcpTransport工厂根据type分发到HttpMCPTransport或SseMCPTransportpackages/mcp/src/tool/mcp-transport.ts。MCPTransportConfig中值得关注的配置项packages/mcp/src/tool/mcp-transport.ts配置项说明默认值redirectHTTP 重定向策略follow跟随 /error拒绝errorinitialSessionId恢复 Streamable HTTP 会话时携带的初始 session id无initialProtocolVersioninitialize 协商前发送的协议版本最新协议版本terminateSessionOnCloseclose()时是否发送 DELETE 终止会话trueonSessionIdChange服务器创建/变更/清除 session id 时回调无onSessionExpired会话 id 返回 404 时回调自动清除后上报无fetch自定义 fetch 实现适用于请求局部 fetch 的运行时globalThis.fetchauthProviderMCP 服务器的 OAuth 客户端提供者无HTTP 会话的持久化与重连2.0.1241a8c5为 HTTP 传输补齐了会话钩子支持缓存的 initialize 元数据、detach-on-close关闭时不发送 DELETE便于后续重连。官方 README 展示了完整的三段式会话复用模式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 { /* 清除本地缓存 */ }, }, initialInitializeResult: savedSession?.initializeResult, // 复用旧会话跳过 initialize });注意会话持久化仅适用于传统 MCP 协议版本2026-07-28 协议是无状态的见 packages/mcp/README.md。此外MCPClientConfig.initialInitializeResult允许客户端直接复用上次的 initialize 结果而不重新握手packages/mcp/src/tool/mcp-client.ts这一机制配合上面的会话钩子即可实现跨进程的零握手恢复。stdio 传输的跨平台细节2.0.36b352a6a修复了 Windows 上npx等命令 shim 的启动问题。stdlib 传输使用cross-spawn跨平台创建子进程相关实现与测试见 packages/mcp/src/tool/mcp-stdio/mcp-stdio-transport.ts 与 create-child-process.ts。协议版本协商从 2025-11-25 到 2026-07-28协议版本支持范围定义在 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 [ /* 包含上述两者及中间版本 */ ];客户端同时支持两条协议路线传统协议2025-11-25 及更早通过initialize握手协商支持会话 id 与缓存的 initialize 结果2026 协议2026-07-28无状态协议通过server/discover进行无状态协议发现不使用 session id。版本演进的关键提交包括2.0.330c60a40、e6a9927加入 2026 streamable HTTP 支持与 2026 协议发现基础9ecd8ae2.0.0-beta.2将 2025-11-25 加入支持列表3e0b82f支持官方 SDK 的协议版本协商2655da8在传输请求头中使用协商后的协议版本。内置 stdio 传输会用server/discover探测连接旧服务器时回退到传统握手。自定义传输可通过设置supportsProtocolVersionDiscovery: true加入同一套协商机制现代请求会在_meta中携带协议版本、客户端能力与客户端信息packages/mcp/README.md。MCPClientConfig.protocolVersionDiscovery默认为true当旧服务器要求initialize必须是第一个请求时可显式关闭packages/mcp/src/tool/mcp-client.ts。面向远程服务器的 OAuth 认证体系MCP 客户端的 OAuth 支持是 1.0.0 引入的核心能力之一实现集中在 packages/mcp/src/tool/oauth.ts。从源码的函数清单可以还原完整的授权流程阶段函数职责发现discoverOAuthProtectedResourceMetadata、discoverAuthorizationServerMetadata从WWW-Authenticate挑战或受保护资源元数据发现授权服务器注册registerClient动态客户端注册授权startAuthorization启动 PKCE 授权码流程换发exchangeAuthorization用授权码换取令牌刷新refreshAuthorization令牌刷新入口auth整合以上流程的顶层封装围绕 OAuth 的加固贯穿整个 2.0 生命周期这部分与安全小节共同体现了凭据零泄露的设计原则scope 选择1011e332.0.32从WWW-Authenticate挑战或受保护资源元数据中选择授权 scope2.0.38bf591f0进一步将 scope 选择应用到动态客户端注册issuer 校验024a6b4发现阶段校验 OAuth 元数据的 issuer凭据防泄露f0c6770防止 rediscovery 过程中的 OAuth 凭据外泄私密端点防护fe693422.0.38发送凭据前拒绝私密 OAuth 端点尾部斜杠处理1e89d62、809e922剥离资源参数的尾部斜杠同时接受仅有 origin 的 OAuth issuer 上的尾部斜杠客户端注册加固1f292302.0.33按最新协议加固注册流程78e0023确保 token 交换与刷新时正确 awaitaddClientAuthentication6f1577e为 refreshAuth 传递 JSON 头。MCP Apps把 HTML 资源安全地渲染进宿主2.0.0 引入的 MCP Apps 支持611f621让 MCP 服务器可以暴露text/html;profilemcp-app类型的 HTML 资源由宿主在受控的 iframe 桥接中渲染。相关实现与类型见 packages/mcp/src/tool/mcp-apps.tsexport const MCP_APP_EXTENSION_NAME io.modelcontextprotocol/ui; export const MCP_APP_MIME_TYPE text/html;profilemcp-app; // 宿主支持 MCP Apps 时传入 createMCPClient 的客户端能力 export const mcpAppClientCapabilities { extensions: { [MCP_APP_EXTENSION_NAME]: { mimeTypes: [MCP_APP_MIME_TYPE] }, }, };2.0.1448e7e78对 MCP Apps 做了系统性安全加固是理解该功能边界的最好注脚运行时校验_meta.ui丢弃畸形或非字符串字段iframe 权限默认拒绝通过新的sandbox.allowedPermissions白名单控制postMessage 源校验推导具体的postMessage目标 origin并校验入站消息来源入站桥接参数校验resources/read仅限ui://资源ui/open-link只允许https/http/mailto资源指纹新增fingerprintMCPAppResource与detectMCPAppResourceDriftpackages/mcp/src/tool/mcp-app-fingerprint.ts用于固定并比较应用资源。工具转换、结构化输出与分页获取客户端核心职责是把 MCP 工具定义转换为 AI SDK 工具。转换逻辑位于DefaultMCPClient.tools()packages/mcp/src/tool/mcp-client.ts工具参数可从服务器的 JSON Schema 自动推断。转换后的输出通过mcpToModelOutput归一化为 AI SDK 的text/file内容类型——MCP 的image内容被映射为file类型ff5eba1将image-*输出类型并入file-*类型。工具结果处理的几个关键演进structuredContent 兜底3da84fd2.0.45当 MCP 工具结果返回structuredContent但没有content字段时将序列化的结构化结果作为文本加入输出避免结果丢失outputSchema 校验旁路e3ea484工具返回isError时跳过outputSchema校验服务器工具注解透出33ba8fd2.0.45将服务器提供的工具注解McpToolAnnotations暴露在工具元数据中服务器名称传播08d2129动态工具部件中携带服务器名称多服务器场景可追溯来源分页工具定义11754342.0.37创建工具集时拉取全部分页的工具定义而非只取第一页服务器指令与信息透出93afb28暴露服务器instructions可注入系统提示词a98bf66暴露serverInfo对应MCPClient.serverInfo/instructions只读属性packages/mcp/src/tool/mcp-client.tsMcpProviderMetadataf634bac新增 MCP 提供者元数据类型配合69254e0的toolMetadata为工具携带附加元数据。安全加固专题原型链污染、白名单与错误处理2.0.0 的 Patch 列表集中体现了安全工程细节这些修复都值得在接入时注意1. 工具白名单的hasOwn修复b44b051当使用client.tools({ schemas })只暴露 MCP 服务器工具的显式子集时旧实现用in操作符做白名单检查会命中Object.prototype的继承属性——服务器若声明名为constructor、toString、__proto__的工具即使开发者从未在schemas中定义也会通过检查并被暴露给模型执行。修复后改用Object.hasOwn只有显式定义的工具才会返回。相关测试见 packages/mcp/src/tool/mcp-client.test.ts。2. 原型污染防护9b0bc8a所有 JSON 解析统一改用secureJsonParse防止恶意服务器通过构造__proto__键污染客户端对象原型。3. OAuth 元数据与凭据加固前文已列issuer 校验024a6b4、rediscovery 凭据防泄露f0c6770、私密端点拒绝fe69342、state参数校验b9b3899、validateJSONRPCMessage暴露3c30eb42.0.6。4. 错误与连接治理MCPClientError结构化 HTTP 上下文f7bc0b4abort 信号触发时拒绝在途请求并清理响应处理器3e6e9552.0.8防止 streamable HTTP 后台 SSE 断开成为未处理的 promise rejectioneebd14b2.0.8SSE 传输锁住收到的第一个 endpoint2a150f8、容忍无显式 event 字段的 SSE 消息b29e087、POST 响应失败时拒绝 SSE 请求76fb75d2.0.35resource_link内容类型加入CallToolResultSchema与PromptMessageSchemab79094c修复 zod ≥ 4.4.x 下的硬拒绝问题按 JSON-RPC 规范以空结果响应 pingdcefad3关闭 issue #6282HTTP 传输上的认证刷新去重6c17a9f。2.0.x 持续演进重试、超时与协议现代化2.0 正式发布后的增量版本继续补齐生产级能力工具调用重试8c616f02.0.5MCPClientConfig.maxRetries选项默认 0禁用。从源码看可重试条件包括 HTTP 408/409/429 与 ≥500 状态码以及ConnectionRefused、ECONNRESET、ETIMEDOUT、EPIPE等网络错误码JSON-RPC 应用层错误如参数非法不重试packages/mcp/src/tool/mcp-client.ts请求 deadline 与初始化边界97f05652.0.20通过initializationOptionstimeout / maxTotalTimeout / abortSignal约束或取消传输启动与 initialize 请求packages/mcp/src/tool/mcp-client.ts2026 协议基础2.0.33streamable HTTP 2026 支持与协议发现基础工具结果内容类型对齐5463d0d工具输出的文件部件类型与顶层消息文件部件类型对齐服务器端 completions68a739a2.0.3允许 MCP 客户端使用服务器补全对应MCPClient.complete()方法packages/mcp/src/tool/mcp-client.ts。依赖基座与 provider 系列的同步演进ai-sdk/mcp始终与ai-sdk/provider、ai-sdk/provider-utils保持版本同步CHANGELOG 中大量Updated dependencies条目当前 2.0.48 对应ai-sdk/provider4.0.13与ai-sdk/provider-utils5.0.39。这反映了一个重要事实MCP 客户端是 AI SDK 工具系统tool/dynamicTool/jsonSchema等来自 provider-utils的深度用户其类型安全依赖ai-sdk/provider的JSONValue/JSONSchema7等基础类型而zod作为 peerDependency 支持^3.25.76 || ^4.1.8packages/mcp/package.json。接入时若遇到类型或行为差异可优先检查这两层依赖是否与本包版本匹配。小结一份可追溯的能力清单从packages/mcp/CHANGELOG.md可以还原出ai-sdk/mcp的完整能力边界稳定的createMCPClientAPI、HTTP/SSE/stdio 三种传输、Streamable HTTP 会话复用、OAuth PKCE 全流程、2025-11-25 与 2026-07-28 双协议协商、MCP Apps 渲染桥接、结构化工具输出与注解透出以及贯穿始终的安全加固。若要验证任一能力的行为细节源码与测试都是最直接的依据客户端与工具转换见 packages/mcp/src/tool/mcp-client.ts传输配置见 packages/mcp/src/tool/mcp-transport.tsOAuth 见 packages/mcp/src/tool/oauth.ts协议版本常量见 packages/mcp/src/tool/types.ts对应的测试覆盖在 packages/mcp/src/tool 目录的*.test.ts文件中。【免费下载链接】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 客户端的核心能力、安全加固与版本脉络
ai-sdk/mcp 包演进全解析AI SDK 中 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-sdk/mcp包的完整变更记录packages/mcp/CHANGELOG.md为主线结合该包源码packages/mcp/src与使用文档packages/mcp/README.md系统梳理 AI SDK 官方 MCP 客户端从独立成包、稳定发布到 2.0 大版本重构的完整演进路径。读完你将掌握ai-sdk/mcp支持哪些传输方式与协议版本、OAuth 认证与 MCP Apps 如何工作、工具转换与结构化输出的实现机制、以及官方在原型链污染、OAuth 凭据泄露等安全问题上做了哪些加固——这些结论均可在仓库源码与测试文件中逐条验证。从ai包拆分ai-sdk/mcp的诞生1.0.0MCP 客户端最初作为实验性 API 内嵌在ai主包中使用方式如下import { experimental_createMCPClient } from ai; import { Experimental_StdioMCPTransport } from ai/mcp-stdio;在 1.0.0 里程碑中变更记录eca63f3官方将 MCP 客户端重构为独立的ai-sdk/mcp包并同时引入 OAuth 支持。新的导入路径为import { experimental_createMCPClient } from ai-sdk/mcp; import { Experimental_StdioMCPTransport } from ai-sdk/mcp/mcp-stdio;这一拆分的意义在于MCP 客户端不再依赖ai主包的运行时可以独立发布与升级ai-sdk/mcp的依赖仅包含ai-sdk/provider、ai-sdk/provider-utils、cross-spawn与pkce-challenge见 packages/mcp/package.json其中pkce-challenge正是为 OAuth PKCE 流程准备的。1.0.0 版本同时完成了一系列能力补全这些能力在后续版本中持续演化MCPClient 转正稳定90ede04客户端 API 从实验性转为稳定接口服务器 Prompts 支持1cff766可列举并调用 MCP 服务器暴露的 prompt 模板Resources 支持5939b92可列举资源、读取资源与资源模板客户端 Elicitation 支持f702df2服务器可向客户端发起信息补全请求如要求用户提供凭据可自定义客户端版本ba2ca2d与暴露_meta字段17c04d4结构化输出基础后续 1.0.5 的9cc0f88支持structuredContent/outputSchema的类型化工具输出工具结果图片返回1.0.16 的8d022fd与服务器标题捕获1.0.11 的d80fc3b。值得注意的是旧入口experimental_createMCPClient至今仍保留但已在源码中标记为deprecated建议使用createMCPClient见 packages/mcp/src/index.ts。2.0.0 大版本ESM-only、Node 22 与 v7 预发布2.0.0 是配合 AI SDK v7 预发布的一次破坏性大版本8359612包含三项 Major Changes默认拒绝 HTTP 重定向23fa161MCP 传输层默认设置redirect: error防止意外跟随重定向导致请求被转发到非预期端点全面 ESM-onlyef992f8所有包移除 CommonJS 导出type: modulerequire()使用者必须迁移到 ESMimport语法启动 v7 预发布8359612。同时最低 Node.js 版本提升到 227fc6bd6官方支持的版本为 22、24、26。这一要求同样体现在 packages/mcp/package.json 的engines字段中。从源码看createMCPClient的默认客户端名为ai-sdk-mcp-client、版本号为1.0.0默认工具调用重试次数为 0见 packages/mcp/src/tool/mcp-client.ts。2.0.0 的 Patch 列表还透露出一个重要的架构调整MCPClientError现在会携带结构化的 HTTP 上下文f7bc0b4// MCPClientError 新增可选字段statusCode、url、responseBody // 当错误来源于 streamable HTTP 传输时填充 // 对 stdio 传输错误、网络错误与 abort 场景保持 undefined。这允许下游消费者例如需要按 MCP 规范决定是否从 streamable HTTP 回退到传统 SSE 的 Agent 框架直接根据响应状态码分支而无需解析错误消息字符串。三种传输方式与 HTTP 会话管理ai-sdk/mcp的传输层抽象为MCPTransport接口packages/mcp/src/tool/mcp-transport.ts统一提供start()、send()、close()以及onclose/onerror/onmessage事件。内置三种实现// HTTP 传输推荐用于生产 const mcpClient await createMCPClient({ transport: { type: http, url: https://your-server.com/mcp, headers: { Authorization: Bearer ${process.env.MCP_API_KEY} }, }, }); // SSE 传输兼容使用 Server-Sent Events 的服务器 const mcpClient await createMCPClient({ transport: { type: sse, url: https://your-server.com/sse }, }); // stdio 传输本地服务器需从子路径导入 import { Experimental_StdioMCPTransport } from ai-sdk/mcp/mcp-stdio; const mcpClient await createMCPClient({ transport: new Experimental_StdioMCPTransport({ command: node, args: [server.js], }), });完整示例见 packages/mcp/README.md。createMcpTransport工厂根据type分发到HttpMCPTransport或SseMCPTransportpackages/mcp/src/tool/mcp-transport.ts。MCPTransportConfig中值得关注的配置项packages/mcp/src/tool/mcp-transport.ts配置项说明默认值redirectHTTP 重定向策略follow跟随 /error拒绝errorinitialSessionId恢复 Streamable HTTP 会话时携带的初始 session id无initialProtocolVersioninitialize 协商前发送的协议版本最新协议版本terminateSessionOnCloseclose()时是否发送 DELETE 终止会话trueonSessionIdChange服务器创建/变更/清除 session id 时回调无onSessionExpired会话 id 返回 404 时回调自动清除后上报无fetch自定义 fetch 实现适用于请求局部 fetch 的运行时globalThis.fetchauthProviderMCP 服务器的 OAuth 客户端提供者无HTTP 会话的持久化与重连2.0.1241a8c5为 HTTP 传输补齐了会话钩子支持缓存的 initialize 元数据、detach-on-close关闭时不发送 DELETE便于后续重连。官方 README 展示了完整的三段式会话复用模式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 { /* 清除本地缓存 */ }, }, initialInitializeResult: savedSession?.initializeResult, // 复用旧会话跳过 initialize });注意会话持久化仅适用于传统 MCP 协议版本2026-07-28 协议是无状态的见 packages/mcp/README.md。此外MCPClientConfig.initialInitializeResult允许客户端直接复用上次的 initialize 结果而不重新握手packages/mcp/src/tool/mcp-client.ts这一机制配合上面的会话钩子即可实现跨进程的零握手恢复。stdio 传输的跨平台细节2.0.36b352a6a修复了 Windows 上npx等命令 shim 的启动问题。stdlib 传输使用cross-spawn跨平台创建子进程相关实现与测试见 packages/mcp/src/tool/mcp-stdio/mcp-stdio-transport.ts 与 create-child-process.ts。协议版本协商从 2025-11-25 到 2026-07-28协议版本支持范围定义在 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 [ /* 包含上述两者及中间版本 */ ];客户端同时支持两条协议路线传统协议2025-11-25 及更早通过initialize握手协商支持会话 id 与缓存的 initialize 结果2026 协议2026-07-28无状态协议通过server/discover进行无状态协议发现不使用 session id。版本演进的关键提交包括2.0.330c60a40、e6a9927加入 2026 streamable HTTP 支持与 2026 协议发现基础9ecd8ae2.0.0-beta.2将 2025-11-25 加入支持列表3e0b82f支持官方 SDK 的协议版本协商2655da8在传输请求头中使用协商后的协议版本。内置 stdio 传输会用server/discover探测连接旧服务器时回退到传统握手。自定义传输可通过设置supportsProtocolVersionDiscovery: true加入同一套协商机制现代请求会在_meta中携带协议版本、客户端能力与客户端信息packages/mcp/README.md。MCPClientConfig.protocolVersionDiscovery默认为true当旧服务器要求initialize必须是第一个请求时可显式关闭packages/mcp/src/tool/mcp-client.ts。面向远程服务器的 OAuth 认证体系MCP 客户端的 OAuth 支持是 1.0.0 引入的核心能力之一实现集中在 packages/mcp/src/tool/oauth.ts。从源码的函数清单可以还原完整的授权流程阶段函数职责发现discoverOAuthProtectedResourceMetadata、discoverAuthorizationServerMetadata从WWW-Authenticate挑战或受保护资源元数据发现授权服务器注册registerClient动态客户端注册授权startAuthorization启动 PKCE 授权码流程换发exchangeAuthorization用授权码换取令牌刷新refreshAuthorization令牌刷新入口auth整合以上流程的顶层封装围绕 OAuth 的加固贯穿整个 2.0 生命周期这部分与安全小节共同体现了凭据零泄露的设计原则scope 选择1011e332.0.32从WWW-Authenticate挑战或受保护资源元数据中选择授权 scope2.0.38bf591f0进一步将 scope 选择应用到动态客户端注册issuer 校验024a6b4发现阶段校验 OAuth 元数据的 issuer凭据防泄露f0c6770防止 rediscovery 过程中的 OAuth 凭据外泄私密端点防护fe693422.0.38发送凭据前拒绝私密 OAuth 端点尾部斜杠处理1e89d62、809e922剥离资源参数的尾部斜杠同时接受仅有 origin 的 OAuth issuer 上的尾部斜杠客户端注册加固1f292302.0.33按最新协议加固注册流程78e0023确保 token 交换与刷新时正确 awaitaddClientAuthentication6f1577e为 refreshAuth 传递 JSON 头。MCP Apps把 HTML 资源安全地渲染进宿主2.0.0 引入的 MCP Apps 支持611f621让 MCP 服务器可以暴露text/html;profilemcp-app类型的 HTML 资源由宿主在受控的 iframe 桥接中渲染。相关实现与类型见 packages/mcp/src/tool/mcp-apps.tsexport const MCP_APP_EXTENSION_NAME io.modelcontextprotocol/ui; export const MCP_APP_MIME_TYPE text/html;profilemcp-app; // 宿主支持 MCP Apps 时传入 createMCPClient 的客户端能力 export const mcpAppClientCapabilities { extensions: { [MCP_APP_EXTENSION_NAME]: { mimeTypes: [MCP_APP_MIME_TYPE] }, }, };2.0.1448e7e78对 MCP Apps 做了系统性安全加固是理解该功能边界的最好注脚运行时校验_meta.ui丢弃畸形或非字符串字段iframe 权限默认拒绝通过新的sandbox.allowedPermissions白名单控制postMessage 源校验推导具体的postMessage目标 origin并校验入站消息来源入站桥接参数校验resources/read仅限ui://资源ui/open-link只允许https/http/mailto资源指纹新增fingerprintMCPAppResource与detectMCPAppResourceDriftpackages/mcp/src/tool/mcp-app-fingerprint.ts用于固定并比较应用资源。工具转换、结构化输出与分页获取客户端核心职责是把 MCP 工具定义转换为 AI SDK 工具。转换逻辑位于DefaultMCPClient.tools()packages/mcp/src/tool/mcp-client.ts工具参数可从服务器的 JSON Schema 自动推断。转换后的输出通过mcpToModelOutput归一化为 AI SDK 的text/file内容类型——MCP 的image内容被映射为file类型ff5eba1将image-*输出类型并入file-*类型。工具结果处理的几个关键演进structuredContent 兜底3da84fd2.0.45当 MCP 工具结果返回structuredContent但没有content字段时将序列化的结构化结果作为文本加入输出避免结果丢失outputSchema 校验旁路e3ea484工具返回isError时跳过outputSchema校验服务器工具注解透出33ba8fd2.0.45将服务器提供的工具注解McpToolAnnotations暴露在工具元数据中服务器名称传播08d2129动态工具部件中携带服务器名称多服务器场景可追溯来源分页工具定义11754342.0.37创建工具集时拉取全部分页的工具定义而非只取第一页服务器指令与信息透出93afb28暴露服务器instructions可注入系统提示词a98bf66暴露serverInfo对应MCPClient.serverInfo/instructions只读属性packages/mcp/src/tool/mcp-client.tsMcpProviderMetadataf634bac新增 MCP 提供者元数据类型配合69254e0的toolMetadata为工具携带附加元数据。安全加固专题原型链污染、白名单与错误处理2.0.0 的 Patch 列表集中体现了安全工程细节这些修复都值得在接入时注意1. 工具白名单的hasOwn修复b44b051当使用client.tools({ schemas })只暴露 MCP 服务器工具的显式子集时旧实现用in操作符做白名单检查会命中Object.prototype的继承属性——服务器若声明名为constructor、toString、__proto__的工具即使开发者从未在schemas中定义也会通过检查并被暴露给模型执行。修复后改用Object.hasOwn只有显式定义的工具才会返回。相关测试见 packages/mcp/src/tool/mcp-client.test.ts。2. 原型污染防护9b0bc8a所有 JSON 解析统一改用secureJsonParse防止恶意服务器通过构造__proto__键污染客户端对象原型。3. OAuth 元数据与凭据加固前文已列issuer 校验024a6b4、rediscovery 凭据防泄露f0c6770、私密端点拒绝fe69342、state参数校验b9b3899、validateJSONRPCMessage暴露3c30eb42.0.6。4. 错误与连接治理MCPClientError结构化 HTTP 上下文f7bc0b4abort 信号触发时拒绝在途请求并清理响应处理器3e6e9552.0.8防止 streamable HTTP 后台 SSE 断开成为未处理的 promise rejectioneebd14b2.0.8SSE 传输锁住收到的第一个 endpoint2a150f8、容忍无显式 event 字段的 SSE 消息b29e087、POST 响应失败时拒绝 SSE 请求76fb75d2.0.35resource_link内容类型加入CallToolResultSchema与PromptMessageSchemab79094c修复 zod ≥ 4.4.x 下的硬拒绝问题按 JSON-RPC 规范以空结果响应 pingdcefad3关闭 issue #6282HTTP 传输上的认证刷新去重6c17a9f。2.0.x 持续演进重试、超时与协议现代化2.0 正式发布后的增量版本继续补齐生产级能力工具调用重试8c616f02.0.5MCPClientConfig.maxRetries选项默认 0禁用。从源码看可重试条件包括 HTTP 408/409/429 与 ≥500 状态码以及ConnectionRefused、ECONNRESET、ETIMEDOUT、EPIPE等网络错误码JSON-RPC 应用层错误如参数非法不重试packages/mcp/src/tool/mcp-client.ts请求 deadline 与初始化边界97f05652.0.20通过initializationOptionstimeout / maxTotalTimeout / abortSignal约束或取消传输启动与 initialize 请求packages/mcp/src/tool/mcp-client.ts2026 协议基础2.0.33streamable HTTP 2026 支持与协议发现基础工具结果内容类型对齐5463d0d工具输出的文件部件类型与顶层消息文件部件类型对齐服务器端 completions68a739a2.0.3允许 MCP 客户端使用服务器补全对应MCPClient.complete()方法packages/mcp/src/tool/mcp-client.ts。依赖基座与 provider 系列的同步演进ai-sdk/mcp始终与ai-sdk/provider、ai-sdk/provider-utils保持版本同步CHANGELOG 中大量Updated dependencies条目当前 2.0.48 对应ai-sdk/provider4.0.13与ai-sdk/provider-utils5.0.39。这反映了一个重要事实MCP 客户端是 AI SDK 工具系统tool/dynamicTool/jsonSchema等来自 provider-utils的深度用户其类型安全依赖ai-sdk/provider的JSONValue/JSONSchema7等基础类型而zod作为 peerDependency 支持^3.25.76 || ^4.1.8packages/mcp/package.json。接入时若遇到类型或行为差异可优先检查这两层依赖是否与本包版本匹配。小结一份可追溯的能力清单从packages/mcp/CHANGELOG.md可以还原出ai-sdk/mcp的完整能力边界稳定的createMCPClientAPI、HTTP/SSE/stdio 三种传输、Streamable HTTP 会话复用、OAuth PKCE 全流程、2025-11-25 与 2026-07-28 双协议协商、MCP Apps 渲染桥接、结构化工具输出与注解透出以及贯穿始终的安全加固。若要验证任一能力的行为细节源码与测试都是最直接的依据客户端与工具转换见 packages/mcp/src/tool/mcp-client.ts传输配置见 packages/mcp/src/tool/mcp-transport.tsOAuth 见 packages/mcp/src/tool/oauth.ts协议版本常量见 packages/mcp/src/tool/types.ts对应的测试覆盖在 packages/mcp/src/tool 目录的*.test.ts文件中。【免费下载链接】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），仅供参考