1. HoRain 云上 Hermes Agent 接 MCP，为什么 stdio 和 HTTP 要分开配
Hermes Agent 是 Nous Research 出的一个开源 Agent 框架，原生支持 MCP（Model Context Protocol）。MCP 是 Anthropic 提出的开放协议，用来标准化 LLM 和外部工具的交互——简单说，任何实现了 MCP 协议的服务，Hermes 都能直接接进来，不用为每个服务单独写适配代码。它适合谁？适合已经在 HoRain 云上跑 Hermes、想把 GitHub、文件系统、数据库、内部 API 这些工具链接进 Agent 工具调用链路的开发者。
但实际配的时候，很多人会卡在同一个地方：MCP 服务器有两种传输方式，stdio 和 HTTP，配置字段完全不一样，适用边界也不一样。stdio 是本地子进程，走 stdin/stdout 加 JSON-RPC；HTTP 是远程端点，走 HTTP 请求加 Bearer Token 或 OAuth。你在 HoRain 云环境里，如果本地工具和远程服务混着接，配置写错一个字段，Agent 就报工具不出现。
我试过在 HoRain 云主机上把这两条通道都跑通，踩过的坑主要集中在三块：一是 stdio 子进程的环境变量隔离，二是 HTTP 端点的认证头写法，三是工具过滤的命名规则。这篇就按可复制的配置骨架，把 stdio 和 HTTP 双通道拆开讲清楚，最后附连通性验证动作，让你在 HoRain 云上快速跑通 Hermes Agent 的工具调用链路。
2. 前置：TaoToken 统一 Key 与 API 通道准备
Hermes Agent 本身负责 MCP 客户端这一侧，但 Agent 背后调用的模型通道需要单独配。这里用 TaoToken 做统一 Key 和 API 通道，好处是一个 Key 走多个模型，不用在 Hermes 里为每个模型维护一套凭据。
TaoToken 的 API 地址是https://taotoken.net/api，注意这个地址不带任何查询参数。官网入口在https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，注册和拿 Key 都在控制台完成。
拿 Key 的路径是：进控制台，找到 API Keys 页面，新建一个 Key。这个 Key 后面会写进 Hermes 的模型配置里，同时 MCP 服务器如果需要访问模型侧能力，也可以复用同一个 Key 做统一鉴权。
注意：MCP 服务器自己的认证（比如 GitHub 的 PAT、Linear 的 OAuth）和 TaoToken 的 Key 是两回事。TaoToken Key 管的是模型通道，MCP 服务器的认证管的是工具通道，别混在一个 env 块里。
如果你后面要长期跑编码类 Agent 任务，可以看下 Coding Plan 页面，它针对高频编码场景做了额度优化。模型对话调试可以直接用模型对话页面验证通道是否通。接入文档在 doc 页面，API Keys 管理在 api-keys 页面。
3. 可复制配置：stdio 与 HTTP 双通道声明骨架
Hermes 的 MCP 配置统一写在~/.hermes/config.yaml的mcp_servers块下。下面这份骨架把 stdio 和 HTTP 两类服务器放在一起，你可以直接改路径和 Token 用。
3.1 stdio 通道：本地子进程配置
stdio 服务器以子进程形式在本地运行，Hermes 负责它的生命周期——会话启动或/reload-mcp时拉起子进程，会话结束或禁用时终止，崩溃自动重启最多 3 次。
# 文件路径：~/.hermes/config.yaml mcp_servers: # 文件系统服务器：限制 Agent 只能访问指定目录 filesystem: command: "npx" args: - "-y" - "@modelcontextprotocol/server-filesystem" - "/home/user/projects" # 只允许访问此目录 env: # stdio 子进程默认只继承 PATH/HOME/USER/LANG 等基础变量 # 其他变量必须在这里显式声明才会传入 NODE_OPTIONS: "--max-old-space-size=512" # Git 服务器：通过 uvx 启动，绑定到具体仓库 git: command: "uvx" args: - "mcp-server-git" - "--repository" - "/home/user/project" tools: include: - git_status - git_diff - git_log # 只注册这三个，git_push 等写操作不暴露stdio 的关键点是command加args的组合，以及env块的隔离机制。Hermes 默认只把PATH、HOME、USER、LANG、LC_ALL、TERM、SHELL、TMPDIR和所有XDG_*变量传给子进程，其他一律屏蔽。这意味着你在 Shell 里export的 Token，如果没在env:块里声明，MCP 子进程根本看不到。这个设计是为了防止恶意 MCP 服务器窃取你环境里的其他凭据。
3.2 HTTP 通道：远程端点配置
HTTP 服务器通过 HTTP 请求连远程 MCP 端点，支持静态 Bearer Token 和 OAuth 2.1 两种认证。
# 文件路径：~/.hermes/config.yaml mcp_servers: # 方式一：静态 Bearer Token，适合内部 API internal_api: url: "https://mcp.internal.example.com/mcp" headers: Authorization: "Bearer ${MY_INTERNAL_TOKEN}" # 支持环境变量插值 tools: exclude: - delete_record - drop_table # 排除高风险写操作，其余全部注册 # 方式二：OAuth 2.1，适合 Linear、Sentry 这类托管服务 linear: url: "https://mcp.linear.app/mcp" auth: oauth # 方式三：需要预注册 OAuth 客户端的提供商 googledrive: url: "https://drivemcp.googleapis.com/mcp/v1" auth: oauth oauth: client_id: "<your-oauth-client-id>" client_secret: "<your-oauth-client-secret>"HTTP 通道的关键点是url加headers或auth。headers里的${MY_INTERNAL_TOKEN}是环境变量插值，Hermes 启动时会从当前 Shell 环境读取。OAuth 类型的服务器需要先跑hermes mcp login <server>完成授权，授权窗口最长等 5 分钟。
3.3 两种通道的边界对照
| 维度 | stdio 服务器 | HTTP 服务器 |
|---|---|---|
| 运行位置 | 本机子进程 | 远程独立服务 |
| 通信方式 | stdin/stdout + JSON-RPC | HTTP 请求 |
| 生命周期 | Hermes 管理启停 | 独立于 Hermes |
| 延迟 | 极低（进程内通信） | 取决于网络延迟 |
| 认证 | 环境变量显式声明 | Bearer Token / OAuth 2.1 |
| 典型场景 | 本地 Git、文件系统、数据库 | GitHub API、Linear、Sentry |
| 配置复杂度 | 低（一行 command） | 中（URL + 认证） |
选型逻辑很简单：工具在本地、需要低延迟访问本地资源，用 stdio；工具在远端托管、或组织内部已有 MCP 接口，用 HTTP。HoRain 云主机上如果本地装了 Git 和文件系统工具，stdio 是首选；如果要接 Linear 这类 SaaS，HTTP 加 OAuth 是唯一选择。
4. 验证请求：连通性检查与成功结果
配置写完，别急着开 Agent 会话，先做三步验证。
第一步，列出所有已配置服务器，确认配置被正确加载：
hermes mcp list正常输出会列出每个服务器的名称、类型（stdio/HTTP）和状态。如果某个服务器没出现，说明 YAML 缩进或字段名写错了。
第二步，测试单个服务器连接：
hermes mcp test filesystemstdio 服务器会尝试拉起子进程并做一次 JSON-RPC 握手，成功返回类似connection ok, 3 tools discovered。HTTP 服务器会发一次探测请求，成功返回HTTP 200, tools: list_issues, create_issue。如果报command not found，检查command是否在 PATH 里；如果报401，检查Authorization头或 OAuth 是否已授权。
第三步，在 Agent 会话里重新加载 MCP 配置：
/reload-mcp这个命令在会话内生效，不用重启整个 Agent。加载完成后，Agent 的工具列表里应该能看到mcp-filesystem、mcp-git这类工具集。你可以直接问 Agent「列出当前可用的 MCP 工具」，它会返回注册成功的工具清单。
成功结果长这样：Agent 能调用git_status返回仓库状态，能调用list_issues返回 Linear 的 issue 列表，且错误信息里的 Token 被自动替换成[REDACTED]。Hermes 在把 MCP 工具错误返回给 LLM 前会自动脱敏，敏感信息不会明文出现在对话里。
5. 本篇常见错排查
MCP 工具不出现：最常见的原因是服务器没启用或连接失败。先跑hermes mcp list看状态，再跑hermes mcp test <name>测连接。stdio 服务器如果command不在 PATH 里，会静默失败。
工具过滤不生效：这是命名规则的坑。Hermes 注册后的工具名会把连字符转成下划线，但你在tools.include或tools.exclude里必须用 MCP 原始工具名，也就是带连字符的list-issues，不是list_issues。写错了过滤规则会被忽略，服务器暴露的所有工具都会注册。
stdio 服务器频繁崩溃：多半是依赖缺失或权限不足。手动在终端跑一遍command加args，看能不能正常启动。如果报EACCES，检查目标目录的读权限。
OAuth 授权超时：/reload-mcp的等待窗口只有 30 秒，不够完成 OAuth 浏览器授权。正确做法是先跑hermes mcp login <server>，在浏览器里完成授权，再跑/reload-mcp。
环境变量不生效：stdio 子进程只继承基础变量，你在 Shell 里export的 Token 不会自动传入。必须在mcp_servers.<name>.env块里显式声明。HTTP 服务器的headers里用${VAR}插值，同样要求变量在当前 Shell 环境里存在。
HTTP 服务器连接拒绝：检查 URL 是否可达、Authorization头格式是否正确。Bearer Token 的格式是Bearer <token>，中间一个空格，别漏了。
6. 接入通道与后续动作
排障和接入相关的操作，统一走 API Keys 页面管理 Key，接入文档在 doc 页面看完整字段说明。如果你要验证模型通道是否通，用模型对话页面直接发一条测试请求。长期跑编码类 Agent 任务，Coding Plan 页面有针对高频调用的额度方案。
HoRain 云上跑 Hermes Agent 接 MCP，核心就是把 stdio 和 HTTP 两条通道的配置字段分清：stdio 看command加args加env隔离，HTTP 看url加headers或auth。工具过滤记得用原始工具名，环境变量记得显式声明。配完跑一遍hermes mcp list和hermes mcp test，再/reload-mcp，工具链路就通了。