Announcement

👇Official Account👇

Welcome to join the group & private message

Article first/tail QR code

PFinalClub
Search K

Appearance

LangChain 1.4.0 实战：官方 MCPAdapter 全解析 ​

TL;DR ​

  • 发布：LangChain 1.4.0（2026-09-03，基于 1.4.0a1-a4 四个 alpha 迭代）引入 langchain.mcp 命名空间与 MCPAdapter 类——LangChain 首个一方 MCP 集成，替代社区包 langchain-mcp-adapters。
  • 底座：构建在 FastMCP 4.0 之上，协议协商、连接管理、认证都由 adapter 处理。
  • 能力：MCP 服务器 → LangChain 工具的自动转换；支持 HTTP URL、本地脚本路径、transport 对象、in-process FastMCP 实例、多服务器 MCPConfig 与 ClientGroup 服务器集群。
  • 亮点：MCP elicitation（服务器向用户提问）通过 LangGraph interrupt 实现人机确认——这是两个生态原生能力的首次深度打通。
  • 状态：beta。API 可能变动，import 时会有一次性警告，生产使用建议锁定版本。

一、为什么官方适配器是 MCP 生态的分水岭 ​

在 1.4.0 之前，LangChain 接 MCP 服务器要靠社区包 langchain-mcp-adapters：第三方维护、协议版本跟进滞后、elicitation 这类新能力长期缺位。1.4.0 直接把转换逻辑搬进主库并移植了该包的实现，信号很明确——

MCP 已经不是"可选项"，而是 Agent 框架的默认工具协议。

实际收益立竿见影：企业内部为各种场景搭的 MCP 服务器（数据库查询、工单系统、监控栈），现在同一个服务器可以同时喂给 Claude Code、Cursor 和你的 LangChain Agent——一份工具实现，三处复用。

二、快速上手：从零到第一个 MCP 驱动的 Agent ​

python
# pip install -U langchain==1.4.0
# mcp extra 需要 fastmcp>=4.0
from langchain.mcp import MCPAdapter
from langchain import create_agent

# 场景 1：远程 HTTP MCP 服务器
adapter = MCPAdapter("https://mcp.example.com/mcp")

async with adapter as session:
    # list_tools() 发现服务器工具，自动转成 LangChain 工具
    tools = await session.list_tools()

    agent = create_agent("anthropic:claude-sonnet-4-5", tools)
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "查一下线上订单表的慢查询"}]}
    )
# 退出 async with 时连接自动关闭

MCPAdapter 构造参数接受五种目标，自动推断连接方式：

python
# 场景 2：本地 stdio 脚本（文件路径 → 自动 spawn 子进程）
adapter = MCPAdapter("/path/to/my_mcp_server.py")

# 场景 3：in-process FastMCP 实例（测试场景零开销）
from fastmcp import FastMCP

server = FastMCP("internal-tools")

@server.tool
def query_orders(order_id: str) -> str:
    """按订单号查询订单状态"""
    return db.lookup(order_id)

adapter = MCPAdapter(server)

# 场景 4：MCPConfig 多服务器编排（一份配置喂多个服务器）
config = {
    "mcpServers": {
        "database": {"url": "https://db-mcp.internal/mcp"},
        "monitoring": {"command": "python", "args": ["monitor_mcp.py"]},
    }
}
adapter = MCPAdapter(config)

# 场景 5：ClientGroup——一个客户端管理一组服务器（1.4.0 alpha 线加入）
# 适合"服务器集群挂在一个入口后面"的网关式部署

这个"目标多态"设计很务实：开发时用 in-process 实例（快），测试时用本地脚本（隔离），生产用 HTTP URL 或 ClientGroup（可扩展）——同一份 Agent 代码不改一行。

三、核心机制拆解 ​

3.1 工具转换：MCP schema → LangChain 工具 ​

list_tools() 内部做的事：调用 MCP 协议的 tools/list，把每个工具的 name/description/inputSchema 转换成 LangChain 的工具对象。转换后传给 create_agent 的工具与原生 LangChain 工具完全同构——模型看到的 schema、调用后的结果回传格式都没有区别。

