先区分三种现象
MCP 故障通常有三种不同表现：服务进程根本没启动；服务启动但工具未注册；工具已注册但调用时失败。三者的排查入口不同，不能只看最后一条模型回复。
1. 检查服务配置和 Profile
hermes profile list
hermes tools
printf '%s\n' "${HERMES_HOME:-<default>}"
确认正在使用的 Profile 与写入 MCP 配置的 Profile 相同。命名 Profile 可能有独立的配置目录，default 中可用不代表其他 Profile 也可用。
2. 脱离 Hermes 单独运行启动命令
把 MCP 配置中的启动命令、参数和工作目录复制出来，在终端单独执行。先使用不会修改数据的健康检查或帮助参数。若命令本身就报 command not found、模块缺失或权限错误，问题在运行环境，不在 Hermes 编排层。
command -v <mcp-command>
python3 -m <module> --help
尖括号内容只是占位符，不要原样复制。
3. 检查 stdio 与日志
stdio 类型 MCP 服务必须把协议输出和调试日志分开。把普通日志写到 stdout 可能破坏 JSON-RPC 通信；调试信息应写 stderr 或固定日志文件。若服务启动后立即退出，先查看退出码和 stderr。
4. 检查工作目录和环境变量
相对路径依赖当前目录，是后台运行时最常见的差异来源。将配置中的相对路径改为明确路径，或在服务定义中固定 cwd。环境变量也不能假设继承自交互式 Shell。
5. 最小化验证
先只启用一个 MCP 服务和一个只读工具，确认工具列表出现，再测试一次低风险调用。成功后逐个恢复其他服务。不要一次启用十几个 MCP，然后根据一条总错误猜原因。
如果工具已经列出但调用失败，记录工具名、参数 schema、退出码和脱敏 stderr；如果列表为空，回到配置、启动命令和 Profile 检查。
安全边界
MCP 服务往往拥有文件、网络或第三方 API 权限。只授予完成任务所需的最小权限；不要把密钥写入配置示例和日志；对写操作先设计 dry-run 或备份。
相关内容：Skill 未加载排查、配置教程。