迁移至 @langchain/mcp-adapters 2.0

从 @langchain/mcp-adapters 1.x 迁移到 2.0

@langchain/mcp-adapters 2.0 在 MCP TypeScript SDK 2 客户端上重建了适配器。它会为每台服务器协商 MCP 协议时代，并用 LangGraph 中断响应现代 MCP 提取请求。本指南涵盖影响 1.x 代码的变更，功能文档请参考 Model Context Protocol (MCP)。

不兼容变更

工具名称默认以服务器名称前缀。 MCPAdapter（包括已弃用的 MultiServerMCPClient），例如 {server}_{tool}（例如 weather_get_forecast），即使使用单一服务器，除非设置 prefixToolNameWithServerName；1.x 默认为 false。设置 prefixToolNameWithServerName: false 以保持 1.x 名称。loadMcpTools 仍默认为 false。更新代码、提示词和保存示例中引用的工具名称。更新 interruptOn 审批规则以匹配前缀名称；不再匹配 delete_repo 的规则适用于 github_delete_repo。适配器不验证服务器名称，较长名称可能超出模型提供者的工具名限制，请参考多服务器。
重复工具名称会抛出错误。 使用 prefixToolNameWithServerName: false、listTools() 和 getTools() 时，当两台服务器暴露相同工具名，或单个服务器重复列出名称时，会抛出 MCPClientError。1.x 会返回所有工具。保持前缀，或从 listToolsets() 中按服务器选择工具。
提取请求默认暂停运行。 当现代服务器在工具调用中请求输入时，适配器会抛出 LangGraph @[interrupt] 并暂停运行，需通过 createMCPElicitationResume 恢复。仅在工具提取时需要检查点。为服务器设置 elicitation: false 以保持 1.x 行为。请参考提取。
工具内容始终为标准内容块。 1.x 默认 useStandardContentBlocks 为 false。2.0 移除该选项并拒绝，强制使用标准块，因此图像使用 data 和 mimeType 而非 image_url 数据 URL，音频使用 mimeType 而非 mime_type。请参考工具结果。
配置严格校验。 构造适配器时，未知键和移除选项会抛出错误。请参考移除选项。
服务器报告的工具错误返回消息。 结果包含 isError 时会返回 ToolMessage 并包含 status: "error"（针对智能体工具调用）。直接使用普通参数调用仍会抛出。请参考工具结果。
模型不再在单个文本块旁显示 structuredContent 或 _meta。 1.x 将它们复制到文本块并序列化为内容；2.0 仅发送文本。从 mcp_structured_content 和 mcp_meta 条目中读取这些信息（1.x 同样放置于此）。请参考工具结果。

安装

升级适配器及其依赖项：

npm install @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

pnpm add @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

yarn add @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

bun add @langchain/mcp-adapters@^2.0.0 @langchain/core @langchain/langgraph

Peer dependencies: 适配器需要 @langchain/core 1.2.6 或更高版本（原为1.0.0），且 @langchain/langgraph 需要达到1.4.13或更高版本（原为1.4.10）。
MCP SDK: 适配器包含MCP SDK 2客户端。若您的代码为 loadMcpTools 创建SDK客户端，请将 @modelcontextprotocol/sdk 导入替换为 @modelcontextprotocol/client。从 @modelcontextprotocol/client/stdio 导入stdio传输。若代码直接导入SDK（包括完成OAuth重定向），请将其作为直接依赖。
Zod 4: 适配器通过内置的Zod 4依赖验证配置，因此配置错误会以Zod 4错误形式呈现。
调试日志: DEBUG=@langchain/mcp-adapters:* 不再输出日志。改用 onConnectionError 和服务器通知回调。

重命名API

Before:

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
  mcpServers: {
    math: { command: "node", args: ["./math-server.js"] },
  },
});
const tools = await client.getTools();

After:

import { MCPAdapter } from "@langchain/mcp-adapters";

const adapter = new MCPAdapter({
  servers: {
    math: { command: "node", args: ["./math-server.js"] },
  },
});
const tools = await adapter.listTools();

1.x API	推荐使用的2.0 API
`MultiServerMCPClient`	`MCPAdapter`
`mcpServers` 或扁平化服务器映射	`servers`
`getTools(...)`	`listTools(...)`，可执行工具的扁平列表
`initializeConnections()`	`listToolsets()`，按服务器分组工具
`ClientConfig` 类型	`MCPAdapterConfig`

该表中的旧API仍然可用但已弃用，未来可能被移除。其他API变更：

从adapter.config.servers读取配置而非adapter.config.mcpServers。这是快照；修改它不会重新配置适配器。
SSEConnection仅支持遗留SSE。使用StreamableHTTPConnection进行HTTP通信，或Connection支持任意传输协议。
ToolException和MCPClientError已导出。通过ToolException.isInstance(error)和MCPClientError.isInstance(error)识别它们（基于品牌而非错误码name）。
setLoggingLevel()仅限遗留版本。若目标服务器协商了现代协议，它会抛出异常且不设置等级。应在每个现代服务器上设置logLevel（参见协议时代）。现代服务器也拒绝resources/subscribe，因此应在服务器的resourceSubscriptions选项中列出要监控的资源URI，并在onResourcesUpdated中处理更新，而非在客户端调用subscribeResource()。