架构视角：

┌────────────────────────────────────────────────────┐
│                create_agent                        │
│  tools = [原生工具, 原生工具, ...MCP 转换工具]        │
└──────────────────────┬─────────────────────────────┘
                       │ 工具调用
┌──────────────────────▼─────────────────────────────┐
│  MCPAdapter（langchain.mcp，beta）                  │
│  · 协议协商与连接管理（FastMCP 4.0 Client）          │
│  · inputSchema → LangChain 参数 schema             │
│  · elicitation → LangGraph interrupt               │
│  · cache_mode 工具列表缓存                          │
└──────────────────────┬─────────────────────────────┘
                       │ MCP 协议（stdio / HTTP）
┌──────────────────────▼─────────────────────────────┐
│  MCP 服务器（数据库/工单/监控/自建）                  │
└────────────────────────────────────────────────────┘

3.2 elicitation → LangGraph interrupt：人机确认的原生打通 ​

这是 1.4.0 最有价值的功能集成。MCP elicitation 允许服务器在执行过程中向用户提问（"要删除 3 万条数据，确认吗？"）。早期适配器直接丢弃这个能力，1.4.0 把它路由到 LangGraph 的 interrupt 机制：

python
# Agent 运行中，MCP 服务器发起 elicitation：
# → LangGraph 产生 interrupt，图执行暂停
# → 客户端拿到问题，展示给人类用户
# → 用户回答后 resume，答案回传 MCP 服务器，工具继续执行

工程意义：危险工具的审批流不再需要你自己造。MCP 服务器声明"这个操作需要确认"，LangChain 侧自动获得暂停-审批-恢复的完整工作流。这正好呼应了近期 MCP 安全事件（Deadbugz 类投毒、危险工具误调用）的防御需求——审批内建于协议层。

3.3 cache_mode：工具列表的性能开关 ​

list_tools() 支持 cache_mode 参数。高频创建 Agent 的服务（每个请求起一个 agent）如果每次都全量拉取工具列表，延迟和服务器压力都不可接受：

python
# 工具列表缓存——适合服务器工具集稳定的部署
tools = await session.list_tools(cache_mode="enabled")

权衡点：缓存意味着服务器侧工具变更不会立即生效。结合最近的 Deadbugz 事件，这里有个微妙的安全考量——缓存工具元数据反而是防御工具元数据漂移攻击的手段之一（变更需要显式失效，而不是静默生效）。

四、与旧方案迁移：langchain-mcp-adapters → langchain.mcp ​

维度langchain-mcp-adapters（社区）langchain.mcp MCPAdapter（1.4.0 一方）
维护社区LangChain 官方
底座mcp SDK 直连FastMCP 4.0
elicitation不支持→ LangGraph interrupt
多服务器MultiServerMCPClientMCPConfig / ClientGroup
协议时代单一自动协商（新旧 MCP 协议混布集群可用）

迁移要点：

  1. 官方移植了社区包的转换实现，convert_mcp_tool_to_langchain_tool 更名为 as_langchain_tool、get_tools 更名为 list_tools——改名不改语义，全局替换即可；
  2. ClientGroup 是新增能力，社区包没有对应物，网关式部署建议直接上；
  3. 过渡期两个包可以并存，按服务器逐个切，不要一刀切。

五、生产使用检查清单 ​

langchain.mcp 目前是 beta，import 会打印一次警告，API 可能变。上生产前过一遍：

六、结语 ​

LangChain 1.4.0 的 MCPAdapter 单看是"少装一个社区包"，放进时间线看是 Agent 框架格局的定型时刻：MCP 成为 LangChain、Claude Code、Cursor 三大生态的公共工具总线，FastMCP 成为 Python 侧事实标准底座。对企业开发者，现在搭 MCP 服务器是稳赚不赔的投入——写一次，全生态可用。对框架观察者，值得盯的是 elicitation × LangGraph interrupt 这条线：当审批流内建于协议层，"AI Agent 人机协同"才真正有了标准件。

参考 ​

上次更新于: