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 條評論

登入 後參與評論

還沒有評論,來搶沙發~