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

图:本站根据 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 代码起一个本地脚本。

图:本站根据 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 消息对象注入图状态。
相关教程
- /guides/langgraph-quickstart-install-first-graph:LangGraph Python 安装与第一个状态图
- /guides/mcp-model-context-protocol:MCP 协议核心概念快速入门
- /guides/mcp-stdio-vs-streamable-http-sse:MCP 的 stdio、SSE 与 Streamable HTTP 区别
- /guides/mcp-server-python-sdk-build-quickstart:用 Python 官方 SDK 自己开发一个 MCP 服务器
参考资料
langchain-ai/langchain-mcp-adapters官方 GitHub 仓库 — https://github.com/langchain-ai/langchain-mcp-adapters- LangChain 官方文档:MCP — https://docs.langchain.com/
0 条评论
还没有评论,来抢沙发~