Hermes Agent MCP 工具加载失败：快速修复
MCP 服务器已配置，会话里却看不到任何工具。五种沉默故障与逐一解决的诊断路径。
你在 ~/.hermes/config.yaml 里加了一个 MCP 服务器，重启网关，让 Hermes 列出可用工具。什么新东西都没有。没有报错，没有告警，gateway.log 一片沉默。这篇文章就是从这份沉默走到会话中能真正调用 mcp_<server>_<tool> 的最短路径。
几乎所有报告过的问题都可以归为五种故障模式，每一种都藏在不同的位置。好消息是：hermes mcp list、hermes mcp test 加一个日志级别开关，能在两分钟内告诉你自己遇到的是哪一种。
为什么会出现沉默故障
MCP 配置是 Hermes 里日志覆盖最差的一块。当加载器无法启动服务器、导入 Python 的 mcp 额外包，或者解析 mcp_servers 块时，失败信息只会写在 DEBUG 级别，默认安装下永远不会进入 gateway.log。在你这边看起来就像配置被接受了，只是工具本来就不存在。
修复的第一步是先提高可见性，然后再动其他任何东西。用详细日志重启 Hermes，让加载器直接告诉你它为什么放弃：
hermes serve --verbose
# 或者，如果通过 docker compose 启动：
HERMES_LOG_LEVEL=DEBUG docker compose up
现在再跑一次 hermes mcp list。如果服务器出现在列表里但下面没有挂着工具，说明连接建立了但发现失败。如果服务器根本不在列表里，说明加载器压根没注册它。这两条岔路能告诉你下面哪个修复才对。
原因一：Python 额外包 mcp 没装
如果你是从源码构建 Hermes，或者把版本固定在某个特定 tag 上，mcp 是一个可选额外包，默认安装并不会带上它。少了它，mcp_servers 下面的每一条都会被静默忽略。这是自定义安装中最常见的原因。
用带上 extra 的方式重新安装：
cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
hermes serve --verbose
如果网关现在能启动并尝试去连服务器，那你之前就是缺 SDK。如果日志还在说 mcp module not available，说明 extra 没有装到 Hermes 实际使用的解释器里：检查 hermes --version 找到 venv 路径，然后在里面重新安装。
原因二：YAML 缩进偏了一个空格
YAML 会静默丢弃任何缩进和父级不匹配的块。一个跑掉的 tab、一个错误深度的 - 、命令字符串里没有加引号的冒号，都会让整个 mcp_servers 映射消失，不会给你一行提示。
安全的写法是：两个空格的缩进，凡是含冒号的字符串都加引号，列表用 - 表示：
mcp_servers:
filesystem:
command: "npx"
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
enabled: true
stripe:
url: "https://mcp.stripe.com/v1/sse"
enabled: true
两个快速检查：先跑 python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" 确认文件本身能被解析，再跑 hermes mcp list 确认名字有出现。如果文件能解析、但从 Hermes 视角看这个块是空的，那就是缩进错了，虽然 YAML 语法本身合法。
原因三：宿主机上没有 node 或 npx
社区里大多数 MCP 服务器都以 npm 包发布，用 npx -y @modelcontextprotocol/server-<name> 启动。如果宿主机的 PATH 里没有 Node.js，子进程还没打印任何东西就退出了，而 Hermes 只会在 DEBUG 级别记录这个失败。这在极简 Docker 容器里最常见。
先在 Hermes 之外把启动命令跑一遍：
node --version
npx --version
npx -y @modelcontextprotocol/server-filesystem /tmp
如果三条命令里有任何一条失败，就在 Hermes 运行的同一个环境里安装 Node.js。在 Docker 里意味着往镜像里加 nodejs 和 npm，或者选一个已经带这些的基础镜像。Hermes 没法启动一个根本不存在的 Node 二进制。
原因四：服务器连上了，但工具从未进入会话
你在 hermes mcp list 里看到服务器，hermes mcp test <server> 也能发现它的工具，可会话里就是没有任何新的可调用项。这就是 issue #51587 和 issue #71736 记录的故障：发现成功了，但工具从未被注入到会话工具集中。
可靠的绕过方式：
- 在 Hermes 会话里执行
/reload-mcp，或者干脆重启整个网关。有些构建只在启动时填充一次工具集，会漏掉稍晚启动的服务器。 - 检查会话上的
enabled_toolsets字段。如果它被约束得很紧（例如 ACP 会话把它硬编码成["hermes-acp"]），MCP 工具会被设计上排除掉，需要把工具集放宽。 - 确认你的服务商真的支持工具调用。Ollama 模型必须用与 Hermes 兼容的工具模板启动；较老的本地模型会报告发现了工具，但从来不会真的调用。
原因五：你的服务商悄悄丢掉了 tool call
即便服务器在跑、工具都注册好了，某些服务商也会在模型看到 tool payload 之前把它剥掉。表现出来的症状和 MCP 出问题一模一样：工具存在，但你请求时什么都不会发生。
两分钟自检：把会话切换到一个已知支持工具调用的服务商（任何较新的 Anthropic、OpenAI 或 Groq 模型），问同一个问题。如果在那边工具能触发，问题就出在你的服务商或模型选择上，不在 MCP。如果依然不触发，回到原因四。
按顺序执行的诊断路径
按下面的顺序执行，一旦某一步改变了你看到的现象就停下：
hermes serve --verbose- 现在故障会打到 stdout。python -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))"- 确认文件至少能被解析。hermes mcp list- 展示加载器实际接受了什么。hermes mcp test <server>- 展示连接和发现是否成立。hermes mcp health- 需要交接给别人时的每个服务器状态快照。- 在会话里执行
/reload-mcp，或者完整重启网关。 - 换成另一个服务商跑两分钟，做一次 A/B。
想要更完整地熟悉这套诊断面，可以看 Hermes 调试与可观测性指南，它讲了 gateway.log、按工具追踪调用以及如何清爽地 tail 一切。如果你还在搭第一个 MCP 服务器，MCP 配置指南 会带你走一遍配置文件形状，让上面这些故障根本没机会出现。
直接跳过整个这层表面
这篇文章里的每一种故障，都源自 Hermes 与其宿主之间的错配：缺失的 Python 额外包，缺失的 Node 二进制，配置文件上写错的权限，会话启动顺序的 bug。Hermify 会替你把这整层表面都跑起来。
开始使用 Hermify，在 Telegram 上运行一个托管的 Hermes Agent，MCP 已经接好，mcp 额外包已装，宿主机上有 npx，改配置自动重载也是出厂就能用的。你的 MCP 配置还在你手里，记忆还在你手里，也不用在周二晚上再去调 YAML 缩进。