MCP 协议

MCP（Model Context Protocol）让 Hermes Agent 能够连接到外部工具服务器，使 Agent 可以使用存在于 Hermes 本身之外的工具 - GitHub、数据库、文件系统、浏览器堆栈、内部 API 等等。

功能概述

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

MCP 提供的功能

• 访问外部工具生态系统 - 无需先编写原生 Hermes 工具
• 同时支持本地和远程 - 本地 stdio 服务器和远程 HTTP MCP 服务器在同一配置中
• 自动工具发现和注册 - 启动时自动完成
• MCP 资源和提示的实用包装器 - 当服务器支持时
• 按服务器过滤 - 精确控制暴露给 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 会看到工具并在正常推理过程中选择它。

配置方法

快速开始

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 支持的功能：

列出 /home/user/projects 中的文件并总结仓库结构。

两种 MCP 服务器类型

Stdio 服务器

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

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

使用场景：

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

HTTP 服务器

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

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

使用场景：

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

OAuth 认证的 HTTP 服务器

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

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

首次连接时，Hermes 会打印授权 URL，尽可能打开浏览器，并在本地回环端口等待 OAuth 回调。令牌缓存在 ~/.hermes/mcp-tokens/<server>.json。

远程/无头主机：当 Hermes 在与浏览器不同的机器上运行时，有两种方式完成流程：

• 粘贴回传（无需设置）：在交互式终端上，Hermes 会打印”或将重定向 URL 粘贴到这里…”以及授权 URL。在浏览器中打开 URL，批准，复制浏览器最终到达的完整 URL（重定向会显示连接错误 - 这是预期的），将其粘贴到提示符。裸 ?code=…&state=… 查询字符串也可以。

• SSH 端口转发：ssh -N -L <port>:127.0.0.1:<port> user@host，然后让重定向流程正常进行。

目录：一键安装 Nous 批准的 MCP

Hermes 附带一个精选的 MCP 服务器目录，由 Nous 员工审核和合并。默认禁用 - 只安装你实际需要的。

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

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

n8n available      从 Hermes 管理和检查 n8n 工作流
linear enabled     Linear 问题/项目管理（远程 OAuth）
github installed (disabled) GitHub 仓库 + PR 工具

按 Enter 安装（并引导完成任何必需的凭证）、启用、禁用或卸载。

基本配置参考

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_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

提示：

检查此项目并总结仓库布局。

GitHub 集成

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

提示：

列出关于 MCP 的开放问题，按主题聚类，并为最常见的错误起草一个高质量的问题。

内部 API 助手

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

提示：

查找客户 ACME Corp 并总结最近的发票活动。

多服务器工作流

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

提示：

检查本地项目文件，然后创建一个 GitHub issue 总结你发现的错误。

WSL2 桥接到 Windows Chrome

当 Hermes 在 WSL2 中运行而浏览器在 Windows 上时：

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

然后：

调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。

最佳实践

按服务器过滤

白名单服务器工具

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 获胜。

禁用实用工具

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

安全建议

1. 为危险系统使用白名单 - 对于任何财务、面向客户或破坏性的系统，使用 tools.include 并尽可能从最小的集合开始

2. 禁用未使用的实用程序 - 如果你不希望模型浏览服务器提供的资源/提示，关闭它们：

tools:
  resources: false
  prompts: false

3. 保持服务器范围狭窄 - 示例：

   • 文件系统服务器根目录限制在一个项目目录，而不是整个主目录
   • Git 服务器指向一个仓库
   • 内部 API 服务器默认暴露读取为主的工具

4. 配置更改后重新加载 - 更改 include/exclude 列表、enabled 标志、resources/prompts 切换、认证头后运行 /reload-mcp

运行时行为

发现时间

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

动态工具发现

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

重新加载

如果更改 MCP 配置，使用：

/reload-mcp

这会从配置重新加载 MCP 服务器并刷新可用工具列表。

工具集

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

mcp-<server>

这使 MCP 服务器在工具集级别更容易推理。

故障排除

症状	可能原因	解决方案
服务器连接但预期工具缺失	被 tools.include 过滤	检查 include/exclude 列表
服务器已配置但无内容加载	enabled: false	检查配置中的 enabled 标志
看到的工具比 MCP 服务器宣传的少	按服务器策略过滤	这是预期的，通常可取
如何在不删除配置的情况下移除 MCP 服务器？	使用 enabled: false	保留配置但阻止连接和注册

推荐的首个 MCP 设置

适合大多数用户的好的首个服务器：

• filesystem
• git
• GitHub
• fetch / 文档 MCP 服务器
• 一个狭窄的内部 API

不太好的首个服务器：

• 具有许多破坏性操作且无法过滤的大型业务系统
• 你不够了解以至于无法约束的任何内容

何时使用 MCP

使用 MCP 当：

• 工具已经以 MCP 形式存在，你不想构建原生 Hermes 工具
• 你希望 Hermes 通过干净的 RPC 层操作本地或远程系统
• 你想要细粒度的每服务器暴露控制
• 你想在不修改 Hermes 核心的情况下将 Hermes 连接到内部 API、数据库或公司系统

不要使用 MCP 当：

• 内置 Hermes 工具已经很好地解决了工作
• 服务器暴露巨大的危险工具表面且你没有准备过滤它
• 你只需要一个非常狭窄的集成，原生工具会更简单更安全