跳到主要內容

MCP 配置參考

本頁是主 MCP 文檔的簡潔參考指南。

關於概念性指導，請參閱：

根配置結構​

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

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

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

服務器鍵​

鍵類型適用範圍含義
commandstringstdio要啟動的可執行文件
argsliststdio子進程的參數
envmappingstdio傳遞給子進程的環境變量
urlstringHTTP遠程 MCP 端點
headersmappingHTTP遠程服務器請求的頭部信息
enabledbool兩者為 false 時跳過整個服務器
timeoutnumber兩者工具調用超時時間
connect_timeoutnumber兩者初始連接超時時間
toolsmapping兩者工具過濾與實用工具策略
authstringHTTP認證方式。設為 oauth 以啟用 OAuth 2.1 與 PKCE
samplingmapping兩者服務器發起的 LLM 請求策略（參見 MCP 指南）

tools 策略鍵​

鍵類型含義
includestring 或 list白名單：允許的服務器原生 MCP 工具
excludestring 或 list黑名單：禁止的服務器原生 MCP 工具
resourcesbool-like啟用/禁用 list_resources + read_resource
promptsbool-like啟用/禁用 list_prompts + get_prompt

過濾語義​

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

重新加載配置​

更改 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 的服務器）