Hermes Agent 接入 MCP：配置与使用完全指南

AI 智能体时代，工具生态的丰富程度直接决定了一个 Agent 的能力上限。Hermes Agent 内置了完整的 MCP（Model Context Protocol）客户端，可以把任意 MCP 工具服务器接入为自己的原生工具——无需编写桥接代码，discovery 到注册全自动完成。本文基于官方文档，详细讲解 MCP 接入方法、配置选项、安全机制和实战例子。

MCP 是什么

MCP 是一种开放协议，让 AI 智能体能动态连接外部工具服务器。GitHub、数据库、文件系统、浏览器自动化、企业内部 API……只要实现了 MCP 协议，就可以无缝接入 Hermes 的工具库。对于用户来说，不需要写一行代码，只需要声明服务器地址和凭证，剩下的全由 Hermes 自动完成。

前置要求

标准安装脚本已包含 MCP 支持。单独安装进入虚拟环境后执行：

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

另外根据要接入的服务器类型准备运行时：

Node.js / npx — 用于官方 filesystem、github 等 Node.js 实现的 MCP 服务器
uvx — 用于 Python 实现的 MCP 服务器

两种 MCP 服务器类型
Stdio 服务器（本地进程）

Hermes 以子进程启动 MCP 服务器，通过 stdin/stdout 通信，适合低延迟、本地资源访问的场景。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    timeout: 60

选择 stdio 的场景：服务器安装在本地、需要访问本地文件系统、低延迟要求、服务器文档中使用 command/args/env 说明。

HTTP 服务器（远程端点）

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer YOUR_API_KEY_HERE"
    timeout: 180
    connect_timeout: 30

选择 HTTP 的场景：服务器部署在远程、组织的内网 MCP 服务、不想在本地起子进程、需要连接第三方 MCP API。

完整配置参考

所有配置写入 ~/.hermes/config.yaml 的 mcp_servers 节点。完整字段说明：

字段	类型	说明
command	string	stdio 服务器的可执行文件（npx / uvx / 绝对路径）
args	list	命令参数列表，如 `["-y", "package-name", "/allowed/path"]`
env	mapping	透传给子进程的环境变量（只有这里声明的才会透传）
url	string	HTTP MCP 端点地址（与 command 二选一）
headers	mapping	HTTP 请求头，用于 Authorization 等
timeout	number	单次工具调用超时（秒），默认 120
connect_timeout	number	初始连接 discovery 超时（秒），默认 60
enabled	bool	false 时完全跳过该服务器
tools	mapping	工具过滤：include/exclude/prompts/resources

工具命名规则

接入的 MCP 工具以 mcp_{服务器名}_{原工具名} 的格式注册：

服务器	MCP 原工具名	Hermes 调用名
filesystem	read_file	mcp_filesystem_read_file
github	create-issue	mcp_github_create_issue
my-api	query.data	mcp_my_api_query_data

实际使用时无需手动指定工具名，Hermes 根据对话内容自动选择合适的工具。

工具过滤：细粒度权限控制
完全禁用服务器

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

白名单模式（只暴露指定工具）

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    tools:
      include: [create_issue, list_issues, search_code]

黑名单模式（排除指定工具）

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer YOUR_API_KEY_HERE"
    tools:
      exclude: [delete_customer]

禁用 resource / prompt utility

MCP 服务器还支持 resource 和 prompt 相关的 utility 工具，可用以下方式禁用：

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

安全机制
环境变量隔离

这是 MCP 安全模型最重要的一点：Hermes 不会把全局环境变量透传给 MCP 子进程。子进程只会继承基础变量（PATH、HOME、USER、LANG、TERM 等），API 密钥必须显式声明在 env 配置里才会透传。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # 只有显式声明的这个变量会透传
      # 全局 .env 中的 GITHUB_TOKEN 不会泄露给这个子进程
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"

凭证自动脱敏

如果 MCP 工具调用失败，Hermes 会自动从错误信息中移除凭证相关内容（ghp_、sk-、Bearer token 等），防止敏感信息进入对话上下文。

运行时行为
启动时 Discovery

Hermes 启动时读取 mcp_servers 配置，依次连接每个服务器并调用 list_tools() 获取工具列表，注册到全局工具库。全部在后台异步完成，不阻塞主对话。

动态工具变更

如果 MCP 服务器在运行时发送 notifications/tools/list_changed 通知，Hermes 会自动重新 discovery 并更新工具列表——无需手动重载。

热重载

修改配置后，在会话中输入 /reload-mcp 即可重新加载所有 MCP 服务器并刷新工具列表。

实战配置示例
1. 时间服务器（uvx）

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

接入后可直接问 Hermes：”现在几点了？”——背后调用的就是 MCP 时间服务器工具。

2. 文件系统访问（npx）

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 30

注意最后一个参数是允许访问的目录白名单路径。

3. GitHub 集成（npx）

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
    tools:
      include: [create_issue, list_issues, search_code]
      prompts: false

这里只授权了三个核心操作，并禁用了 prompt utility，符合最小权限原则。

4. 多服务器组合

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"

  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer YOUR_API_KEY_HERE"
    timeout: 300

四个服务器同时接入，互不干扰，各有各的认证方式和超时配置。

CLI 管理命令

除直接编辑 config.yaml 外，也可通过 Hermes 命令行管理 MCP 服务器：

命令	说明
hermes mcp list	列出当前所有配置的服务器及连接状态
hermes mcp add NAME	添加服务器（–command 或 –url）
hermes mcp remove NAME	删除服务器
hermes mcp test NAME	测试连接
hermes mcp configure NAME	交互式配置工具过滤规则
/reload-mcp	会话内热重载 MCP 配置

排查问题
“MCP SDK not available — skipping MCP tool discovery”

需要安装 MCP 包：uv pip install mcp

工具不出现

确认配置写在 mcp_servers 节点下（不是 mcp 或 servers）
YAML 缩进正确，mcp_servers 是一级键
查看 Hermes 启动日志有无连接成功信息
工具名前缀是 mcp_{服务器名}_{工具名}

连接频繁断开

检查网络连通性，或增加 timeout / connect_timeout 值。服务器端也要确认正常可用。

npx / uvx 命令找不到

确保 Node.js（npx）和 uv（uvx）在 PATH 中：

which npx
which uvx

总结

Hermes Agent 的 MCP 集成设计得非常克制——只需要声明服务器地址和凭证，剩下的 discovery、注册、重连、脱敏全部自动化。与其自己实现各种 API 桥接，不如让专业的 MCP 服务器来做专业的事。GitHub 工具交给 github-mcp-server，文件系统交给 filesystem-mcp-server，企业 API 交给内网 MCP 服务——Hermes 作为统一入口，把这些能力串联起来，这才是 MCP 协议的真正价值所在。

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp