Skip to main content

MCP（模型上下文协议）

MCP 使 Hermes Agent 能够连接到外部工具服务器，从而让代理使用存在于 Hermes 之外的工具——例如 GitHub、数据库、文件系统、浏览器堆栈、内部 API 等。

如果你曾希望 Hermes 能使用某个已存在的外部工具，MCP 通常是实现这一目标最清晰的方式。

MCP 提供的能力​

  • 无需先编写原生 Hermes 工具即可访问外部工具生态
  • 支持本地 stdio 服务器与远程 HTTP MCP 服务器共存于同一配置中
  • 启动时自动发现并注册工具
  • 当服务器支持时，提供对 MCP 资源和提示的实用封装
  • 按服务器进行过滤，仅向 Hermes 暴露你真正希望它使用的 MCP 工具

快速入门​

  1. 安装 MCP 支持（如使用标准安装脚本，则已包含）：
cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"
  1. 在 ~/.hermes/config.yaml 中添加一个 MCP 服务器：
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
  1. 启动 Hermes：
hermes chat
  1. 让 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: "***"

使用 stdio 服务器的场景包括：

  • 服务器已本地安装
  • 需要低延迟访问本地资源
  • 正在遵循文档中展示 command、args 和 env 的 MCP 服务器指南

HTTP 服务器​

HTTP MCP 服务器是 Hermes 可直接连接的远程端点。

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

使用 HTTP 服务器的场景包括：

  • MCP 服务器部署在其他位置
  • 你的组织提供了内部 MCP 端点
  • 不希望 Hermes 为该集成启动本地子进程

基础配置参考​

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

常用配置项​

键类型含义
command字符串stdio MCP 服务器的可执行文件路径
args列表传递给 stdio 服务器的参数
env映射传递给 stdio 服务器的环境变量
url字符串HTTP MCP 服务端点地址
headers映射连接远程服务器时使用的 HTTP 头信息
timeout数字工具调用超时时间（秒）
connect_timeout数字初始连接超时时间（秒）
enabled布尔值若为 true，Hermes 将完全跳过该服务器
tools映射每个服务器的工具过滤规则与实用策略

最小化 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>

示例：

服务器MCP 工具注册名称
filesystemread_filemcp_filesystem_read_file
githubcreate-issuemcp_github_create_issue
my-apiquery.datamcp_my_api_query_data

实际上，你通常无需手动调用带前缀的名称——Hermes 会在正常推理过程中自动识别并选择这些工具。

MCP 实用工具​

当服务器支持时，Hermes 还会注册围绕 MCP 资源和提示的实用工具：

  • list_resources
  • read_resource
  • list_prompts
  • get_prompt

这些工具按服务器注册，采用相同的前缀模式，例如：

  • mcp_github_list_resources
  • mcp_github_get_prompt

重要说明​

这些实用工具现在具备能力感知功能：

  • 仅当 MCP 会话确实支持资源操作时，Hermes 才会注册资源相关工具
  • 仅当 MCP 会话确实支持提示操作时，Hermes 才会注册提示相关工具

因此，一个只暴露可调用工具但不支持资源或提示的服务器，不会获得这些额外封装。

按服务器过滤​

你可以控制每个 MCP 服务器向 Hermes 贡献哪些工具，实现对工具命名空间的精细管理。

完全禁用某个服务器​

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

若设置为 true，Hermes 将完全跳过该服务器，甚至不会尝试建立连接。

白名单工具（仅允许特定工具）​

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]

注册所有工具，但排除列表中的项目。

优先级规则​

如果两者同时存在：

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

include 优先级更高。

也可单独禁用实用工具​

你还可以独立禁用 Hermes 添加的实用封装：

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

完整示例​

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

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

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

如果所有工具都被过滤掉了怎么办？​

如果配置过滤掉所有可调用工具，并且禁用了所有支持的实用工具，Hermes 不会为该服务器创建空的运行时 MCP 工具集。

这有助于保持工具列表的简洁。

运行时行为​

发现阶段​

Hermes 在启动时发现 MCP 服务器，并将其工具注册到常规工具注册表中。

动态工具发现​

MCP 服务器可通过发送 notifications/tools/list_changed 通知来告知 Hermes 其可用工具在运行时发生变化。当 Hermes 接收到此通知时，会自动重新获取服务器的工具列表并更新注册表——无需手动 /reload-mcp。

这对于能力动态变化的 MCP 服务器非常有用（例如：新数据库模式加载后新增工具，或服务离线时移除工具）。

刷新操作受锁保护，防止同一服务器频繁发送通知导致重叠刷新。提示和资源变更通知（prompts/list_changed、resources/list_changed）会被接收，但暂不处理。

重新加载​

若更改了 MCP 配置，请使用：

/reload-mcp

这将从配置中重新加载 MCP 服务器，并刷新可用工具列表。对于由服务器自身推送的运行时工具变更，请参见上方 动态工具发现。

工具集​

每个配置的 MCP 服务器在至少贡献一个注册工具时，也会创建一个运行时工具集：

mcp-<server>

这使得在工具集层面更易于理解和管理 MCP 服务器。

安全模型​

Stdio 环境变量过滤​

对于 stdio 服务器，Hermes 不会盲目传递完整的 shell 环境。

仅传递显式配置的 env 加上一个安全基线环境。这有助于减少意外凭据泄露的风险。

配置级别的暴露控制​

新的过滤功能本身也是一种安全控制：

  • 禁用你不希望模型看到的危险工具
  • 为敏感服务器仅暴露最小白名单
  • 当不需要暴露该表面时，禁用资源/提示封装

示例应用场景​

仅提供最小化问题管理功能的 GitHub 服务器​

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

使用方式如下：

Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.

