LangGraph 怎么使用 MCP:用 langchain-mcp-adapters 接入本地与远程工具

想让自建的 LangGraph 状态图直接调用现成的 MCP 服务器,官方标准方案是安装 langchain-mcp-adapters 并使用 MultiServerMCPClient。本文讲清 stdio 与 streamable_http 两种配置写法、异步图运行及按节点分工具技巧。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 免费账号 账号

结论先说

  1. 官方标准桥接包是 langchain-mcp-adapters:它能把任意符合协议的 MCP 工具自动转换成标准的 LangChain BaseTool 对象,直接塞进 LangGraph 的 ToolNode。
  2. 用 MultiServerMCPClient 可以一次性管理多个不同协议的服务端:本地命令行脚本配 "transport": "stdio",远程网关服务配 "transport": "streamable_http"。
  3. 图执行必须改走异步接口(await graph.ainvoke 或 astream):MCP 底层通信是纯异步的,如果依然调同步的 graph.invoke() 会在执行工具节点时报错。
  4. 多 Agent 状态图里用 client.get_tools(server_name="...") 按角色隔离工具:让数据库节点只拿查库工具、文档节点只拿搜索工具,既防越权又省 Token。

LangGraph 接入两类 MCP 传输对比

图:本站根据 langchain-mcp-adapters 官方仓库文档 整理的示意图

本文根据 LangChain 官方仓库 langchain-ai/langchain-mcp-adapters 与 LangGraph 官方文档整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 或 Anthropic 官方网站。

适用于谁

  • 搜「langgraph 使用 mcp」「langchain 接入 mcp server」的人;
  • 已经跑通了基础状态图(见 /guides/langgraph-quickstart-install-first-graph),不想把查数据库、搜网页、操作 GitHub 的工具从头手写一遍,想直接复用开源 MCP 生态的开发者;
  • 运行 MCP 工具时报异步调用错误(Sync invocation is not supported)正在查改法的人。

如果你对 MCP 协议本身或传输协议还不熟,可先翻看 /guides/mcp-model-context-protocol 与 /guides/mcp-stdio-vs-streamable-http-sse。

一、安装官方适配器包

在已经装好 langgraph 的 Python 虚拟环境里,补装官方维护的 MCP 适配器与你要使用的模型包:

bash
pip install -U langgraph langchain-mcp-adapters langchain-anthropic

如果你准备顺手自己写一个极简的本地测试 MCP 服务端来联调,也可以参考 /guides/mcp-server-python-sdk-build-quickstart 用几行 FastMCP 代码起一个本地脚本。

LangGraph 连接 MCP 服务器四步法

图:本站根据 LangChain 官方 MCP 文档 整理的示意图

二、完整代码:StateGraph 同时挂载本地与远程 MCP

下面的示例展示了如何用 MultiServerMCPClient 同时接入一个本地 Python stdio 工具脚本和一个远程 streamable_http 服务端,并组装进显式的 StateGraph 异步运行:

python
import asyncio
from langchain_anthropic import ChatAnthropic
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode, tools_condition

