結論先說
- 官方標準橋接包是
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 條評論
還沒有評論,來搶沙發~