<!-- Source: https://hermesbible.com/docs/reference/mcp-config-reference -->

本頁面是主要 MCP 文件的精簡參考手冊。

概念性指引，請參見：

• MCP（模型上下文協定）
• 在 Hermes 中使用 MCP

根設定結構

mcp_servers:
  <server_name>:
    command: "..."      # stdio 伺服器
    args: []
    env: {}

    # 或
    url: "..."          # HTTP 伺服器
    headers: {}

    # 選用的 HTTP/SSE TLS 設定：
    ssl_verify: true                # 布林值或 CA 套件路徑（PEM）
    client_cert: "/path/to/cert.pem"  # mTLS 客戶端憑證（見下文）
    # client_key: "/path/to/key.pem"  # 選用，當金鑰位於獨立檔案時

    enabled: true
    timeout: 120
    connect_timeout: 60
    supports_parallel_tool_calls: false
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

伺服器金鑰

tools 策略金鑰

過濾語義

include

若設定了 include，則只註冊這些伺服器原生的 MCP 工具。

tools:
  include: [create_issue, list_issues]

exclude

若設定了 exclude 且未設定 include，則除這些名稱之外的所有伺服器原生 MCP 工具都會被註冊。

tools:
  exclude: [delete_customer]

優先順序

若兩者都設定了，include 優先。

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

結果：

• create_issue 仍然允許
• delete_issue 被忽略，因為 include 優先

實用工具策略

Hermes 可能為每個 MCP 伺服器註冊這些實用工具包裝器：

資源：

• list_resources
• read_resource

提示：

• list_prompts
• get_prompt

停用資源

tools:
  resources: false

停用提示

tools:
  prompts: false

感知能力的註冊

即使 resources: true 或 prompts: true，Hermes 僅在 MCP 工作階段實際暴露對應能力時才會註冊這些實用工具。

所以以下情況是正常的：

• 你啟用了提示
• 但沒有出現提示實用工具
• 因為伺服器不支援提示

enabled: false

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

行為：

• 不進行連線嘗試
• 不進行發現
• 不進行工具註冊
• 設定保留供後續重用

空結果行為

若過濾移除了所有伺服器原生工具且未註冊實用工具，Hermes 不會為該伺服器建立空的 MCP 運行時工具組。

範例設定

安全的 GitHub 白名單

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      resources: false
      prompts: false

Stripe 黑名單

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

僅資源的文件伺服器

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      include: []
      resources: true
      prompts: false

TLS 客戶端憑證（mTLS）

對於需要客戶端憑證的 HTTP/SSE 伺服器，設定 client_cert（以及可選的 client_key）：

mcp_servers:
  # 憑證 + 金鑰合併在單一 PEM 檔案中
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/secrets/mcp-client.pem"

  # 憑證和金鑰分開的檔案
  partner_api:
    url: "https://mcp.partner.example.com/mcp"
    client_cert: "~/secrets/client.crt"
    client_key: "~/secrets/client.key"

  # 帶有密碼的加密金鑰（三元素列表形式）
  bank_api:
    url: "https://mcp.bank.example.com/mcp"
    client_cert: ["~/secrets/client.crt", "~/secrets/client.key", "my-passphrase"]

  # 自訂 CA 套件（私有 CA / 自簽伺服器）
  lab_api:
    url: "https://mcp.lab.local/mcp"
    ssl_verify: "~/secrets/lab-ca.pem"
    client_cert: "~/secrets/lab-client.pem"

注意事項：

• 路徑支援 ~ 展開。缺失的檔案會在連線時立即失敗，並顯示伺服器範圍的錯誤訊息。
• ssl_verify: false 完全停用伺服器憑證驗證。不要在實際服務中使用此設定。
• 在 Streamable HTTP 和 SSE 傳輸上均可使用。

重新載入設定

變更 MCP 設定後，使用以下命令重新載入伺服器：

/reload-mcp

工具命名

伺服器原生 MCP 工具成為：

mcp_<server>_<tool>

範例：

• mcp_github_create_issue
• mcp_filesystem_read_file
• mcp_my_api_query_data

實用工具遵循相同的前綴模式：

• mcp_<server>_list_resources
• mcp_<server>_read_resource
• mcp_<server>_list_prompts
• mcp_<server>_get_prompt

名稱清理

伺服器名稱和工具名稱中的連字號（-）和點號（.）會在註冊前替換為底線。這確保工具名稱是 LLM 函數呼叫 API 的有效識別碼。

例如，名為 my-api 的伺服器暴露名為 list-items.v2 的工具，會成為：

mcp_my_api_list_items_v2

編寫 include / exclude 過濾器時請記住這一點 — 使用原始的 MCP 工具名稱（帶連字號/點號），而非清理後的版本。

OAuth 2.1 認證

對於需要 OAuth 的 HTTP 伺服器，在伺服器條目上設定 auth: oauth：

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

行為：

• Hermes 使用 MCP SDK 的 OAuth 2.1 PKCE 流程（中繼資料發現、動態客戶端註冊、令牌交換和重新整理）
• 首次連線時，會開啟瀏覽器視窗進行授權
• 令牌持久化至 ~/.hermes/mcp-tokens/<server>.json 並跨工作階段重用
• 令牌重新整理是自動的；僅在重新整理失敗時才重新授權
• 僅適用於 HTTP/StreamableHTTP 傳輸（基於 url 的伺服器）

---

---

模型目錄