「踩坑实录」给 LangGraph Agent 接两个 FastMCP,我被 langchain 偷偷改了工具名

一、背景:为什么要接多个 MCP?

我的 LangGraph Agent 已经跑通了一个 FastMCP 服务(叫 yun120),专门查本地 MySQL,提供 15 个工具:站点访问量统计、柱状图/折线图渲染、音乐/简历/文章/RBAC 查询等。

现在我又新建了一个独立的 FastMCP 项目 (叫 demo1),里面只有两个搞笑工具:flip_coin(抛硬币)和 make_decision(从多个选项里随机挑一个,治疗选择困难症)。

这两个项目是完全独立的:

makefile 复制代码
yun120:  Python 3.14,和 LangGraph Agent 共用同一个 venv
demo1:   Python 3.12,自己独立的 venv

需求:让 Agent 同时能调用 yun120 的 15 个工具和 demo1 的 2 个工具。


二、选型:stdio 多路 vs HTTP 常驻

给一个 Agent 接多个 MCP,有两种主流方案,我做了张对比表:

维度 stdio 多路(本地) HTTP 常驻(服务器)
MCP 生命周期 绑定 Agent 进程,Agent 死则全挂 独立 systemd/Docker 托管
依赖要求 Agent 要能访问所有 MCP 的 venv 和可执行文件 只要求 Agent 能访问 HTTP 地址
工具复用 只能被拉起它的那个 Agent 用 任意客户端(其他 Agent、MCP Inspector)可连
故障隔离 无,某个 MCP 崩可能拖垮 Agent 完全隔离
可观测性 日志全混在 Agent stdout 里 每个 MCP 独立日志/指标
开发体验 改 .env 就行,用完自动销毁 要单独起服务占端口

结论:

  • 本地开发选 stdio 多路------省资源、改动小、venv 天然隔离,调完即走
  • 服务器部署选 HTTP 常驻------稳定、可运维、可复用,是 FastMCP 官方推荐的生产方式

我先把本地 stdio 多路跑通,给 demo1 加了 HTTP 参数留好退路,等上服务器再切。


三、实现:4 步改造

3.1 给 demo1 加 argparse(留 HTTP 退路)

demo1 原来的 server.py 只有简单的 mcp.run(),改成和 yun120 一样的双模式:

python 复制代码
"""demo1 FastMCP ------ 选择困难症辅助工具"""
from __future__ import annotations

import argparse
import random

from fastmcp import FastMCP

mcp = FastMCP(
    name="Decision Helper",
    instructions="帮你随机做选择的小工具: make_decision 从多个选项里随机挑一个, flip_coin 抛硬币。",
)

@mcp.tool
def make_decision(options: list[str]) -> str:
    """从给定的选项中随机选一个,帮你治疗选择困难症。"""
    if not options:
        return "你什么都没给,我很难办啊。"
    choice = random.choice(options)
    return f"天意如此,就选这个吧:**{choice}**"

@mcp.tool
def flip_coin() -> str:
    """抛硬币,正面或反面。"""
    return random.choice(["正面 (Heads)", "反面 (Tails)"])

def main() -> None:
    parser = argparse.ArgumentParser(description="demo1 FastMCP server")
    parser.add_argument(
        "--mode", choices=["http", "stdio"], default="stdio",
        help="http=常驻 Streamable HTTP (服务器用), stdio=被 Agent 拉起 (本地用)"
    )
    parser.add_argument("--addr", default="127.0.0.1:8766", help="HTTP 模式 host:port")
    parser.add_argument("--path", default="/mcp", help="HTTP 模式路径")
    args = parser.parse_args()

    if args.mode == "http":
        host, port = args.addr.split(":")
        print(f"[demo1] 启动 HTTP 模式: http://{host}:{port}{args.path}")
        mcp.run(transport="http", host=host, port=int(port), path=args.path, show_banner=False)
    else:
        print("[demo1] 启动 stdio 模式 (等待 Agent 拉起)...")
        mcp.run(transport="stdio", show_banner=False)

if __name__ == "__main__":
    main()

3.2 给 demo1 加 run.sh(指向自己的 venv)

关键:demo1 用 Python 3.12,Agent 用 3.14,必须让 demo1 用自己的 venv,不能复用 Agent 的 venv。

bash 复制代码
#!/bin/sh
# demo1 FastMCP 启动脚本 ------ stdio 模式 (由 langgraph Agent 拉起)
set -e
DIR="$(cd "$(dirname "$0")" && pwd)"
PY="${DEMO1_PYTHON:-$DIR/.venv/bin/python}"
if [ ! -x "$PY" ]; then
  PY="$(command -v python3)"
fi
exec "$PY" -m demo1.server --mode stdio "$@"

加执行权限:chmod +x run.sh

3.3 改 .env,约定多 MCP 的命名规则

