HoRain云 Hermes Agent 集成 MCP：stdio 与 HTTP 双通道配置实战

1. HoRain 云上 Hermes Agent 接 MCP为什么 stdio 和 HTTP 要分开配Hermes Agent 是 Nous Research 出的一个开源 Agent 框架原生支持 MCPModel Context Protocol。MCP 是 Anthropic 提出的开放协议用来标准化 LLM 和外部工具的交互——简单说任何实现了 MCP 协议的服务Hermes 都能直接接进来不用为每个服务单独写适配代码。它适合谁适合已经在 HoRain 云上跑 Hermes、想把 GitHub、文件系统、数据库、内部 API 这些工具链接进 Agent 工具调用链路的开发者。但实际配的时候很多人会卡在同一个地方MCP 服务器有两种传输方式stdio 和 HTTP配置字段完全不一样适用边界也不一样。stdio 是本地子进程走 stdin/stdout 加 JSON-RPCHTTP 是远程端点走 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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-size512 # 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-secretHTTP 通道的关键点是url加headers或auth。headers里的${MY_INTERNAL_TOKEN}是环境变量插值Hermes 启动时会从当前 Shell 环境读取。OAuth 类型的服务器需要先跑hermes mcp login server完成授权授权窗口最长等 5 分钟。3.3 两种通道的边界对照维度stdio 服务器HTTP 服务器运行位置本机子进程远程独立服务通信方式stdin/stdout JSON-RPCHTTP 请求生命周期Hermes 管理启停独立于 Hermes延迟极低进程内通信取决于网络延迟认证环境变量显式声明Bearer Token / OAuth 2.1典型场景本地 Git、文件系统、数据库GitHub API、Linear、Sentry配置复杂度低一行 command中URL 认证选型逻辑很简单工具在本地、需要低延迟访问本地资源用 stdio工具在远端托管、或组织内部已有 MCP 接口用 HTTP。HoRain 云主机上如果本地装了 Git 和文件系统工具stdio 是首选如果要接 Linear 这类 SaaSHTTP 加 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工具链路就通了。