移除了危险操作的 Stripe 服务器​

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

使用方式如下：

Look up the last 10 failed payments and summarize common failure reasons.

仅针对单个项目根目录的文件系统服务器​

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

使用方式如下：

Inspect the project root and explain the directory layout.

故障排查​

MCP 服务器无法连接​

请检查：

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

然后验证配置并重启 Hermes。

工具未出现​

可能原因包括：

  • 服务器连接失败
  • 发现过程失败
  • 你的过滤配置排除了这些工具
  • 该服务器不支持所需的功能（资源或提示）
  • 服务器因 enabled: false 被禁用

如果你有意进行过滤，这是预期行为。

为什么没有出现资源或提示实用工具？​

因为 Hermes 现在仅在以下两个条件同时满足时才注册这些封装：

  1. 你的配置允许注册
  2. 服务器会话确实支持该能力

这是有意为之的设计，确保工具列表真实可信。

MCP 采样支持​

MCP 服务器可通过 sampling/createMessage 协议请求 Hermes 进行 LLM 推理。这使得 MCP 服务器能够要求 Hermes 代为生成文本——对那些需要 LLM 能力但自身无模型访问权限的服务器非常有用。采样功能对所有 MCP 服务器默认启用（只要 MCP SDK 支持）。可通过在每个服务器的配置中设置 sampling 键来单独配置：

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # Enable sampling (default: true)
      model: "openai/gpt-4o"  # Override model for sampling requests (optional)
      max_tokens_cap: 4096     # Max tokens per sampling response (default: 4096)
      timeout: 30              # Timeout in seconds per request (default: 30)
      max_rpm: 10              # Rate limit: max requests per minute (default: 10)
      max_tool_rounds: 5       # Max tool-use rounds in sampling loops (default: 5)
      allowed_models: []       # Allowlist of model names the server may request (empty = any)
      log_level: "info"        # Audit log level: debug, info, or warning (default: info)

采样处理器包含滑动窗口速率限制、每请求超时时间以及工具循环深度限制，以防止资源滥用。每个服务器实例都会记录请求次数、错误数和使用的 token 数量等指标。

如需禁用某个特定服务器的采样功能：

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

作为 MCP 服务器运行 Hermes​

除了连接到 MCP 服务器外，Hermes 本身也可以成为一个 MCP 服务器。这使得其他具备 MCP 能力的代理（如 Claude Code、Cursor、Codex 或任意 MCP 客户端）能够使用 Hermes 的消息功能——列出对话、读取消息历史，并跨所有已连接平台发送消息。

何时使用此功能​

  • 你希望 Claude Code、Cursor 或其他编程代理通过 Hermes 发送和接收 Telegram/Discord/Slack 消息
  • 你希望有一个统一的 MCP 服务器，一次性桥接 Hermes 所有已连接的消息平台
  • 你已经运行了一个带有已连接平台的 Hermes 网关

快速入门​

hermes mcp serve

这将启动一个基于 stdio 的 MCP 服务器。MCP 客户端（而非你）负责管理进程生命周期。

MCP 客户端配置​

将 Hermes 添加到你的 MCP 客户端配置中。例如，在 Claude Code 的 ~/.claude/claude_desktop_config.json 中：

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

或者如果你将 Hermes 安装在特定路径下：

{
  "mcpServers": {
    "hermes": {
      "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

可用工具​

该 MCP 服务器暴露了 10 个工具，与 OpenClaw 的频道桥接接口一致，并额外提供一个 Hermes 特有的频道浏览器：

工具描述
conversations_list列出当前活跃的消息对话。可按平台筛选或按名称搜索。
conversation_get通过会话键获取某个对话的详细信息。
messages_read获取某个对话的最近消息历史。
attachments_fetch从指定消息中提取非文本附件（如图片、媒体文件）。
events_poll从某个游标位置开始轮询自上次以来的新对话事件。
messages_send长轮询 / 阻塞等待下一个事件到达（近实时）。
telegram:123456通过某个平台发送消息（例如 discord:#general、channels_list）。
permissions_list_open列出所有平台上可用的消息目标。
permissions_respond列出当前桥接会话期间观察到的所有待审批请求。
message允许或拒绝一个待处理的审批请求。

事件系统​

MCP 服务器内置了实时事件桥接机制，会定期轮询 Hermes 的会话数据库以获取新消息。这使 MCP 客户端能近乎实时地感知到新对话的到来：

# Poll for new events (non-blocking)
events_poll(after_cursor=0)

# Wait for next event (blocks up to timeout)
events_wait(after_cursor=42, timeout_ms=30000)

事件类型：message、approval_requested、approval_resolved

事件队列为内存中存储，当桥接连接建立后即开始运行。较旧的消息可通过 messages_read 获取。

选项​

hermes mcp serve              # Normal mode
hermes mcp serve --verbose    # Debug logging on stderr

工作原理​

MCP 服务器直接从 Hermes 的会话存储（~/.hermes/sessions/sessions.json 和 SQLite 数据库）读取对话数据。后台线程会轮询数据库以检测新消息，并维护一个内存中的事件队列。发送消息时，它使用与 Hermes 代理自身相同的 send_message 基础设施。

对于读操作（如列出对话、读取历史、轮询事件），网关无需运行。但若要执行发送操作，则必须运行网关，因为平台适配器需要保持活跃连接。

当前限制​

  • 仅支持 stdio 传输（尚未支持 HTTP MCP 传输）
  • 事件轮询间隔约为 200ms，通过 mtime 优化的数据库轮询实现（文件未变更时跳过工作）
  • 尚未支持 claude/channel 推送通知协议
  • 仅支持纯文本发送（无法通过 messages_send 发送媒体或附件）

相关文档​