)
1. HoRain 云上 Hermes Agent 接 MCP為什么 stdio 和 HTTP 要分開配Hermes Agent 是 Nous Research 出的一個開源 Agent 框架原生支持 MCPModel Context Protocol。MCP 是 Anthropic 提出的開放協(xié)議用來標準化 LLM 和外部工具的交互——簡單說任何實現(xiàn)了 MCP 協(xié)議的服務Hermes 都能直接接進來不用為每個服務單獨寫適配代碼。它適合誰適合已經(jīng)在 HoRain 云上跑 Hermes、想把 GitHub、文件系統(tǒng)、數(shù)據(jù)庫、內(nèi)部 API 這些工具鏈接進 Agent 工具調(diào)用鏈路的開發(fā)者。但實際配的時候很多人會卡在同一個地方MCP 服務器有兩種傳輸方式stdio 和 HTTP配置字段完全不一樣適用邊界也不一樣。stdio 是本地子進程走 stdin/stdout 加 JSON-RPCHTTP 是遠程端點走 HTTP 請求加 Bearer Token 或 OAuth。你在 HoRain 云環(huán)境里如果本地工具和遠程服務混著接配置寫錯一個字段Agent 就報工具不出現(xiàn)。我試過在 HoRain 云主機上把這兩條通道都跑通踩過的坑主要集中在三塊一是 stdio 子進程的環(huán)境變量隔離二是 HTTP 端點的認證頭寫法三是工具過濾的命名規(guī)則。這篇就按可復制的配置骨架把 stdio 和 HTTP 雙通道拆開講清楚最后附連通性驗證動作讓你在 HoRain 云上快速跑通 Hermes Agent 的工具調(diào)用鏈路。2. 前置TaoToken 統(tǒng)一 Key 與 API 通道準備Hermes Agent 本身負責 MCP 客戶端這一側(cè)但 Agent 背后調(diào)用的模型通道需要單獨配。這里用 TaoToken 做統(tǒng)一 Key 和 API 通道好處是一個 Key 走多個模型不用在 Hermes 里為每個模型維護一套憑據(jù)。TaoToken 的 API 地址是https://taotoken.net/api注意這個地址不帶任何查詢參數(shù)。官網(wǎng)入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注冊和拿 Key 都在控制臺完成。拿 Key 的路徑是進控制臺找到 API Keys 頁面新建一個 Key。這個 Key 后面會寫進 Hermes 的模型配置里同時 MCP 服務器如果需要訪問模型側(cè)能力也可以復用同一個 Key 做統(tǒng)一鑒權。注意MCP 服務器自己的認證比如 GitHub 的 PAT、Linear 的 OAuth和 TaoToken 的 Key 是兩回事。TaoToken Key 管的是模型通道MCP 服務器的認證管的是工具通道別混在一個 env 塊里。如果你后面要長期跑編碼類 Agent 任務可以看下 Coding Plan 頁面它針對高頻編碼場景做了額度優(yōu)化。模型對話調(diào)試可以直接用模型對話頁面驗證通道是否通。接入文檔在 doc 頁面API Keys 管理在 api-keys 頁面。3. 可復制配置stdio 與 HTTP 雙通道聲明骨架Hermes 的 MCP 配置統(tǒng)一寫在~/.hermes/config.yaml的mcp_servers塊下。下面這份骨架把 stdio 和 HTTP 兩類服務器放在一起你可以直接改路徑和 Token 用。3.1 stdio 通道本地子進程配置stdio 服務器以子進程形式在本地運行Hermes 負責它的生命周期——會話啟動或/reload-mcp時拉起子進程會話結束或禁用時終止崩潰自動重啟最多 3 次。# 文件路徑~/.hermes/config.yaml mcp_servers: # 文件系統(tǒng)服務器限制 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 服務器竊取你環(huán)境里的其他憑據(jù)。3.2 HTTP 通道遠程端點配置HTTP 服務器通過 HTTP 請求連遠程 MCP 端點支持靜態(tài) Bearer Token 和 OAuth 2.1 兩種認證。# 文件路徑~/.hermes/config.yaml mcp_servers: # 方式一靜態(tài) Bearer Token適合內(nèi)部 API internal_api: url: https://mcp.internal.example.com/mcp headers: Authorization: Bearer ${MY_INTERNAL_TOKEN} # 支持環(huán)境變量插值 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}是環(huán)境變量插值Hermes 啟動時會從當前 Shell 環(huán)境讀取。OAuth 類型的服務器需要先跑hermes mcp login server完成授權授權窗口最長等 5 分鐘。3.3 兩種通道的邊界對照維度stdio 服務器HTTP 服務器運行位置本機子進程遠程獨立服務通信方式stdin/stdout JSON-RPCHTTP 請求生命周期Hermes 管理啟停獨立于 Hermes延遲極低進程內(nèi)通信取決于網(wǎng)絡延遲認證環(huán)境變量顯式聲明Bearer Token / OAuth 2.1典型場景本地 Git、文件系統(tǒng)、數(shù)據(jù)庫GitHub API、Linear、Sentry配置復雜度低一行 command中URL 認證選型邏輯很簡單工具在本地、需要低延遲訪問本地資源用 stdio工具在遠端托管、或組織內(nèi)部已有 MCP 接口用 HTTP。HoRain 云主機上如果本地裝了 Git 和文件系統(tǒng)工具stdio 是首選如果要接 Linear 這類 SaaSHTTP 加 OAuth 是唯一選擇。4. 驗證請求連通性檢查與成功結果配置寫完別急著開 Agent 會話先做三步驗證。第一步列出所有已配置服務器確認配置被正確加載hermes mcp list正常輸出會列出每個服務器的名稱、類型stdio/HTTP和狀態(tài)。如果某個服務器沒出現(xiàn)說明 YAML 縮進或字段名寫錯了。第二步測試單個服務器連接hermes mcp test filesystemstdio 服務器會嘗試拉起子進程并做一次 JSON-RPC 握手成功返回類似connection ok, 3 tools discovered。HTTP 服務器會發(fā)一次探測請求成功返回HTTP 200, tools: list_issues, create_issue。如果報command not found檢查command是否在 PATH 里如果報401檢查Authorization頭或 OAuth 是否已授權。第三步在 Agent 會話里重新加載 MCP 配置/reload-mcp這個命令在會話內(nèi)生效不用重啟整個 Agent。加載完成后Agent 的工具列表里應該能看到mcp-filesystem、mcp-git這類工具集。你可以直接問 Agent「列出當前可用的 MCP 工具」它會返回注冊成功的工具清單。成功結果長這樣Agent 能調(diào)用git_status返回倉庫狀態(tài)能調(diào)用list_issues返回 Linear 的 issue 列表且錯誤信息里的 Token 被自動替換成[REDACTED]。Hermes 在把 MCP 工具錯誤返回給 LLM 前會自動脫敏敏感信息不會明文出現(xiàn)在對話里。5. 本篇常見錯排查MCP 工具不出現(xiàn)最常見的原因是服務器沒啟用或連接失敗。先跑hermes mcp list看狀態(tài)再跑hermes mcp test name測連接。stdio 服務器如果command不在 PATH 里會靜默失敗。工具過濾不生效這是命名規(guī)則的坑。Hermes 注冊后的工具名會把連字符轉(zhuǎn)成下劃線但你在tools.include或tools.exclude里必須用 MCP 原始工具名也就是帶連字符的list-issues不是list_issues。寫錯了過濾規(guī)則會被忽略服務器暴露的所有工具都會注冊。stdio 服務器頻繁崩潰多半是依賴缺失或權限不足。手動在終端跑一遍command加args看能不能正常啟動。如果報EACCES檢查目標目錄的讀權限。OAuth 授權超時/reload-mcp的等待窗口只有 30 秒不夠完成 OAuth 瀏覽器授權。正確做法是先跑hermes mcp login server在瀏覽器里完成授權再跑/reload-mcp。環(huán)境變量不生效stdio 子進程只繼承基礎變量你在 Shell 里export的 Token 不會自動傳入。必須在mcp_servers.name.env塊里顯式聲明。HTTP 服務器的headers里用${VAR}插值同樣要求變量在當前 Shell 環(huán)境里存在。HTTP 服務器連接拒絕檢查 URL 是否可達、Authorization頭格式是否正確。Bearer Token 的格式是Bearer token中間一個空格別漏了。6. 接入通道與后續(xù)動作排障和接入相關的操作統(tǒng)一走 API Keys 頁面管理 Key接入文檔在 doc 頁面看完整字段說明。如果你要驗證模型通道是否通用模型對話頁面直接發(fā)一條測試請求。長期跑編碼類 Agent 任務Coding Plan 頁面有針對高頻調(diào)用的額度方案。HoRain 云上跑 Hermes Agent 接 MCP核心就是把 stdio 和 HTTP 兩條通道的配置字段分清stdio 看command加args加env隔離HTTP 看url加headers或auth。工具過濾記得用原始工具名環(huán)境變量記得顯式聲明。配完跑一遍hermes mcp list和hermes mcp test再/reload-mcp工具鏈路就通了。 HoRain云 Hermes Agent 集成 MCP：stdio 與 HTTP 雙通道配置實戰(zhàn)
1. HoRain 云上 Hermes Agent 接 MCP為什么 stdio 和 HTTP 要分開配Hermes Agent 是 Nous Research 出的一個開源 Agent 框架原生支持 MCPModel Context Protocol。MCP 是 Anthropic 提出的開放協(xié)議用來標準化 LLM 和外部工具的交互——簡單說任何實現(xiàn)了 MCP 協(xié)議的服務Hermes 都能直接接進來不用為每個服務單獨寫適配代碼。它適合誰適合已經(jīng)在 HoRain 云上跑 Hermes、想把 GitHub、文件系統(tǒng)、數(shù)據(jù)庫、內(nèi)部 API 這些工具鏈接進 Agent 工具調(diào)用鏈路的開發(fā)者。但實際配的時候很多人會卡在同一個地方MCP 服務器有兩種傳輸方式stdio 和 HTTP配置字段完全不一樣適用邊界也不一樣。stdio 是本地子進程走 stdin/stdout 加 JSON-RPCHTTP 是遠程端點走 HTTP 請求加 Bearer Token 或 OAuth。你在 HoRain 云環(huán)境里如果本地工具和遠程服務混著接配置寫錯一個字段Agent 就報工具不出現(xiàn)。我試過在 HoRain 云主機上把這兩條通道都跑通踩過的坑主要集中在三塊一是 stdio 子進程的環(huán)境變量隔離二是 HTTP 端點的認證頭寫法三是工具過濾的命名規(guī)則。這篇就按可復制的配置骨架把 stdio 和 HTTP 雙通道拆開講清楚最后附連通性驗證動作讓你在 HoRain 云上快速跑通 Hermes Agent 的工具調(diào)用鏈路。2. 前置TaoToken 統(tǒng)一 Key 與 API 通道準備Hermes Agent 本身負責 MCP 客戶端這一側(cè)但 Agent 背后調(diào)用的模型通道需要單獨配。這里用 TaoToken 做統(tǒng)一 Key 和 API 通道好處是一個 Key 走多個模型不用在 Hermes 里為每個模型維護一套憑據(jù)。TaoToken 的 API 地址是https://taotoken.net/api注意這個地址不帶任何查詢參數(shù)。官網(wǎng)入口在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注冊和拿 Key 都在控制臺完成。拿 Key 的路徑是進控制臺找到 API Keys 頁面新建一個 Key。這個 Key 后面會寫進 Hermes 的模型配置里同時 MCP 服務器如果需要訪問模型側(cè)能力也可以復用同一個 Key 做統(tǒng)一鑒權。注意MCP 服務器自己的認證比如 GitHub 的 PAT、Linear 的 OAuth和 TaoToken 的 Key 是兩回事。TaoToken Key 管的是模型通道MCP 服務器的認證管的是工具通道別混在一個 env 塊里。如果你后面要長期跑編碼類 Agent 任務可以看下 Coding Plan 頁面它針對高頻編碼場景做了額度優(yōu)化。模型對話調(diào)試可以直接用模型對話頁面驗證通道是否通。接入文檔在 doc 頁面API Keys 管理在 api-keys 頁面。3. 可復制配置stdio 與 HTTP 雙通道聲明骨架Hermes 的 MCP 配置統(tǒng)一寫在~/.hermes/config.yaml的mcp_servers塊下。下面這份骨架把 stdio 和 HTTP 兩類服務器放在一起你可以直接改路徑和 Token 用。3.1 stdio 通道本地子進程配置stdio 服務器以子進程形式在本地運行Hermes 負責它的生命周期——會話啟動或/reload-mcp時拉起子進程會話結束或禁用時終止崩潰自動重啟最多 3 次。# 文件路徑~/.hermes/config.yaml mcp_servers: # 文件系統(tǒng)服務器限制 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 服務器竊取你環(huán)境里的其他憑據(jù)。3.2 HTTP 通道遠程端點配置HTTP 服務器通過 HTTP 請求連遠程 MCP 端點支持靜態(tài) Bearer Token 和 OAuth 2.1 兩種認證。# 文件路徑~/.hermes/config.yaml mcp_servers: # 方式一靜態(tài) Bearer Token適合內(nèi)部 API internal_api: url: https://mcp.internal.example.com/mcp headers: Authorization: Bearer ${MY_INTERNAL_TOKEN} # 支持環(huán)境變量插值 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}是環(huán)境變量插值Hermes 啟動時會從當前 Shell 環(huán)境讀取。OAuth 類型的服務器需要先跑hermes mcp login server完成授權授權窗口最長等 5 分鐘。3.3 兩種通道的邊界對照維度stdio 服務器HTTP 服務器運行位置本機子進程遠程獨立服務通信方式stdin/stdout JSON-RPCHTTP 請求生命周期Hermes 管理啟停獨立于 Hermes延遲極低進程內(nèi)通信取決于網(wǎng)絡延遲認證環(huán)境變量顯式聲明Bearer Token / OAuth 2.1典型場景本地 Git、文件系統(tǒng)、數(shù)據(jù)庫GitHub API、Linear、Sentry配置復雜度低一行 command中URL 認證選型邏輯很簡單工具在本地、需要低延遲訪問本地資源用 stdio工具在遠端托管、或組織內(nèi)部已有 MCP 接口用 HTTP。HoRain 云主機上如果本地裝了 Git 和文件系統(tǒng)工具stdio 是首選如果要接 Linear 這類 SaaSHTTP 加 OAuth 是唯一選擇。4. 驗證請求連通性檢查與成功結果配置寫完別急著開 Agent 會話先做三步驗證。第一步列出所有已配置服務器確認配置被正確加載hermes mcp list正常輸出會列出每個服務器的名稱、類型stdio/HTTP和狀態(tài)。如果某個服務器沒出現(xiàn)說明 YAML 縮進或字段名寫錯了。第二步測試單個服務器連接hermes mcp test filesystemstdio 服務器會嘗試拉起子進程并做一次 JSON-RPC 握手成功返回類似connection ok, 3 tools discovered。HTTP 服務器會發(fā)一次探測請求成功返回HTTP 200, tools: list_issues, create_issue。如果報command not found檢查command是否在 PATH 里如果報401檢查Authorization頭或 OAuth 是否已授權。第三步在 Agent 會話里重新加載 MCP 配置/reload-mcp這個命令在會話內(nèi)生效不用重啟整個 Agent。加載完成后Agent 的工具列表里應該能看到mcp-filesystem、mcp-git這類工具集。你可以直接問 Agent「列出當前可用的 MCP 工具」它會返回注冊成功的工具清單。成功結果長這樣Agent 能調(diào)用git_status返回倉庫狀態(tài)能調(diào)用list_issues返回 Linear 的 issue 列表且錯誤信息里的 Token 被自動替換成[REDACTED]。Hermes 在把 MCP 工具錯誤返回給 LLM 前會自動脫敏敏感信息不會明文出現(xiàn)在對話里。5. 本篇常見錯排查MCP 工具不出現(xiàn)最常見的原因是服務器沒啟用或連接失敗。先跑hermes mcp list看狀態(tài)再跑hermes mcp test name測連接。stdio 服務器如果command不在 PATH 里會靜默失敗。工具過濾不生效這是命名規(guī)則的坑。Hermes 注冊后的工具名會把連字符轉(zhuǎn)成下劃線但你在tools.include或tools.exclude里必須用 MCP 原始工具名也就是帶連字符的list-issues不是list_issues。寫錯了過濾規(guī)則會被忽略服務器暴露的所有工具都會注冊。stdio 服務器頻繁崩潰多半是依賴缺失或權限不足。手動在終端跑一遍command加args看能不能正常啟動。如果報EACCES檢查目標目錄的讀權限。OAuth 授權超時/reload-mcp的等待窗口只有 30 秒不夠完成 OAuth 瀏覽器授權。正確做法是先跑hermes mcp login server在瀏覽器里完成授權再跑/reload-mcp。環(huán)境變量不生效stdio 子進程只繼承基礎變量你在 Shell 里export的 Token 不會自動傳入。必須在mcp_servers.name.env塊里顯式聲明。HTTP 服務器的headers里用${VAR}插值同樣要求變量在當前 Shell 環(huán)境里存在。HTTP 服務器連接拒絕檢查 URL 是否可達、Authorization頭格式是否正確。Bearer Token 的格式是Bearer token中間一個空格別漏了。6. 接入通道與后續(xù)動作排障和接入相關的操作統(tǒng)一走 API Keys 頁面管理 Key接入文檔在 doc 頁面看完整字段說明。如果你要驗證模型通道是否通用模型對話頁面直接發(fā)一條測試請求。長期跑編碼類 Agent 任務Coding Plan 頁面有針對高頻調(diào)用的額度方案。HoRain 云上跑 Hermes Agent 接 MCP核心就是把 stdio 和 HTTP 兩條通道的配置字段分清stdio 看command加args加env隔離HTTP 看url加headers或auth。工具過濾記得用原始工具名環(huán)境變量記得顯式聲明。配完跑一遍hermes mcp list和hermes mcp test再/reload-mcp工具鏈路就通了。