跳到主要內容

使用 MCP 與 Hermes

本指南展示瞭如何在日常工作中實際使用 MCP 與 Hermes Agent。

如果功能頁面解釋了 MCP 是什麼，那麼本指南則關注如何快速且安全地從中獲取價值。

何時應使用 MCP？​

在以下情況使用 MCP：

  • 已存在以 MCP 形式提供的工具，且你不想構建原生的 Hermes 工具
  • 希望 Hermes 通過乾淨的 RPC 層與本地或遠程系統交互
  • 希望按服務器進行細粒度的暴露控制
  • 希望將 Hermes 連接到內部 API、數據庫或公司系統，而無需修改 Hermes 核心

不要使用 MCP 的情況包括：

  • 內置的 Hermes 工具已能很好地完成任務
  • 服務器暴露了大量危險工具，而你尚未準備好進行過濾
  • 你只需要一個非常狹窄的集成，原生工具會更簡單且更安全

思維模型​

將 MCP 視為一個適配層：

  • Hermes 保持為 Agent
  • MCP 服務器提供工具
  • Hermes 在啟動或重新加載時發現這些工具
  • 模型可像使用普通工具一樣使用它們
  • 你控制每個服務器可見的部分

最後一點至關重要。良好的 MCP 使用方式不僅僅是“連接一切”，而是“連接正確的內容，並且只暴露最小但夠用的能力範圍”。

第一步：安裝 MCP 支持​

如果你通過標準安裝腳本安裝了 Hermes，MCP 支持已包含在內（安裝程序會運行 uv pip install -e ".[all]"）。

如果你未使用額外組件安裝，需要單獨添加 MCP：

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

對於基於 npm 的服務器，請確保 Node.js 和 npx 可用。

對於許多 Python MCP 服務器，uvx 是一個不錯的默認選擇。

第二步：先添加一個服務器​

從一個單一、安全的服務器開始。

示例：僅對一個項目目錄進行文件系統訪問。

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

然後啟動 Hermes：

hermes chat

現在提出一個具體問題：

Inspect this project and summarize the repo layout.

第三步：驗證 MCP 已加載​

你可以通過以下幾種方式驗證 MCP：

  • 配置後，Hermes 啟動橫幅/狀態應顯示 MCP 集成
  • 詢問 Hermes 它有哪些可用工具
  • 在配置更改後使用 /reload-mcp
  • 檢查日誌以確認服務器是否連接失敗

一個實用的測試提示：

Tell me which MCP-backed tools are available right now.

第四步：立即開始過濾​

如果服務器暴露了大量工具，請不要等到以後再處理。

示例：僅允許所需內容（白名單）​

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

這通常是敏感系統的最佳默認策略。

示例：屏蔽危險操作（黑名單）​

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:
      prompts: false
      resources: false

過濾實際影響什麼？​

Hermes 中通過 MCP 暴露的功能分為兩類：

  1. 服務器原生的 MCP 工具

    • 通過以下方式過濾：
      • tools.include
      • tools.exclude

  2. Hermes 添加的實用封裝器

    • 通過以下方式過濾：
      • tools.resources
      • tools.prompts

你可能會看到的實用封裝器​

資源：

  • list_resources
  • read_resource

提示：

  • list_prompts
  • get_prompt

這些封裝器僅在滿足以下條件時才會出現：

  • 你的配置允許它們
  • MCP 服務器會話確實支持這些功能

因此，Hermes 不會假裝某個服務器擁有資源/提示，如果它實際上並不支持。

常見模式​

模式 1：本地項目助手​

當希望 Hermes 在一個有限的工作區範圍內推理時，使用 MCP 來連接倉庫本地的文件系統或 Git 服務器。

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

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

良好提示示例：

Review the project structure and identify where configuration lives.
Check the local git state and summarize what changed recently.

模式 2：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]
      prompts: false
      resources: false

良好提示示例：

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

模式 3：內部 API 助手​

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

良好提示示例：

Look up customer ACME Corp and summarize recent invoice activity.

在這種場景中，嚴格的白名單遠優於排除列表。

模式 4：文檔 / 知識服務器​

某些 MCP 服務器暴露的提示或資源更像是共享知識資產，而非直接操作。

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: true
      resources: true

良好提示示例：

List available MCP resources from the docs server, then read the onboarding guide and summarize it.
List prompts exposed by the docs server and tell me which ones would help with incident response.

教程：帶過濾的端到端設置​

以下是一個實用的逐步流程。

階段 1：添加 GitHub MCP 並使用嚴格白名單​

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

啟動 Hermes 並提問：

Search the codebase for references to MCP and summarize the main integration points.

階段 2：僅在需要時擴展​

如果之後需要更新問題：

tools:
  include: [list_issues, create_issue, update_issue, search_code]

然後重新加載：

/reload-mcp

階段 3：添加第二個具有不同策略的服務器​

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]
      prompts: false
      resources: false

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

現在 Hermes 可以組合使用它們：

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

這正是 MCP 的強大之處：無需修改 Hermes 核心即可實現多系統工作流。

安全使用建議​

對危險系統優先使用允許列表​

對於任何金融、面向客戶或具有破壞性的系統：

  • 使用 tools.include
  • 從最小的集合開始

禁用未使用的實用功能​

如果你不希望模型瀏覽服務器提供的資源/提示，請關閉它們：

tools:
  resources: false
  prompts: false

將服務器作用域限制在狹窄範圍內​

示例：

  • 以單個項目目錄為根目錄的文件系統服務器，而非整個主目錄
  • 指向單個倉庫的 Git 服務器
  • 默認以讀取為主、工具暴露較多的內部 API 服務器

配置更改後重新加載​

/reload-mcp

在更改以下內容後執行此操作：

  • include/exclude 列表
  • 啟用標誌
  • 資源/提示開關
  • 認證頭 / 環境變量

按症狀排查問題​

“服務器已連接，但我預期的工具缺失”​

可能原因：

  • 被 tools.include 過濾
  • 被 tools.exclude 排除
  • 通過 resources: false 或 prompts: false 禁用了工具包裝器
  • 服務器本身不支持資源/提示功能

“服務器已配置，但沒有任何內容加載”​

請檢查：

  • 配置中未留下 enabled: false
  • 命令/運行時存在（如 npx、uvx 等）
  • HTTP 端點可訪問
  • 認證環境變量或請求頭正確

“為什麼我看到的工具比 MCP 服務器宣傳的要少？”​

因為 Hermes 現在尊重每個服務器的策略和能力感知註冊機制。這是預期行為，通常也是期望的結果。

“如何在不刪除配置的情況下移除一個 MCP 服務器？”​

使用：

enabled: false

這將保留配置，但阻止連接和註冊。

對大多數用戶而言，良好的首個服務器選擇包括：

  • 文件系統
  • Git
  • GitHub
  • fetch / 文檔 MCP 服務器
  • 一個功能狹窄的內部 API

不太理想的首個服務器選擇包括：

  • 包含大量破壞性操作且無過濾機制的大型業務系統
  • 你無法充分理解並加以約束的任何系統