getClient()现在从@modelcontextprotocol/client返回SDK 2 Client。loadMcpTools(serverName, client)可将工具从自建的SDK客户端转换。SDK Client默认协商遗留协议，若工具应通过中断触发，需用versionNegotiation: { mode: "auto" }创建它。要将其连接到InMemoryTransport的进程内服务器，需用serveStdio(factory, { transport: serverSide })托管该服务器；server.connect()仅支持遗留协议。

已移除的选项

设置任何以下选项的配置现在会失败验证。loadMcpTools验证选项的方式与原文相同：

选项	替换方案
`useStandardContentBlocks`	无。工具内容始终为标准LangChain内容块。删除该选项。
`onRootsListChanged`	无。删除该选项。
`onCancelled`	无。删除该选项。
Stdio `encoding`	无。删除该选项。
顶层通知回调	在每个服务器上设置（参见将回调移动到服务器）。

配置

将回调移动到服务器

通知和进度回调从顶层移动到应接收它们的服务器。这适用于onMessage、onProgress、onInitialized、onPromptsListChanged、onResourcesListChanged、onResourcesUpdated和onToolsListChanged。前：

const client = new MultiServerMCPClient({
  mcpServers: {
    everything: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-everything"],
    },
  },
  onProgress: (progress, source) => {
    console.log(source.type, progress.progress, progress.total);
  },
});

后：

const adapter = new MCPAdapter({
  servers: {
    everything: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-everything"],
      onProgress: (progress, source) => {
        console.log(source.type, progress.progress, progress.total);
      },
    },
  },
});

工具钩子（beforeToolCall、afterToolCall）和onConnectionError仍保留在顶层适配器选项。在1.x版本中，由onProgress回调抛出的错误或拒绝的承诺现在会被忽略。

设置协议模式

（注：此处原文未提供具体内容，根据上下文推测应为协议模式设置说明）每个服务器现在接受 mode（默认值）的 "auto"、"modern" 或 "legacy" 并独立协商。各模式的具体行为请参考协议时代。省略 mode 可自动协商。设置 mode: "modern" 以强制使用现代协议，或设置 mode: "legacy" 以跳过已知遗留服务器的探测。这些选项需要 mode: "legacy" 在设置它们的服务器上：

onInitialized
automaticSSEFallback
HTTP/SSE reconnect
onElicitation

1.x 版本设置 automaticSSEFallback 或 reconnect 时，在未添加 mode: "legacy" 的情况下会触发验证失败：

const adapter = new MCPAdapter({
  servers: {
    legacy: {
      url: "https://legacy.example.com/sse",
      transport: "sse",
      mode: "legacy", 
      reconnect: { enabled: true, maxAttempts: 3, delayMs: 1000 },
    },
  },
});

HTTP 连接在 "auto" 或 "modern" 模式下不再恢复被丢弃的响应流。如需依赖流恢复，请使用 mode: "legacy"。 SSE 作为遗留传输协议，会拒绝 mode: "modern"、elicitation 和 logLevel。在 "auto" 模式下，HTTP 到 SSE 的自动回退仅支持 HTTP 404 和 405 状态码。

期待更严格的验证

配置：Zod 4 验证会拒绝未知适配器和服务选项、与服务器模式或传输不匹配的选项、冲突的传输设置、空服务器映射，以及同时设置 servers 和 mcpServers。重启和重连 maxAttempts 必须为非负整数，而 delayMs 不能为负数。
钩子：在 beforeToolCall 和 afterToolCall 中，state 的类型已明确为 unknown，使用前需窄化类型。参数覆盖必须为对象。合并后的参数会根据工具的输入 schema 进行验证，因此添加 schema 不允许的属性的覆盖会以 ToolException 错误在发送到服务器前终止调用。

认证

两种提供商形态：authProvider 支持 AuthProvider（{ token, onUnauthorized? }）和 OAuthClientProvider。1.x 版本仅支持 OAuth 提供商。
头部优先级：一旦提供商拥有令牌，它会优先于配置的 Authorization 头部。在此之前，会发送配置的头部。
OAuth 回调：使用 SDK 的 transport.finishAuth(params) 完成重定向，需使用存储相同的提供商。适配器没有 finishAuth。
错误处理：遍历认证失败的 cause 链查找 UnauthorizedError（适配器现在导出该值），或 HTTP 401 错误。发现过程将其封装在 MCPClientError 中（遗留模式回退到 SSE 时封装两次）；工具调用将其封装在 ToolException 中。
重试：认证失败会在下一次调用时自动重试，即使使用 onConnectionError: "ignore"。
覆盖：工具目录根据不同头部和提供商对象独立维护。当提供商对象绑定的账户变更时需重建适配器。方法级的 authProvider 会替换配置值，方法级的 headers 会添加到每个服务器的配置头部（配置头部同名时优先）。两者均适用于所有 HTTP/SSE 服务器，即使仅从单一服务器选择工具。

