一、背景:为什么要接多个 MCP?
我的 LangGraph Agent 已经跑通了一个 FastMCP 服务(叫 yun120),专门查本地 MySQL,提供 15 个工具:站点访问量统计、柱状图/折线图渲染、音乐/简历/文章/RBAC 查询等。
现在我又新建了一个独立的 FastMCP 项目(叫 demo1),里面只有两个搞笑工具:flip_coin(抛硬币)和 make_decision(从多个选项里随机挑一个,治疗选择困难症)。
这两个项目是完全独立的:
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 一样的双模式:
"""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。
#!/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 的命名规则
# ====== 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 字典"。
@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。
架构图:
┌─────────────────────────────────────────────┐
│ langgraph-demo2 Agent (3.14) │
│ │
│ MCPAdapter ──┬──拉起──▶ yun120 子进程(3.14) │
│ │ └─ 15 个 MySQL 工具 │
│ └──拉起──▶ demo1 子进程(3.12) │
│ └─ 2 个随机工具 │
└─────────────────────────────────────────────┘
17 个工具合并给 Agent 用
四、核心坑:工具名被 langchain 偷偷加了前缀
改完一跑,工具列表从 15 变成 17 个,看起来成功了。结果我问"用柱状图展示今年各站点访问量",模型说找不到 chart_visit_trend 工具。
我打印工具名一看,懵了:
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 里写死了工具名:
SYSTEM_PROMPT = """
...
画图规则: 访问量随时间变化用 chart_visit_trend, 各站点对比用 chart_visit_by_site ...
"""
现在工具名变成了 default_chart_visit_trend,模型当然找不到。
五、解决方案:3 行代码
在 start() 里 list_tools() 之后,把 default_ 前缀去掉(yun120 是默认 MCP,和 SYSTEM_PROMPT 保持一致),其他 MCP 的前缀保留(防冲突):
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])
再打印一次,工具名正常了:
--- 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 只要两步
- 新项目写好
server.py(加和 yun120/demo1 一样的 argparsemain())和run.sh langgraph-demo2/.env加一行:
LYF_MCP_CMD_NEWPROJECT=/Users/liyefeng/Documents/.../newproject/run.sh
重启 langgraph dev 就自动加载,agent.py 不用再改。
八、待办:服务器部署切 HTTP 多路
本地 stdio 跑通了,服务器上要切 HTTP 模式。_build_adapter() 里已经写了 HTTP 骨架,但 _CompositeHTTPAdapter 聚合适配器(逐个 __aenter__ + 合并 list_tools())还没实现,下次填坑。
服务器架构应该是:
[前端 8080] → [Agent 2024] → [yun120 MCP 8765] → [MySQL 3306]
└→ [demo1 MCP 8766]
所有内部服务绑 127.0.0.1,仅对外暴露前端。
九、总结
- langchain 的 MCPAdapter 原生支持多 server stdio:传一个
mcpServers字典就行,它会并行拉起所有子进程 - 多 server 时工具名会自动加
<server_name>_前缀:这是防冲突机制,但会让 SYSTEM_PROMPT 里写死的工具名失效 - 解决方案:默认 MCP 去掉前缀,额外 MCP 保留前缀
- 本地用 stdio,服务器用 HTTP:这是 FastMCP 官方推荐的分工
踩过 langchain 的哪些坑?评论区聊聊~