Skip to main content
模型上下文协议(MCP)是一个开放协议,标准化了应用程序向大语言模型(LLM)提供工具和上下文的方式。LangChain 智能体可以通过 langchain-mcp-adapters 库使用 MCP 服务器上定义的工具。

快速入门

安装 langchain-mcp-adapters 库:
langchain-mcp-adapters 允许智能体使用一个或多个 MCP 服务器上定义的工具。
MultiServerMCPClient 默认是无状态的。每次工具调用都会创建一个新的 MCP ClientSession,执行工具,然后清理。有关更多详情,请参阅有状态会话部分。
访问多个 MCP 服务器
使用 LangSmith 追踪 MCP 工具调用以及智能体的推理步骤。按照追踪快速入门指南进行设置。

自定义服务器

要创建自定义 MCP 服务器,请使用 FastMCP 库:
要使用 MCP 工具服务器测试你的智能体,请使用以下示例:

传输方式

MCP 支持不同的客户端-服务器通信传输机制。

HTTP

http 传输(也称为 streamable-http)使用 HTTP 请求进行客户端-服务器通信。有关更多详情,请参阅 MCP HTTP 传输规范

传递请求头

通过 HTTP 连接到 MCP 服务器时,你可以使用连接配置中的 headers 字段包含自定义请求头(例如用于认证或追踪)。sse(已被 MCP 规范弃用)和 streamable_http 传输均支持此功能。
使用 MultiServerMCPClient 传递请求头

认证

langchain-mcp-adapters 库底层使用官方 MCP SDK,允许你通过实现 httpx.Auth 接口来提供自定义认证机制。

stdio

客户端将服务器作为子进程启动,并通过标准输入/输出进行通信。最适合本地工具和简单配置。
与 HTTP 传输不同,stdio 连接本质上是有状态的:子进程在客户端连接的整个生命周期内持续存在。但是,当使用 MultiServerMCPClient 而不进行显式会话管理时,每次工具调用仍然会创建一个新会话。有关管理持久连接的信息,请参阅有状态会话

有状态会话

默认情况下,MultiServerMCPClient无状态的:每次工具调用都会创建一个新的 MCP 会话,执行工具,然后清理。 如果你需要控制 MCP 会话的生命周期(例如,当使用跨工具调用维护上下文的有状态服务器时),你可以使用 client.session() 创建持久的 ClientSession
使用 MCP ClientSession 进行有状态工具使用

核心功能

工具

工具允许 MCP 服务器暴露可执行函数,供大语言模型(LLM)调用以执行操作——如查询数据库、调用 API 或与外部系统交互。LangChain 将 MCP 工具转换为 LangChain 工具,使其可以直接在任何 LangChain 智能体或工作流中使用。

加载工具

使用 client.get_tools() 从 MCP 服务器检索工具并传递给你的智能体:

结构化内容

MCP 工具可以在人类可读的文本响应之外返回结构化内容。当工具需要返回机器可解析的数据(如 JSON)以及展示给模型的文本时,这很有用。 当 MCP 工具返回 structuredContent 时,适配器将其包装在 MCPToolArtifact 中,并作为工具的 artifact 返回。你可以通过 ToolMessage 上的 artifact 字段访问它。你也可以使用拦截器自动处理或转换结构化内容。 从 artifact 提取结构化内容 调用智能体后,你可以从响应中的工具消息访问结构化内容:
通过拦截器追加结构化内容 如果你希望结构化内容在对话历史中可见(对模型可见),你可以使用拦截器自动将结构化内容追加到工具结果中:

多模态工具内容

MCP 工具可以在其响应中返回多模态内容(图片、文本等)。当 MCP 服务器返回包含多个部分(例如文本和图片)的内容时,适配器将其转换为 LangChain 的标准内容块。你可以通过 ToolMessage 上的 content_blocks 属性访问标准化表示:
这允许你以提供商无关的方式处理多模态工具响应,无论底层 MCP 服务器如何格式化其内容。

资源

资源允许 MCP 服务器暴露数据——如文件、数据库记录或 API 响应——供客户端读取。LangChain 将 MCP 资源转换为 Blob 对象,提供统一的文本和二进制内容处理接口。

加载资源

使用 client.get_resources() 从 MCP 服务器加载资源:
你也可以直接使用 load_mcp_resources 配合会话进行更精细的控制:

提示词

提示词允许 MCP 服务器暴露可复用的提示词模板,供客户端检索和使用。LangChain 将 MCP 提示词转换为消息,使其易于集成到基于聊天的工作流中。

加载提示词

使用 client.get_prompt() 从 MCP 服务器加载提示词:
你也可以直接使用 load_mcp_prompt 配合会话进行更精细的控制:

高级功能

工具拦截器

MCP 服务器作为独立进程运行——它们无法访问 LangGraph 运行时信息,如存储上下文或智能体状态。拦截器弥补了这个差距,让你在 MCP 工具执行期间可以访问这些运行时上下文。 拦截器还提供类似中间件的工具调用控制:你可以修改请求、实现重试、动态添加请求头,或完全短路执行。

访问运行时上下文

当 MCP 工具在 LangChain 智能体中使用时(通过 create_agent),拦截器可以访问 ToolRuntime 上下文。这提供了对工具调用 ID、状态、配置和存储的访问——支持访问用户数据、持久化信息和控制智能体行为等强大模式。
访问用户特定的配置,如在调用时传递的用户 ID、API 密钥或权限:
将用户上下文注入 MCP 工具调用
有关更多上下文工程模式,请参阅上下文工程工具

状态更新和命令

拦截器可以返回 Command 对象来更新智能体状态或控制图执行流程。这对于追踪任务进度、在智能体之间切换或提前结束执行很有用。
标记任务完成并切换智能体
使用 Command 配合 goto="__end__" 提前结束执行:
成功时结束智能体运行

自定义拦截器

拦截器是包装工具执行的异步函数,支持请求/响应修改、重试逻辑和其他横切关注点。它们遵循”洋葱”模式,列表中的第一个拦截器是最外层。 基本模式 拦截器是一个接收请求和处理器的异步函数。你可以在调用处理器之前修改请求、在之后修改响应,或完全跳过处理器。
基本拦截器模式
修改请求 使用 request.override() 创建修改后的请求。这遵循不可变模式,原始请求保持不变。
修改工具参数
在运行时修改请求头 拦截器可以根据请求上下文动态修改 HTTP 请求头:
动态请求头修改
组合拦截器 多个拦截器以”洋葱”顺序组合——列表中的第一个拦截器是最外层:
组合多个拦截器
错误处理 使用拦截器捕获工具执行错误并实现重试逻辑:
出错时重试
你也可以捕获特定的错误类型并返回降级值:
带降级的错误处理

进度通知

订阅长时间运行的工具执行的进度更新:
进度回调
CallbackContext 提供:
  • server_name:MCP 服务器的名称
  • tool_name:正在执行的工具名称(在工具调用期间可用)

日志记录

MCP 协议支持来自服务器的日志通知。使用 Callbacks 类订阅这些事件。
日志回调

引出

引出允许 MCP 服务器在工具执行期间请求用户的额外输入。服务器可以在需要时交互式地请求信息,而不是要求预先提供所有输入。

服务器设置

定义一个使用 ctx.elicit() 请求用户输入的工具,带有 schema:
带引出的 MCP 服务器

客户端设置

通过向 MultiServerMCPClient 提供回调来处理引出请求:
处理引出请求

响应动作

引出回调可以返回三种动作之一:
响应动作示例

更多资源