async def main():
    # 1. 登记一个或多个 MCP 服务器连接配置
    client = MultiServerMCPClient({
        "local_calc": {
            "transport": "stdio",
            "command": "python",
            "args": ["./calc_mcp_server.py"],
        },
        "internal_docs": {
            "transport": "streamable_http",
            "url": "http://127.0.0.1:8000/mcp",
        },
    })

    # 2. 异步拉取并转换为 LangChain 标准工具列表
    tools = await client.get_tools()

    # 3. 绑定给大模型并定义异步推理节点
    llm = ChatAnthropic(model="claude-sonnet-4-5", temperature=0).bind_tools(tools)

    async def agent_node(state: MessagesState):
        response = await llm.ainvoke(state["messages"])
        return {"messages": [response]}

    # 4. 构建并编译状态图
    builder = StateGraph(MessagesState)
    builder.add_node("agent", agent_node)
    builder.add_node("tools", ToolNode(tools))

    builder.add_edge(START, "agent")
    builder.add_conditional_edges("agent", tools_condition)
    builder.add_edge("tools", "agent")

    graph = builder.compile()

    # 5. 注意:必须用异步 ainvoke 或 astream 调用
    result = await graph.ainvoke({
        "messages": [("user", "查一下内部文档里的发布清单,并核算本次变更项数量")]
    })
    print(result["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

三、两个高频进阶配置细节

1. 远程连接需要携带鉴权请求头怎么办

生产环境里的远程 streamable_http 服务通常受内网网关保护。你可以在该服务配置字典里直接添加 headers 字段,从环境变量传入令牌(不要在源码里硬编码密钥):

python
import os

client = MultiServerMCPClient({
    "corp_gateway": {
        "transport": "streamable_http",
        "url": "https://mcp.example.internal/mcp",
        "headers": {
            "Authorization": f"Bearer {os.environ['MCP_GATEWAY_TOKEN']}"
        },
    }
})

2. 多节点多 Agent 图里怎么给不同节点分不同的 MCP 工具

如果一张图里有「数据分析员」和「文档检索员」两个不同节点,直接调无参数的 await client.get_tools() 会把所有服务器的几十个工具混成一大包全塞给每个节点。更干净的做法是按登记名分开拉取:

python
calc_tools = await client.get_tools(server_name="local_calc")
doc_tools = await client.get_tools(server_name="internal_docs")

然后分别绑定给对应的模型节点和专属 ToolNode,每个代理只看自己职责范围内的工具。平时在本地客户端先验证某个第三方 MCP 好不好用、返回结构长什么样时,很多开发者也会先挂到 Claude Desktop 或 Claude Code 里试跑一轮,桌面订阅环境可参考 /chongzhi/claude-pro 的说明。

常见问题

Q:照着旧博客写 async with MultiServerMCPClient(...) as client: 为什么报错?

langchain-mcp-adapters 在版本迭代中调整了客户端生命周期写法,新版推荐直接 client = MultiServerMCPClient({...}) 后调用 await client.get_tools()。如果遇到上下文管理器相关的 TypeError,去掉 async with 改成上面示例的写法即可。

Q:用 npx 启动 Node.js 写的 MCP 服务器(如文件系统或浏览器 MCP)怎么填?

把配置里的 "command" 填 "npx","args" 填 ["-y", "@modelcontextprotocol/server-filesystem", "/允许访问的目录"],"transport" 填 "stdio" 即可。在 Windows 系统上若找不到 npx,可把 command 写成 "npx.cmd"。

Q:每次调工具都会重新拉起一次 stdio 子进程吗?如果工具需要保持会话状态怎么办?

默认无状态模式下按次建立连接更安全隔离;如果你的本地 MCP 服务必须在多次工具调用之间保留同一个进程内存态(例如已在浏览器里打开了一个页面),官方适配器还提供了基于持久 session 的加载接口(load_mcp_tools(session)),可按仓库文档包裹在同一个客户端会话生命周期内运行。

Q:接入外部 MCP 服务器前有哪些安全注意事项?

MCP 工具的描述文本与返回内容都会直接进入大模型上下文。生产环境只建议连接团队自研审计过或知名官方仓库发布的 MCP 服务,对远程连接启用最小权限令牌,并在高风险写操作节点前配合 LangGraph 的 interrupt 人工审批机制拦截确认,避免因提示词注入触发越权修改。

Q:除了拉取工具(Tools),适配器还支持读取 MCP 的提示词模板(Prompts)与资源(Resources)吗?

支持。除了最常用的 get_tools() 之外,langchain-mcp-adapters 同样封装了读取服务端预置 Prompt 模板和静态 Resource 数据的辅助方法,可以把服务端统一维护的业务指令直接转成 LangChain 消息对象注入图状态。

相关教程

参考资料

  • langchain-ai/langchain-mcp-adapters 官方 GitHub 仓库 — https://github.com/langchain-ai/langchain-mcp-adapters
  • LangChain 官方文档:MCP — https://docs.langchain.com/

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    MCP 收费吗:开源协议免费边界、第三方 API 账单与隐形 Token 开销说明

    搜「mcp 收费 吗」的人常担心装多了插件会被扣费。MCP(模型上下文协议)本身和官方 SDK 采用 MIT 协议完全免费;实际使用中可能产生费用的只有两处:挂载过多工具占用的大模型上下文 Token,以及部分外部商业数据源自带的 API 套餐。

    Claude其他 AI 工具0
  2. 02

    MCP 协议最新版本更新了什么:无状态架构、OAuth 2.1、结构化输出与异步 Tasks 详解

    搜「mcp 重大 更新」「mcp 协议 更新」想补齐规范演进脉络?本文对照 modelcontextprotocol.io 官方规范更新日志,梳理从 Streamable HTTP 到无状态优先架构、OAuth 2.1 资源服务器、Elicitation 交互补参与异步 Tasks 扩展的核心变化。

    Claude其他 AI 工具0
  3. 03

    A2A 和 MCP 有什么区别:工具连接协议与智能体通信协议的边界和配合

    很多人问「有了 MCP 为什么还要出 A2A,两者是不是二选一的竞争关系」。两份官方规范都明确写明它们是上下互补关系:MCP 负责给单个智能体挂载工具与数据源,A2A 负责让多个独立黑盒智能体跨团队、跨框架互相派单协作。

    Claude其他 AI 工具0
  4. 04

    A2A 协议是什么、怎么用:Agent2Agent 智能体互联规范、名片发现与 Python 接入流程

    A2A(Agent2Agent)是由 Google 发起并移交 Linux 基金会托管的开放智能体通信协议,用来让不同团队、不同框架开发的独立智能体跨网络互相派单协作。本文按官方规范讲清 Agent Card、Task 状态机与 Python SDK 接入步骤。

    Gemini其他 AI 工具0
  5. 05

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  6. 06

    CrewAI 多轮对话与记忆怎么配:memory=True 三层记忆、人工介入与 Flows 状态持久化

    刚用上 CrewAI 的人常疑惑 kickoff 跑完就结束,怎么做多轮连续对话与跨次记忆。本文按官方文档拆解 memory=True 的短期/长期/实体三层记忆、嵌入模型配置,以及用 Flows 状态流和 @persist 搭建多轮会话的实战写法。

    其他 AI 工具0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~