用 MCP 管理 Hermes Cloud

本页的 Python 依赖命令使用一份由 PM 准备的源码 checkout。依赖变更后，重新激活该 checkout 并重启 Hermes。

Hermes Cloud 为你托管 Hermes Agent 实例。通常你在 Nous Portal 的 /agents 页面管理它们。本指南把你的本地 Hermes Agent 连到 Portal 的 MCP 服务器，让你只需开口——"列出我的云端智能体"、"重启那个停掉的"、"它花了我多少钱"——就能管理这些云实例，而无需离开终端。

它是 Nous Research 托管的一个标准 MCP 服务器，用你登录 Portal 时同一套 OAuth 登录把关。连接后，Hermes 获得两个可代你调用的工具。

你能用它做什么 {#what-you-can-do-with-it}

连接后，模型可在你的 Hermes Cloud 组织上调用：

你这么说……背后动作
"列出我的云端智能体"agents（list）
"<name> 现在状态如何？"agents（get / status）
"这个实例大概花多少钱？"agents（cost_estimate）
"启动 / 停止 / 重启 <name>"agent（start / stop / restart）
"起一个叫 <name> 的新实例"agent（create）
"销毁 <name>"agent（destroy）
"更新 <name> 上的 env / 镜像"agent（update_env / update_image）

每次调用都以你的 Portal 身份在你的组织上执行，且每次调用都会重新校验成员资格——该连接只能触碰你在网页 UI 上已经控制的实例。

前置条件 {#prerequisites}

  • 一个 Nous Portal 账号，且有 Hermes Cloud 访问权（至少一个实例，或能创建一个）。

  • 已安装 MCP 支持。若你用的是标准安装脚本，它已就位；否则：

    cd ~/.hermes/hermes-agent
python -c "import pm; pm.sync_venv(['mcp'], explicit=True)"

你不需要单独的 API key 或 client secret——服务器用 PKCE OAuth，登录是一次浏览器往返。

第 1 步：添加服务器 {#step-1-add-the-server}

hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud

--auth oauth 告诉 Hermes 这是一个受 OAuth 保护的 HTTP 服务器。首次连接时 Hermes：

  1. 自动发现服务器的 OAuth 端点（RFC 9728 / 8414 元数据）。
  2. 把自己注册为客户端（RFC 7591 动态客户端注册）——没有 secret 要复制。
  3. 在浏览器打开 Portal 让你登录并授权。
  4. 把得到的令牌存在 ~/.hermes/mcp-tokens/ 并复用（自动刷新）。

选择组织 {#choosing-an-organization}

若你的 Portal 账号属于多个组织，授权期间浏览器会显示一个组织选择器——选这个连接应管理哪个组织。选择在浏览器里做一次；命令行无需传任何东西。单组织账号跳过这一步并自动绑定。

若你日后需要把连接指向另一个组织，移除再重新添加服务器（hermes mcp remove hermes-cloud，再跑一次 add 命令），在浏览器里选另一个组织。

第 2 步：验证连接 {#step-2-verify-it-connected}

hermes mcp test hermes-cloud

然后启动（或重载）一次会话：

hermes chat

/reload-mcp

问一个只读问题确认工具已上线：

列出我的 Hermes Cloud 智能体及其当前状态。

你应得到与 Portal /agents 页面上相同的实例。

第 3 步：使用 {#step-3-use-it}

只读问题总是安全的：

我的云端智能体现在哪些在运行，每个大概花多少钱？

生命周期动作对应直白请求：

重启叫 research-bot 的实例。

创建一个叫 scratch 的新 Hermes Cloud 实例，好了告诉我。

Hermes 会报告每个工具返回了什么——实例列表、新状态、新建实例的详情——让你确认动作已落地。

配置 {#configuration}

hermes mcp add 后，服务器位于 ~/.hermes/config.yaml：

mcp_servers:
  hermes-cloud:
    url: "https://portal.nousresearch.com/mcp"
    auth: oauth

config.yaml 里不放任何凭据——OAuth 令牌单独保存在 ~/.hermes/mcp-tokens/，与 Portal refresh token 不进配置同理。

限制工具面 {#limiting-the-tool-surface}

服务器同时暴露只读（agents）和变更（agent）工具。若你希望该连接只读——列出和查看，但绝不启动/停止/创建/销毁——把它限制到 agents 工具：

mcp_servers:
  hermes-cloud:
    url: "https://portal.nousresearch.com/mcp"
    auth: oauth
    tools:
      include: [agents]

改完配置后运行 /reload-mcp。完整过滤模型（include/exclude、prompts、resources）见在 Hermes 中使用 MCP。

故障排查 {#troubleshooting}

浏览器显示组织选择器，我不确定选哪个

你属于多个 Portal 组织。选你想从这个连接管理其 Hermes Cloud 实例的那个组织。若不确定，就是拥有你在 Portal /agents 页面上看到的实例的那个组织。日后可通过移除再添加服务器重新选择。

连接时报 "invalid_client" 或 "unknown client"

存储的客户端注册已与服务器不匹配（例如你之前连过另一个环境）。清掉该服务器缓存的 OAuth 状态再重新添加：

hermes mcp remove hermes-cloud
rm -f ~/.hermes/mcp-tokens/hermes-cloud.*
hermes mcp add --url https://portal.nousresearch.com/mcp --auth oauth hermes-cloud

添加服务器后工具没出现

在会话内重载 MCP 再检查：

/reload-mcp

告诉我现在有哪些 MCP 后端工具可用。

若仍缺失，运行 hermes mcp test hermes-cloud 直接看连接错误。

它又让我登录

OAuth 令牌自动刷新，但若 Portal 使你的会话失效（改密码、吊销、过期），下一次调用会请你重新授权。重跑 hermes mcp add 命令——浏览器流程会重新铸造令牌。

无头 / SSH / 远程主机 {#headless--ssh--remote-host}

OAuth 浏览器回调跑在 Hermes 所在的机器上。在远程主机上，经 SSH 转发 loopback 端口——与任何其他 OAuth 登录相同的模式。见经 SSH / 远程主机的 OAuth。

另见 {#see-also}