MCP（模型上下文协议）

MCP 允许 Hermes Agent 连接到外部工具服务器，使智能体可以使用位于 Hermes 之外的工具，例如 GitHub、数据库、文件系统、浏览器栈以及内部 API。

如果你希望 Hermes 使用一个已经存在于其他系统中的工具，MCP 通常是最干净的接入方式。

MCP 带来的能力

• 无需先编写原生 Hermes 工具，就能接入外部工具生态
• 可在同一份配置中混用本地 stdio 服务器与远程 HTTP MCP 服务器
• 启动时自动发现并注册工具
• 当服务器支持时，可为 MCP resources 和 prompts 提供辅助包装工具
• 支持按服务器做精细过滤，只把真正想暴露给 Hermes 的 MCP 工具开放出来

快速开始

1. 安装 MCP 支持（如果你使用的是标准安装脚本，通常已经包含）：

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

2. 在 ~/.hermes/config.yaml 中加入一个 MCP 服务器：

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

3. 启动 Hermes：

hermes chat

4. 让 Hermes 使用 MCP 提供的能力，例如：

List the files in /home/user/projects and summarize the repo structure.

Hermes 会发现该 MCP 服务器暴露的工具，并像使用原生工具一样调用它们。

两类 MCP 服务器

Stdio 服务器

Stdio 服务器以本地子进程形式运行，通过 stdin/stdout 通信：

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

适用于：

• MCP 服务器已安装在本地
• 需要低延迟访问本地资源
• 你所参考的 MCP 文档本来就使用 command、args、env

HTTP 服务器

HTTP MCP 服务器是远程端点，Hermes 会直接发起连接：

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

适用于：

• MCP 服务器部署在远端
• 组织内部已有 MCP 端点
• 你不希望 Hermes 为这类集成再拉起本地子进程

基础配置参考

Hermes 从 ~/.hermes/config.yaml 的 mcp_servers 读取配置。

常见键

Key	Type	Meaning
command	string	stdio MCP 服务器的可执行程序
args	list	stdio 服务器参数
env	mapping	传给 stdio 服务器的环境变量
url	string	HTTP MCP 端点
headers	mapping	远程服务器请求头
timeout	number	工具调用超时
connect_timeout	number	初始连接超时
enabled	bool	若为 false，Hermes 会完全跳过该服务器
tools	mapping	每服务器的工具过滤与 utility 策略

最小 stdio 示例

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

最小 HTTP 示例

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

Hermes 如何注册 MCP 工具

Hermes 会给 MCP 工具自动加前缀，以避免与内置工具冲突：

mcp_<server_name>_<tool_name>

例如：

Server	MCP tool	Registered name
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 辅助工具

当服务器支持时，Hermes 还会围绕 MCP resources 与 prompts 注册辅助工具：

• list_resources
• read_resource
• list_prompts
• get_prompt

它们也会按服务器加前缀，例如：

• mcp_github_list_resources
• mcp_github_get_prompt

Important

这些 utility 工具现在是 capability-aware 的：

• 只有 MCP 会话实际支持 resource 操作时，Hermes 才会注册 resource utilities
• 只有 MCP 会话实际支持 prompt 操作时，Hermes 才会注册 prompt utilities

因此，一个只暴露 callable tools、但不支持 resources/prompts 的服务器，不会得到这些额外包装工具。

按服务器过滤

你可以控制每台 MCP 服务器向 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: "***"
    tools:
      include: [create_issue, list_issues]

黑名单

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

优先级规则

如果同时配置了 include 和 exclude，则 include 优先。

同时过滤 utility tools

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

这表示：

• tools.resources: false 禁用 list_resources 与 read_resource
• tools.prompts: false 禁用 list_prompts 与 get_prompt

全部过滤后会怎样？

如果一个服务器的所有 callable tools 都被过滤掉，且所有 utility 也都被禁用或不存在，那么 Hermes 不会为空服务器创建一个空的运行时 MCP 工具集。

运行时行为

发现时机

Hermes 会在启动时发现 MCP 服务器，并把它们的工具注册进普通工具注册表。

动态工具发现

MCP 服务器可以通过发送 notifications/tools/list_changed 通知，告知 Hermes 其工具列表发生变化。收到该通知后，Hermes 会自动重新拉取工具列表并刷新注册表，无需手动 /reload-mcp。

重新加载

如果你修改了 MCP 配置，可执行：

/reload-mcp

工具集

当某个 MCP 服务器最终至少提供了一个已注册工具时，Hermes 还会为它创建一个运行时工具集：

mcp-<server>

安全模型

Stdio 环境变量过滤

对于 stdio 服务器，Hermes 不会把完整 shell 环境原样传递过去。默认只会透传显式配置的 env 加上一组安全基线环境变量，以减少意外泄露秘密信息的风险。

配置级暴露控制

工具过滤同样也是一种安全控制手段：

• 禁用危险工具
• 对敏感服务器只暴露最小白名单
• 在不希望暴露 resources/prompts 时禁用对应 utility

示例场景

最小 issue 管理面板的 GitHub server

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

移除危险动作的 Stripe server

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

单项目根目录的 filesystem server

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

故障排查

MCP server 无法连接

请检查：

cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
node --version
npx --version

然后检查配置并重启 Hermes。

工具没有出现

可能原因包括：

• 服务器连接失败
• 发现流程失败
• 过滤配置把工具排除了
• 该服务器根本不支持相应 utility
• 配置了 enabled: false

为什么没有出现 resource / prompt utilities？

因为只有在以下两项都满足时，Hermes 才会注册这些包装工具：

1. 你的配置允许它们
2. 服务器会话本身支持该 capability

MCP Sampling 支持

MCP 服务器可以通过 sampling/createMessage 协议向 Hermes 请求 LLM 推理，从而让 MCP 服务器在自己没有模型访问能力时，也能借助 Hermes 生成文本。

Sampling 默认对所有 MCP 服务器开启（前提是当前 MCP SDK 支持）。你可以按服务器配置：

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true
      model: "openai/gpt-4o"
      max_tokens_cap: 4096
      timeout: 30
      max_rpm: 10
      max_tool_rounds: 5
      allowed_models: []
      log_level: "info"

让 Hermes 自己充当 MCP 服务器

除了连接到 MCP 服务器之外，Hermes 也可以作为一个 MCP server 运行。这样其他支持 MCP 的智能体（如 Claude Code、Cursor、Codex 或任意 MCP 客户端）就可以使用 Hermes 的消息能力：列出会话、读取历史消息，以及跨所有已连接平台发送消息。

快速开始

hermes mcp serve

它会启动一个 stdio MCP server，进程生命周期由 MCP 客户端管理。

MCP client 配置

例如在 Claude Code 中：

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

可用工具

Hermes 作为 MCP server 时会暴露 10 个工具，包括：

• conversations_list
• conversation_get
• messages_read
• attachments_fetch
• events_poll
• events_wait
• messages_send
• channels_list
• permissions_list_open
• permissions_respond

事件系统

这个 MCP server 带有一个实时事件桥接层，会轮询 Hermes 的 session 数据库，以便向 MCP 客户端提供近实时的会话事件流。

当前限制

• 仅支持 stdio transport
• 通过优化过的数据库轮询实现约 200ms 级事件检查
• 还没有 claude/channel push notification 协议
• messages_send 目前仅支持文本发送，不支持媒体附件

相关文档

• Use MCP with Hermes
• CLI Commands
• Slash Commands
• FAQ