跳到主要内容

将 MCP 与 Hermes 配合使用

本指南介绍如何在日常工作流里真正把 MCP 用到 Hermes Agent 上。

如果功能页解释的是 MCP 是什么，那么这篇指南关注的是如何快速、安全地把它用出价值。

什么时候该用 MCP？​

在以下情况使用 MCP：

  • 某个工具已经以 MCP 形式存在，而你不想再实现一个原生 Hermes 工具
  • 你希望 Hermes 通过清晰的 RPC 层操作本地或远程系统
  • 你需要按服务器做细粒度工具暴露控制
  • 你希望 Hermes 连接内部 API、数据库或公司系统，但不改 Hermes 核心

在以下情况不要使用 MCP：

  • 内置的 Hermes 工具已经足够胜任
  • 服务器暴露了过大且危险的工具面，而你又不准备做过滤
  • 你只需要一个很窄的集成，写一个原生工具会更简单也更安全

心智模型​

可以把 MCP 看作一层适配器：

  • Hermes 仍然是 agent
  • MCP 服务器提供工具
  • Hermes 在启动或重载时发现这些工具
  • 模型可以像使用普通工具一样使用它们
  • 你可以控制每台服务器向模型暴露多少能力

最后一点非常重要。好的 MCP 使用方式不是“全都接上”，而是“只接入对的东西，并把暴露面缩到刚好够用”。

第 1 步：安装 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 是一个很好的默认选择。

第 2 步：先只加一台服务器​

先从一台安全、范围明确的服务器开始。

示例：只开放某一个项目目录的文件系统访问。

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.

第 3 步：确认 MCP 已加载​

你可以通过以下几种方式确认 MCP 是否正常工作：

  • 配置完成后，Hermes 的启动横幅或状态信息会显示 MCP 集成
  • 直接问 Hermes 当前有哪些可用工具
  • 修改配置后使用 /reload-mcp
  • 如果服务器连接失败，查看日志

一个实用的测试提示是：

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

第 4 步：立刻开始做过滤​

如果服务器暴露了很多工具，不要想着“以后再过滤”。

示例：只把需要的工具加入白名单​

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
  1. Hermes 额外添加的实用包装工具
  • 用以下配置过滤：
    • tools.resources
    • tools.prompts

你可能会看到的实用包装工具​

Resources:

  • list_resources
  • read_resource

Prompts:

  • list_prompts
  • get_prompt

这些包装工具只有在以下条件同时满足时才会出现：

  • 配置允许它们
  • MCP 服务器会话本身也真的支持这些能力

所以，如果某台服务器根本不支持 resources 或 prompts，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 服务器暴露的 prompts 或 resources 更像共享知识资产，而不是直接动作。

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：只在需要时扩展​

如果之后你确实需要更新 issue 的能力：

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
  • 从最小可用集合开始

关闭不用的实用能力​

如果你不希望模型去浏览服务器提供的 resources 或 prompts，就把它们关掉：

tools:
  resources: false
  prompts: false

把服务器范围收窄​

例如：

  • 文件系统服务器只根到某一个项目目录，而不是整个 home 目录
  • git 服务器只指向一个仓库
  • 内部 API 服务器默认只暴露偏只读的能力

配置变更后记得重载​

/reload-mcp

尤其是在改完这些以后：

  • include / exclude 列表
  • enabled 开关
  • resources / prompts 开关
  • 鉴权 headers / env

按症状排查问题​

“服务器连上了，但我预期的工具没出现”​

可能原因：

  • 被 tools.include 过滤掉了
  • 被 tools.exclude 排除了
  • resources: false 或 prompts: false 禁用了实用包装工具
  • 服务器实际上并不支持 resources 或 prompts

“配置了服务器，但什么都没加载”​

检查：

  • 配置里是不是还留着 enabled: false
  • 运行时命令是否存在（npx、uvx 等）
  • HTTP 端点是否可达
  • 鉴权 env 或 headers 是否正确

“为什么我看到的工具比 MCP 服务器宣称的更少？”​

因为 Hermes 现在会遵守你按服务器配置的策略，并结合能力感知注册。这样是预期行为，而且通常更好。

“如何保留配置但先移除 MCP 服务器？”​

使用：

enabled: false

这样配置还在，但不会连接，也不会注册工具。

推荐的第一批 MCP 配置​

对大多数用户来说，比较好的第一批服务器是：

  • filesystem
  • git
  • GitHub
  • fetch / documentation 类 MCP 服务器
  • 一个范围很窄的内部 API

不适合一上来就接入的服务器：

  • 巨型业务系统，动作很多且带破坏性，还没有任何过滤
  • 任何你自己都还没理解清楚、无法约束范围的系统

相关文档​