Native Mcp

內置的 MCP（模型上下文協議）客戶端，用於連接外部 MCP 服務器，發現其工具，並將它們註冊為原生的 Hermes Agent 工具。支持 stdio 和 HTTP 傳輸協議，具備自動重連、安全過濾和零配置工具注入功能。

技能元數據

來源	捆綁（默認安裝）
路徑	skills/mcp/native-mcp
版本	1.0.0
作者	Hermes Agent
許可證	MIT
標籤	MCP, Tools, Integrations
相關技能	mcporter

參考：完整 SKILL.md

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

Native MCP 客戶端

Hermes Agent 擁有一個內置的 MCP 客戶端，它在啟動時連接到 MCP 服務器，發現其工具，並使這些工具作為一等公民工具供代理直接調用。無需橋接 CLI——來自 MCP 服務器的工具會與 terminal、read_file 等內置工具一起顯示。

何時使用

在以下情況下使用此技能：

• 連接到 MCP 服務器並在 Hermes Agent 中使用其工具
• 通過 MCP 添加外部功能（文件系統訪問、GitHub、數據庫、API）
• 運行基於本地 stdio 的 MCP 服務器（npx、uvx 或任何命令）
• 連接到遠程 HTTP/StreamableHTTP MCP 服務器
• 讓 MCP 工具自動發現並在每次對話中可用

如果希望從終端臨時調用 MCP 工具而無需進行任何配置，請參閱 mcporter 技能。

前置條件

• mcp Python 包 -- 可選依賴項；使用 pip install mcp 安裝。如果未安裝，MCP 支持將被靜默禁用。
• Node.js -- 基於 npx 的 MCP 服務器（大多數社區服務器）所需
• uv -- 基於 uvx 的 MCP 服務器（基於 Python 的服務器）所需

安裝 MCP SDK：

pip install mcp
# or, if using uv:
uv pip install mcp

快速開始

在 ~/.hermes/config.yaml 的 mcp_servers 鍵下添加 MCP 服務器：

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

重啟 Hermes Agent。啟動時它將：

1. 連接到服務器
2. 發現可用工具
3. 使用 mcp_time_* 前綴註冊它們
4. 將它們注入到所有平臺工具集中

然後你可以自然地使用這些工具——只需要求代理獲取當前時間。

配置參考

mcp_servers 下的每個條目都是一個映射到其配置的服務器名稱。有兩種傳輸類型：stdio（基於命令）和 HTTP（基於 URL）。

Stdio 傳輸（命令 + 參數）

mcp_servers:
  server_name:
    command: "npx"             # (required) executable to run
    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
    env:                       # (optional) environment variables for the subprocess
      SOME_API_KEY: "value"
    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

HTTP 傳輸（URL）

mcp_servers:
  server_name:
    url: "https://my-server.example.com/mcp"   # (required) server URL
    headers:                                     # (optional) HTTP headers
      Authorization: "Bearer sk-..."
    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

所有配置選項

選項	類型	默認值	描述
command	string	--	要運行的可執行文件（stdio 傳輸，必填）
args	list	[]	傳遞給命令的參數
env	dict	{}	子進程的額外環境變量
url	string	--	服務器 URL（HTTP 傳輸，必填）
headers	dict	{}	隨每個請求發送的 HTTP 頭
timeout	int	120	每次工具調用的超時時間（秒）
connect_timeout	int	60	初始連接和發現的超時時間

注意：服務器配置必須包含 command（stdio）或 url（HTTP），二者不可兼得。

工作原理

啟動發現

當 Hermes Agent 啟動時，會在工具初始化期間調用 discover_mcp_tools()：

1. 從 ~/.hermes/config.yaml 讀取 mcp_servers
2. 對於每個服務器，在專用的後臺事件循環中生成連接
3. 初始化 MCP 會話並調用 list_tools() 以發現可用工具
4. 在 Hermes 工具註冊表中註冊每個工具

工具命名約定

MCP 工具按照以下命名模式註冊：

mcp_{server_name}_{tool_name}

為了兼容 LLM API，名稱中的連字符和點號會被替換為下劃線。

示例：

• 服務器 filesystem，工具 read_file → mcp_filesystem_read_file
• 服務器 github，工具 list-issues → mcp_github_list_issues
• 服務器 my-api，工具 fetch.data → mcp_my_api_fetch_data

自動注入

發現後，MCP 工具會自動注入到所有 hermes-* 平臺工具集（CLI、Discord、Telegram 等）中。這意味著 MCP 工具在每次對話中都可用，無需任何額外配置。

連接生命週期

• 每個服務器作為長期運行的 asyncio Task 在後臺守護線程中運行
• 連接在代理進程的生命週期內持續存在
• 如果連接斷開，會自動觸發指數退避重連機制（最多重試 5 次，最大退避時間 60 秒）
• 在代理關閉時，所有連接都會優雅地關閉

冪等性

discover_mcp_tools() 是冪等的——多次調用僅會連接到尚未連接的服務器。失敗的服務器將在後續調用中重試。

傳輸類型

Stdio 傳輸

