好奇心花园🪴

搜索

SearchSearch

最近的笔记

MCP（模型上下文协议）

2026年5月24日18分钟阅读

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 配置。

通用键

键类型含义
commandstringstdio MCP 服务器的可执行文件
argsliststdio 服务器的参数
envmapping传递给 stdio 服务器的环境变量
urlstringHTTP MCP 端点
headersmapping远程服务器的 HTTP 头
timeoutnumber工具调用超时
connect_timeoutnumber初始连接超时
enabledbool如果为 false，Hermes 完全跳过该服务器
supports_parallel_tool_callsbool如果为 true，此服务器的工具可能并发运行
toolsmapping每服务器工具过滤和实用策略

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

内置预设

对于知名的 MCP 服务器，hermes mcp add 接受 --preset 标志，填写传输细节，这样您就不必查找命令和参数。预设只提供默认值——您在同一个命令行上传递的其他任何内容（环境变量、头信息、过滤）仍然优先。

预设连接内容
codexCodex CLI 的 MCP 服务器（codex mcp-server 通过 stdio）。需要在 PATH 上有 codex CLI
# 一行添加 Codex CLI 作为 MCP 服务器
hermes mcp add codex --preset codex

这写入相当于：

mcp_servers:
  codex:
    command: "codex"
    args: ["mcp-server"]

您可以选择任何本地名称（hermes mcp add my-codex --preset codex 没问题）；预设只提供 command/args 默认值。

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

如果 enabled: false，Hermes 完全跳过该服务器，甚至不尝试连接。

白名单服务器工具

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

仅注册这些 MCP 服务器工具。

黑名单服务器工具

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 env 过滤

对于 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 服务器无法连接

检查：

# 验证 MCP 依赖已安装（已包含在标准安装中）
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"
 
node --version
npx --version

然后验证您的配置并重启 Hermes。

工具未出现

可能的原因：

  • 服务器连接失败
  • 发现失败
  • 您的过滤器配置排除了这些工具
  • 该服务器上不存在该实用能力
  • 服务器已用 enabled: false 禁用

如果您有意过滤，这是预期的。

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

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

  1. 您的配置允许它们
  2. 服务器会话实际支持该能力

这是有意为之，并使工具列表保持诚实。

并行工具调用

默认情况下，MCP 工具顺序运行——一次一个。如果您的 MCP 服务器暴露了可以安全并发运行的工具（例如，只读查询、独立的 API 调用），您可以选择并行执行：

mcp_servers:
  docs:
    command: "docs-server"
    supports_parallel_tool_calls: true

当 supports_parallel_tool_calls 为 true 时，Hermes 可能会在单个工具调用批次中同时执行该服务器的多个工具，就像它对内置只读工具（web_search、read_file 等）所做的那样。

:::caution 仅为工具安全同时运行的 MCP 服务器启用并行调用。如果工具读写共享状态、文件、数据库或外部资源，请在启用此设置前审查读/写竞争条件。 :::

MCP 采样支持

MCP 服务器可以通过 sampling/createMessage 协议请求 Hermes 进行 LLM 推理。这允许 MCP 服务器请 Hermes 代其生成文本——对于需要 LLM 能力但没有自己模型访问权限的服务器很有用。

采样默认对所有 MCP 服务器启用（当 MCP SDK 支持时）。在 sampling 键下按服务器配置：

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # 启用采样（默认：true）
      model: "openai/gpt-4o"  # 覆盖采样请求的模型（可选）
      max_tokens_cap: 4096     # 每次采样响应的最大令牌数（默认：4096）
      timeout: 30              # 每请求超时秒数（默认：30）
      max_rpm: 10              # 速率限制：每分钟最大请求数（默认：10）
      max_tool_rounds: 5       # 采样循环中的最大工具使用轮数（默认：5）
      allowed_models: []       # 服务器可请求的模型名称白名单（空 = 任意）
      log_level: "info"        # 审计日志级别：debug、info 或 warning（默认：info）

采样处理程序包括滑动窗口速率限制器、每请求超时和工具循环深度限制，以防止失控使用。指标（请求计数、错误、使用的令牌）按服务器实例跟踪。

要为特定服务器禁用采样：

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

将 Hermes 作为 MCP 服务器运行

除了连接到 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自光标位置以来轮询新对话事件
events_wait长轮询/阻塞直到下一个事件到达（近实时）
messages_send通过平台发送消息（例如 telegram:123456、discord:#general）
channels_list列出所有平台上的可用消息目标
permissions_list_open列出此桥接会话期间观察到的待处理审批请求
permissions_respond允许或拒绝待处理的审批请求

事件系统

MCP 服务器包括一个实时事件桥，轮询 Hermes 的会话数据库以获取新消息。这为 MCP 客户端提供了近实时的传入对话感知：

# 轮询新事件（非阻塞）
events_poll(after_cursor=0)

# 等待下一个事件（最多阻塞到超时）
events_wait(after_cursor=42, timeout_ms=30000)

事件类型：message、approval_requested、approval_resolved

事件队列在内存中，在桥接连接时启动。较早的消息可通过 messages_read 获取。

选项

hermes mcp serve              # 正常模式
hermes mcp serve --verbose    # stderr 上的调试日志

工作原理

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

网关不需要运行以进行读操作（列出对话、读取历史、轮询事件）。它确实需要运行以进行发送操作，因为平台适配器需要活动连接。

当前限制

  • 内嵌的 hermes mcp serve 今天暴露一个仅 stdio 的 MCP 服务器。如果您需要 HTTP MCP 服务器，请运行一个单独的适配器——或者更常见的是，使用 Hermes 的 MCP 客户端端，它已经支持 stdio 和 HTTP（mcp_servers.yaml / config.yaml 中的 url + headers；参见上面的HTTP 服务器）
  • 事件轮询间隔约 200ms，通过 mtime 优化的数据库轮询（文件未更改时跳过工作）
  • 尚无 claude/channel 推送通知协议
  • 仅文本发送（通过 messages_send 无媒体/附件发送）

相关文档

关系图谱

反向链接