ini 复制代码
# ====== MCP (FastMCP stdio 多路, 本地开发用)
# 约定: LYF_MCP_CMD 放默认 MCP (yun120), LYF_MCP_CMD_<名字> 放额外 MCP
# 以后再加第 3 个 MCP, 只要加一行 LYF_MCP_CMD_XXX=路径 就行
LYF_MCP_MODE=stdio
LYF_MCP_CMD=/Users/liyefeng/Documents/langgraph-projects/first-project/mcp-yun120/run.sh
LYF_MCP_DSN='root:xxxxxx@tcp(127.0.0.1:3306)/xxxxx?charset=utf8mb4'
LYF_MCP_CMD_DEMO1=/Users/liyefeng/Documents/langgraph-projects/FastMCP-project/demo1/run.sh

# 服务器 HTTP 模式 (每个 MCP 独立常驻, 改 _build_adapter 循环读所有 LYF_MCP_URL_*)
# LYF_MCP_MODE=http_multiple
# LYF_MCP_URL_YUN120=http://127.0.0.1:8765/mcp
# LYF_MCP_URL_DEMO1=http://127.0.0.1:8766/mcp

3.4 改 agent.py 的 _build_adapter()

这是核心改动------把原来"只读一个 LYF_MCP_CMD"改成"循环读所有 LYF_MCP_CMD_* 变量,拼进 mcpServers 字典"。

python 复制代码
@staticmethod
def _build_adapter() -> MCPAdapter | None:
    """构建 MCPAdapter, 支持 stdio 多路:
    读 LYF_MCP_CMD (默认 yun120) + 所有 LYF_MCP_CMD_* (额外 MCP, 比如 demo1),
    循环拼进一个 mcpServers 字典, 一次喂给 MCPAdapter, 并行拉起所有子进程
    """
    mode = os.getenv("LYF_MCP_MODE", "http").lower()
    if mode in ("http", "http_multiple"):
        # ... HTTP 模式骨架 (留给服务器部署时实现)
        ...

    # === stdio 模式 (本地开发用) ===
    cmds: list[tuple[str, str]] = []
    if c := os.getenv("LYF_MCP_CMD"):
        cmds.append(("default", c))  # 默认 MCP 叫 "default"
    for key, val in sorted(os.environ.items()):
        if key.startswith("LYF_MCP_CMD_") and val:
            # 变量名后缀作为 server 名, 比如 LYF_MCP_CMD_DEMO1 → "demo1"
            server_name = key[len("LYF_MCP_CMD_"):].lower()
            cmds.append((server_name, val))

    if not cmds:
        return None

    # 拼 mcpServers 字典 ------ langchain 的 MCPAdapter 原生支持 stdio 配置里放多个 server
    mcp_servers: dict[str, dict] = {}
    for name, cmd in cmds:
        args: list[str] = []
        # 只有默认 yun120 MCP 才吃 DSN/TABLE 参数, 额外 MCP 不吃
        if name == "default":
            if dsn := os.getenv("LYF_MCP_DSN"):
                args += ["--dsn", dsn]
            if table := os.getenv("LYF_MCP_TABLE"):
                args += ["--table", table]
        mcp_servers[name] = {"command": cmd, "args": args, "transport": "stdio"}

    logger.info("使用 stdio 启动 %d 个 MCP 子进程: %s", len(cmds), list(mcp_servers.keys()))
    return MCPAdapter({"mcpServers": mcp_servers})

原理 :langchain 的 MCPAdapter 原生接受一个包含多个 server 配置的字典,它会并行拉起所有子进程,每个子进程通过 stdio 对接,然后把两边的工具合并成一个列表返回给 Agent。

架构图:

scss 复制代码
┌─────────────────────────────────────────────┐
│          langgraph-demo2 Agent (3.14)        │
│                                              │
│   MCPAdapter ──┬──拉起──▶ yun120 子进程(3.14)  │
│                │           └─ 15 个 MySQL 工具 │
│                └──拉起──▶ demo1 子进程(3.12)    │
│                            └─ 2 个随机工具      │
└─────────────────────────────────────────────┘
              17 个工具合并给 Agent 用

四、核心坑:工具名被 langchain 偷偷加了前缀

改完一跑,工具列表从 15 变成 17 个,看起来成功了。结果我问"用柱状图展示今年各站点访问量",模型说找不到 chart_visit_trend 工具。

我打印工具名一看,懵了:

shell 复制代码
await toolbox.start()
print([t.name for t in toolbox.tools])
# 输出:
# ['default_list_tables', 'default_describe_table', 'default_run_sql',
#  'default_visit_stats', 'default_chart_visit_trend', ...,
#  'demo1_make_decision', 'demo1_flip_coin']

所有工具名前面都被加了 server 名前缀 !yun120 的工具变成 default_xxx,demo1 的变成 demo1_xxx。

为什么会这样?

langchain 的 MCPAdapter 在多 server 模式下 ,为了防止两个 MCP 有同名工具(比如都叫 run_sql),自动给每个工具名加 <server_name>_ 前缀。yun120 是 "default",demo1 是 "demo1"。