最常見的傳輸方式。Hermes 將 MCP 服務器作為子進程啟動，並通過 stdin/stdout 進行通信。

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

該子進程繼承一個經過過濾的環境變量（參見下方的安全部分），以及你在 env 中指定的任何變量。

HTTP / StreamableHTTP 傳輸

適用於遠程或共享的 MCP 服務器。要求 mcp 包包含 HTTP 客戶端支持（mcp.client.streamable_http）。

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

如果已安裝的 mcp 版本中不可用 HTTP 支持，服務器將因 ImportError 失敗，而其他服務器將繼續正常運行。

安全

環境變量過濾

對於 stdio 服務器，Hermes 不會將完整的 shell 環境變量傳遞給 MCP 子進程。僅繼承安全的基線變量：

• PATH、HOME、USER、LANG、LC_ALL、TERM、SHELL、TMPDIR
• 任何 XDG_* 變量

除非你通過 env 配置鍵顯式添加，否則所有其他環境變量（API 密鑰、令牌、機密）均被排除。這防止了憑據意外洩露給不受信任的 MCP 服務器。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # Only this token is passed to the subprocess
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

錯誤消息中的憑據剝離

如果 MCP 工具調用失敗，錯誤消息中任何類似憑據的模式在顯示給 LLM 之前會自動被脫敏。涵蓋以下內容：

• GitHub PATs (ghp_...)
• OpenAI 風格的密鑰 (sk-...)
• Bearer 令牌
• 通用的 token=、key=、API_KEY=、password=、secret= 模式

故障排除

"MCP SDK not available -- skipping MCP tool discovery"

未安裝 mcp Python 包。請安裝它：

pip install mcp

"No MCP servers configured"

~/.hermes/config.yaml 中沒有 mcp_servers 鍵，或者該鍵為空。請至少添加一個服務器。

"Failed to connect to MCP server 'X'"

常見原因：

• 命令未找到：command 二進制文件不在 PATH 中。確保已安裝 npx、uvx 或相關命令。
• 包未找到：對於 npx 服務器，npm 包可能不存在，或者需要在參數中添加 -y 以自動安裝。
• 超時：服務器啟動時間過長。增加 connect_timeout。
• 端口衝突：對於 HTTP 服務器，URL 可能無法訪問。

"MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"

你的 mcp 包版本不包含 HTTP 客戶端支持。請升級：

pip install --upgrade mcp

工具未出現

• 檢查服務器是否列在 mcp_servers 下（而不是 mcp 或 servers）
• 確保 YAML 縮進正確
• 查看 Hermes Agent 啟動日誌中的連接消息
• 工具名稱以前綴 mcp_{server}_{tool} 命名——查找該模式

連接不斷斷開

客戶端會以指數退避機制最多重試 5 次（1秒、2秒、4秒、8秒、16秒，上限為 60秒）。如果服務器根本不可達，它將在 5 次嘗試後放棄。檢查服務器進程和網絡連通性。

示例

時間服務器 (uvx)

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

註冊諸如 mcp_time_get_current_time 之類的工具。

文件系統服務器 (npx)

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

註冊諸如 mcp_filesystem_read_file、mcp_filesystem_write_file、mcp_filesystem_list_directory 之類的工具。

帶身份驗證的 GitHub 服務器

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

註冊諸如 mcp_github_list_issues、mcp_github_create_pull_request 等工具。

遠程 HTTP 服務器

mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

多個服務器

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

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

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 300

來自所有服務器的所有工具均已註冊並同時可用。每個服務器的工具都以其名稱為前綴，以避免衝突。

採樣（服務器發起的 LLM 請求）

Hermes 支持 MCP 的 sampling/createMessage 能力——MCP 服務器可以在工具執行期間通過代理請求 LLM 補全。這使得代理在環工作流（數據分析、內容生成、決策制定）成為可能。

採樣默認啟用。按服務器配置：

mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true           # default: true
      model: "gemini-3-flash" # model override (optional)
      max_tokens_cap: 4096    # max tokens per request
      timeout: 30             # LLM call timeout (seconds)
      max_rpm: 10             # max requests per minute
      allowed_models: []      # model whitelist (empty = all)
      max_tool_rounds: 5      # tool loop limit (0 = disable)
      log_level: "info"       # audit verbosity

服務器還可以在採樣請求中包含 tools，用於多輪工具增強工作流。max_tool_rounds 配置可防止無限工具循環。每個服務器的審計指標（請求數、錯誤數、令牌數、工具使用計數）通過 get_mcp_status() 進行跟蹤。

使用 sampling: { enabled: false } 為不受信任的服務器禁用採樣。

注意事項

• 從代理的角度來看，MCP 工具是同步調用的，但在專用的後臺事件循環上異步運行
• 工具結果以 JSON 形式返回，格式為 {"result": "..."} 或 {"error": "..."}
• 原生 MCP 客戶端獨立於 mcporter——你可以同時使用兩者
• 服務器連接是持久的，並在同一代理進程中的所有對話間共享
• 添加或刪除服務器需要重啟代理（目前不支持熱重載）