完整指南请参考认证。

引导

2.0 版本新增引导功能：1.x 不支持引导。当服务器协商现代协议时，适配器默认将每个请求输入轮次提升为单个 LangGraph @[interrupt]，其 requests 包含所有问题。请求输入的工具会暂停运行。

检查点：仅在工具请求输入时需要检查点。否则直接调用仍有效。
恢复：回答 requests 中的所有键，然后将 createMCPElicitationResume(interrupt, responses) 作为 LangGraph Command 的 resume 值。
回放：恢复运行会从头重新执行工具，包括 beforeToolCall。需确保重复执行不会导致副作用重复。
禁用：在 elicitation: false 单个现代服务器，或在 loadMcpTools 选项中，可保持 1.x 行为。
遗留服务器：为 mode: "legacy" 的服务器设置 onElicitation 处理器。此处理器为 2.0 新增。

完整中断载荷、动作响应和示例请参考引导。

抽样与根节点

仅通过中断响应引导。请求抽样或根节点会以 ToolException 错误终止工具调用，即使它们与引导请求同时到达。

工具结果

标准内容块: 工具内容始终使用标准 LangChain 内容块。图像和音频会暴露 data 和 mimeType。默认情况下，1.x 版本使用数据 URL 生成 image_url 块，音频块使用 mime_type。
附件: 路由到附件的块保留 MCP 格式，包括在 afterToolCall 中接收完整的附件列表（包含 mcp_structured_content、mcp_meta 和 mcp_content 条目）。当转换会丢失信息时，原始资源块和内容元数据保存在 mcp_content 条目中。
嵌入资源: 转换结果不再主动获取资源 URI。需要获取资源时需显式调用 readResource()。路由到模型内容时，嵌入文本资源会转为文本块，嵌入二进制资源根据 MIME 类型转为图像、音频或文件块。
资源链接: resource_link 块会转为 file 块并包含 url、mimeType 和资源元数据。更新使用 1.x 版本的 source_type 和 mime_type 字段消费者。
工具错误: 当服务器返回包含 isError 的结果时，适配器会返回 ToolMessage 并包含 status: "error"（用于智能体工具调用）。直接调用带普通参数的工具有时会抛出 ToolException，将 MCP 响应在 error.result 中返回。由于这些结果是返回而非抛出，不再触发异常处理机制（如 toolRetryMiddleware 或 ToolNode handleToolErrors 函数）。通过 ToolMessage.status（例如在 wrapToolCall 中）检查 outputHandling 以重试。即使 outputHandling 路由文本到附件，服务器的错误文本始终发送给模型。
其他失败: 连接和验证失败仍会从工具抛出异常。直接调用工具时会抛出异常；在 createAgent 智能体中，默认错误处理将其转为 ToolMessage 并包含 status: "error"。读取异常的 message 获取详情； cause 不总是设置。
钩子结果: 钩子保留返回的 ToolMessage 和 LangGraph Command 对象，而非扁平化或拒绝。 afterToolCall 仅接收成功结果。
资源读取: readResource() 保留 SDK 内容元数据。通过 "text" in content 或 "blob" in content 筛选每个项目。
结构化内容: 包含单个文本块的响应会转为字符串 content，即使携带 structuredContent 或 _meta。1.x 版本将两者合并到内容中，因此模型可见。从 mcp_structured_content 和 mcp_meta 附件条目读取它们。
工具方案: 工具输入方案以服务器声明的形式传递给模型。1.x 版本内联 $ref 定义并简化复合方案：合并 allOf，扁平化 anyOf 和 oneOf，移除 if/then/else、not 和 $schema/unevaluatedProperties。检查来自复杂方案的 listToolsets() 工具与模型服务提供商兼容性。

生命周期

分组发现: listToolsets() 返回服务名到工具的映射， listTools() 平坦化该映射。
可重用关闭: 在使用工具期间保持适配器打开，之后 await close()。关闭会停止活动发现、挂起的重连并清除连接和缓存。之后重新发现工具以重用适配器。
发现缓存: listTools([], { cacheMode: "refresh" }) 刷新发现； cacheMode: "bypass" 跳过缓存。刷新失败仍保留之前返回的工具。
资源列表: listResources() 和 listResourceTemplates() 现在抛出服务器的错误（1.x 版本对失败服务器返回 [] 并仅在 DEBUG 下记录错误）。无资源模板的服务器仍以 [] 列出资源。
重连失败: 背景 stdio 重连尝试耗尽后通过 onConnectionError 回调报告。

参考信息

官方原文：src/oss/javascript/migrate/langchain-mcp-adapters.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。

​不兼容变更

​安装

​重命名API

​已移除的选项

​配置

​将回调移动到服务器

​设置协议模式

​期待更严格的验证

​认证

​引导

​抽样与根节点

​工具结果

​生命周期

​参考信息