跳到主要内容

使用 MCP 与 Hermes

本指南展示了如何在日常工作中实际使用 MCP 与 Hermes Agent。

如果功能页面解释了 MCP 是什么，那么本指南则关注如何快速且安全地从中获取价值。

何时应使用 MCP？​

在以下情况使用 MCP：

  • 已存在以 MCP 形式提供的工具，且你不想构建原生的 Hermes 工具
  • 希望 Hermes 通过干净的 RPC 层与本地或远程系统交互
  • 希望实现细粒度的每服务器暴露控制
  • 希望将 Hermes 连接到内部 API、数据库或公司系统，而无需修改 Hermes 核心

不要使用 MCP 的情况包括：

  • 内置的 Hermes 工具已能很好地完成任务
  • 服务器暴露了大量危险工具，而你尚未准备好进行过滤
  • 你只需要一个非常狭窄的集成，原生工具会更简单且更安全

思维模型​

将 MCP 视为一个适配层：

  • Hermes 保持为代理
  • 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

不太理想的首个服务器选择包括：

  • 包含大量破坏性操作且无过滤机制的大型业务系统
  • 你无法充分理解并加以约束的任何系统