后果

我在 SYSTEM_PROMPT 里写死了工具名:

ini 复制代码
SYSTEM_PROMPT = """
...
画图规则: 访问量随时间变化用 chart_visit_trend, 各站点对比用 chart_visit_by_site ...
"""

现在工具名变成了 default_chart_visit_trend,模型当然找不到。


五、解决方案:3 行代码

在 start() 里 list_tools() 之后,把 default_ 前缀去掉(yun120 是默认 MCP,和 SYSTEM_PROMPT 保持一致),其他 MCP 的前缀保留(防冲突):

python 复制代码
self._tools = await adapter.list_tools()

# langchain MCPAdapter 在多 server 时给工具名加 server 前缀 (比如 default_ / demo1_)
# 把 "default_" 去掉, 让 yun120 工具名和 SYSTEM_PROMPT 里写的一致; 其他前缀保留防冲突
for t in self._tools:
    if t.name.startswith("default_"):
        t.name = t.name[len("default_"):]

self.status = "ready"
logger.info("MCP 工具加载完成: %s", [t.name for t in self._tools])

再打印一次,工具名正常了:

scss 复制代码
--- yun120 (15 个, 无前缀) ---
['list_tables', 'describe_table', 'run_sql', 'visit_stats', 'visit_trend', 'visit_range', 'chart_visit_trend', 'chart_visit_by_site', 'make_chart', 'music_overview', 'search_music', 'resume_profile', 'search_articles', 'rbac_overview', 'user_permissions']

--- demo1 (2 个, demo1_ 前缀保留) ---
['demo1_make_decision', 'demo1_flip_coin']

为什么不去掉 demo1_ 前缀? 因为额外 MCP 数量会增长,保留前缀能防止未来和其他 MCP 工具名冲突。yun120 是默认 MCP,已经写在 SYSTEM_PROMPT 里了,所以去掉。


六、端到端验证

重启 langgraph dev,打开前端发"帮我抛个硬币吧",AI 回复:

🪙 硬币抛出来了:反面 (Tails)

模型成功调用了 demo1_flip_coin 工具,链路完全打通。


七、扩展性:以后加第 3 个 MCP 只要两步

  1. 新项目写好 server.py(加和 yun120/demo1 一样的 argparse main())和 run.sh
  2. langgraph-demo2/.env 加一行:
bash 复制代码
LYF_MCP_CMD_NEWPROJECT=/Users/liyefeng/Documents/.../newproject/run.sh

重启 langgraph dev 就自动加载,agent.py 不用再改。


八、待办:服务器部署切 HTTP 多路

本地 stdio 跑通了,服务器上要切 HTTP 模式。_build_adapter() 里已经写了 HTTP 骨架,但 _CompositeHTTPAdapter 聚合适配器(逐个 __aenter__ + 合并 list_tools())还没实现,下次填坑。

服务器架构应该是:

css 复制代码
[前端 8080] → [Agent 2024] → [yun120 MCP 8765] → [MySQL 3306]
                        └→ [demo1 MCP 8766]

所有内部服务绑 127.0.0.1,仅对外暴露前端。


九、总结

  1. langchain 的 MCPAdapter 原生支持多 server stdio :传一个 mcpServers 字典就行,它会并行拉起所有子进程
  2. 多 server 时工具名会自动加 <server_name>_ 前缀:这是防冲突机制,但会让 SYSTEM_PROMPT 里写死的工具名失效
  3. 解决方案:默认 MCP 去掉前缀,额外 MCP 保留前缀
  4. 本地用 stdio,服务器用 HTTP:这是 FastMCP 官方推荐的分工

踩过 langchain 的哪些坑?评论区聊聊~


相关推荐
阿里云大数据AI技术9 分钟前
穹彻智能 × MaxCompute:具身智能 UMI 数据产线的全模态计算实践
人工智能
联犀14 分钟前
ai时代复杂项目的golang项目如何更好的与ai共舞:monorepo+gozero
开发语言·人工智能·golang
飞Link30 分钟前
灵巧手是什么?从机械结构、驱动方式到控制原理,认识机器人的精细操作能力
人工智能·python·机器人
Resean022332 分钟前
Spring 源码分析(一)IOC 容器总览与 refresh() 全景
java·后端·spring
苍何32 分钟前
一句话出成片,我搭了个AI视频工厂
后端
跳跳的小星星34 分钟前
自研组件】Vue2 + ElementUI 通用列表页封装 wkjp-list-page,一套配置搞定搜索、动态表格、分页、增删改
前端
阿里云大数据AI技术39 分钟前
从“扫文件”到“找数据行”:EMR Serverless StarRocks 支持 Paimon Global Index
人工智能
tryCbest43 分钟前
Vue3—— 第 18 篇:Vue 2 到 Vue 3 迁移指南——升级避坑全记录
前端·vue.js
武子康1 小时前
AI通关了,游戏就算通过测试了吗?
人工智能·游戏·机器学习