MCP 协议

MCP 让 Hermes Agent 能够连接到外部工具服务器，使 Agent 可以使用位于 Hermes 本身之外的工具——GitHub、数据库、文件系统、浏览器栈、内部 API 等。

如果你曾经希望 Hermes 使用某个已经存在于别处的工具，MCP 通常是最干净的方式。

MCP 的价值

无需先编写原生 Hermes 工具即可访问外部工具生态
本地 stdio 服务器和远程 HTTP MCP 服务器在同一配置中
启动时自动工具发现和注册
当服务器支持时，MCP 资源和提示的实用包装器
按服务器过滤，只暴露你真正希望 Hermes 看到的 MCP 工具

快速开始

安装 MCP 支持（如果使用标准安装脚本则已包含）：

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

添加 MCP 服务器到 ~/.hermes/config.yaml：

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

启动 Hermes：

hermes chat

然后让 Hermes 使用 MCP 支持的能力：

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

Hermes 会发现 MCP 服务器的工具，并像使用其他任何工具一样使用它们。

目录安装

Hermes 附带一个经过 Nous 审核的 MCP 服务器精选目录。它们默认禁用——只安装你真正需要的。

hermes mcp            # 交互式选择器（默认）
hermes mcp catalog    # 纯文本列表，可脚本化
hermes mcp install n8n  # 按名称安装目录条目

选择器显示每个条目的当前状态：

n8n              available  Manage and inspect n8n workflows from Hermes
linear            enabled     Linear issue/project management (remote OAuth)
github            installed (disabled)  GitHub repo + PR tools

在行上按 Enter 来安装（并逐步完成所需的凭据），或启用、禁用、卸载。目录条目存储在 hermes-agent 仓库的 optional-mcps/ 下——该目录中的存在即表示 Nous 已审核。没有社区提交层级；条目通过合并 PR 添加。

安装时工具选择

配置凭据后，Hermes 探测 MCP 服务器以列出其暴露的每个工具，并呈现一个清单：

Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues        Find issues matching a query
  [x] get_issue          Get a single issue
  [x] create_issue       Create a new issue
  [ ] delete_workspace   Delete a Linear workspace
  ...

预勾选的行来自：

你之前的选择（如果之前安装过此条目——重新安装保留你的设置，清单的默认值不会覆盖它）
清单的 tools.default_enabled（如果条目声明了一个——某些目录条目会预修剪可变或很少有用的工具）
如果两者都不适用，则全选

用 ENTER 提交清单。只有勾选的工具最终会出现在 mcp_servers.<name>.tools.include 中。如果你全选，则不写入过滤器（最干净的配置形状，行为相同）。

如果探测失败（服务器不可达、OAuth 尚未完成、后端服务未运行），安装仍然成功：清单的 tools.default_enabled 被直接应用（如果声明了），或者如果不声明则写入无过滤器。服务器可达后，重新运行 hermes mcp configure <name> 来优化。

两种 MCP 服务器

Stdio 服务器

Stdio 服务器作为本地子进程运行，通过 stdin/stdout 通信。

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

使用 stdio 服务器的场景：

服务器安装在本地
需要低延迟访问本地资源
你正在按照 MCP 服务器文档中显示的 command、args 和 env 操作

HTTP 服务器

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

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

使用 HTTP 服务器的场景：

MCP 服务器托管在其他地方
你的组织暴露内部 MCP 端点
你不希望 Hermes 为该集成生成本地子进程

OAuth 认证的 HTTP 服务器

大多数托管的 MCP 服务器（Linear、Sentry、Atlassian、Asana、Figma、Stripe 等）需要 OAuth 2.1 而非静态 bearer token。设置 auth: oauth，Hermes 会处理发现、动态客户端注册、PKCE、令牌交换、刷新和通过 MCP Python SDK 的逐步认证。

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

首次连接时，Hermes 打印授权 URL，在可能时打开浏览器，并在本地 loopback 端口上等待 OAuth 回调。令牌缓存在 ~/.hermes/mcp-tokens/<server>.json，权限为 0o600；后续运行静默重用它们，直到刷新失败。

远程/无头主机：当 Hermes 在与浏览器不同的机器上运行时，loopback 回调可能无法到达你的笔记本。两种完成流程的方法：

粘贴返回（无需设置）：在交互式终端上，Hermes 在授权 URL 旁边打印 “Or paste the redirect URL here…”。在浏览器中打开 URL，批准，复制浏览器最终到达的完整 URL（重定向将显示连接错误——这是预期的），在提示符处粘贴它。?code=...&state=... 裸查询字符串也有效。
SSH 端口转发：在单独的终端中 ssh -N -L :127.0.0.1: user@host，然后让重定向流程正常进行。

配置参考

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

常用键

键	类型	含义
`command`	string	Stdio MCP 服务器的可执行文件
`args`	list	Stdio 服务器的参数
`env`	mapping	传递给 stdio 服务器的环境变量
`url`	string	HTTP MCP 端点
`headers`	mapping	远程服务器的 HTTP 头
`timeout`	number	工具调用超时
`connect_timeout`	number	初始连接超时
`enabled`	bool	如果 false，Hermes 完全跳过服务器
`supports_parallel_tool_calls`	bool	如果 true，来自此服务器的工具可能并发运行
`tools`	mapping	按服务器工具过滤和实用策略

最小 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 标志，填入传输详细信息，这样你就不必查找 command 和 args。预设只提供默认值——你在同一命令行上传递的任何其他内容（env 变量、headers、过滤）仍然优先。

预设	连接方式
`codex`	Codex CLI 的 MCP 服务器（`codex mcp-server` over 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 工具	注册名称
`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 资源和提示注册实用工具：

list_resources
read_resource
list_prompts
get_prompt

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

mcp_github_list_resources
mcp_github_get_prompt

按服务器过滤

你可以控制每个 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

安全模型

Stdio 环境变量过滤

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

只传递显式配置的环境变量加上安全基线。这减少了意外的秘密泄露。

配置级暴露控制

新的过滤支持也是一种安全控制：

禁用你不想让模型看到的危险工具
为敏感服务器暴露最小白名单
当你不想暴露该表面时，禁用资源/提示包装器

并行工具调用

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

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

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

动态工具发现

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

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

刷新是锁保护的，因此来自同一服务器的快速触发通知不会导致重叠刷新。提示和资源变更通知（prompts/list_changed、resources/list_changed）被接收但尚未处理。

故障排除

MCP 服务器无法连接

检查：

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

node --version
npx --version

然后验证你的配置并重新启动 Hermes。

工具未出现

可能的原因：

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

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

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

因为 Hermes 现在只在这些都为真时注册这些包装器：

你的配置允许它们
服务器会话实际支持该能力

这是有意的，并保持工具列表的诚实。