Hermes 集成 MCP 最佳实践：安全、可控地把“外部工具”接入 Agent

面向读者：想用 Hermes Agent 接入文件系统、GitHub、内部 API 等外部能力，但又希望可控、安全、可维护。
目标：用一条清晰路径，从 0 跑通 MCP，到能在真实工作流里稳定使用（并避免“工具暴露过大”的坑）。

TL;DR（先记住这三句话）

  1. MCP 是 Agent 世界的“USB 标准”：Hermes（Agent）通过 MCP 连接外部系统，像调用普通工具一样调用 MCP server 暴露的能力。

  2. 最佳实践不是“连接一切”，而是：只连接正确的内容，并且只暴露最小但够用的能力范围。

  3. 过滤要从第一天就做：尤其是 GitHub、支付、客户数据、内部系统等敏感场景，优先使用白名单（tools.include）。

参考：官方指南《使用 MCP 与 Hermes》：https://hermesagent.org.cn/docs/guides/use-mcp-with-hermes

0. 什么时候该用 / 不该用 MCP？

适合用 MCP 的情况

  • 已经存在 MCP 形式的工具（server），你不想再构建原生 Hermes 工具

  • 你希望 Hermes 通过干净的 RPC 层与本地或远程系统交互（而不是把逻辑塞进 Agent 侧）

  • 你需要“按 server 维度”的细粒度暴露控制（哪些工具可见、哪些功能禁用）

  • 你要接内部 API、数据库、公司系统，但不想改 Hermes 核心

不建议用 MCP 的情况

  • Hermes 内置工具已能很好完成任务

  • server 暴露了大量危险工具，而你暂时没有准备做过滤/审计

  • 你只需要一个非常狭窄的集成（原生工具可能更简单、更安全）

1. 思维模型：把 MCP 当“适配层”

  • Hermes Agent：负责推理、计划、选择工具、推进任务

  • MCP Server：提供外部工具（文件、GitHub、数据库、内部系统等）

  • Hermes 启动/重载时发现这些工具，模型可像使用普通工具一样使用它们

  • 你负责控制每个 server 的暴露面（最关键的一点）

好的 MCP 接入 = 连接正确的系统 + 严格限制暴露面 + 可观测（可验证、可排错）。

2. 第一步：安装 MCP 支持（一次搞定）

如果你是通过 Hermes 标准安装脚本安装的，通常已经包含 MCP 支持（安装器会安装带额外组件的依赖）。

如果你需要手动补装（在 Hermes 源码/安装目录中执行）：

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

补充建议：

  • npm 系 server：确保本机有 Node.js，且 npx 可用

  • Python MCP server：很多场景 uvx 是一个不错的默认选择

3. 第二步：先接一个“最安全”的 MCP server（从 filesystem 开始）

最佳实践：从单一、低风险、可控范围的小 server 起步。最经典的是“只给一个项目目录的文件系统访问”。

在 Hermes 配置文件中加入一个 MCP server（示例：project_fs）：

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

关键点（也是最佳实践）：

  • 路径要尽量窄：给 /home/user/my-project，不要给整个 /home/user

  • 先别急着加 GitHub/数据库/内部系统：先把“接入—验证—过滤—排错”跑通

然后启动 Hermes：

hermes chat

你可以直接问一个具体问题来验证文件系统工具是否工作：

Inspect this project and summarize the repo layout.

4. 第三步：验证 MCP 已加载（不要“凭感觉”）

你可以用以下方式验证 MCP server 是否真正加载成功：

  1. 启动横幅/状态信息：Hermes 启动时通常会显示 MCP 集成状态

  2. 直接问当前可用工具：

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

  1. 配置改完后使用：

/reload-mcp

  1. 如果加载失败或工具缺失：看日志（很多问题是路径/依赖/鉴权导致的连接失败）

5. 第四步：立刻开始过滤（强烈建议从白名单起步）

现实里很多 server 的工具集非常“大”。如果你不从第一天就过滤，后面会很难收口。

Hermes 对 MCP 暴露面的过滤分两类：

  1. server 原生工具：用 tools.include（白名单）或 tools.exclude（黑名单）

  2. Hermes 额外的“实用封装器”：是否暴露 resources 和 prompts

5.1 白名单（推荐）：只允许需要的工具

以 GitHub MCP server 为例（严格白名单）：

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

为什么推荐白名单？

  • 对金融/客户数据/具有破坏性的系统，这是默认更安全的策略

  • 你可以从“最小集合”开始，等确实需要再扩容（而不是反过来删不干净）

5.2 黑名单：屏蔽危险操作（适合“工具集很大但你已知危险点”）

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

黑名单的风险：你永远不知道是不是漏掉了“新的危险工具”。敏感系统仍优先白名单。

5.3 同时禁用 prompts / resources（避免模型去“浏览知识资产”）

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

说明：你可能会看到 list_resources/read_resource、list_prompts/get_prompt 这类封装器。只有当你的配置允许且 server 会话支持时才会出现；Hermes 不会假装 server 支持它实际上不支持的能力。

6. 常见落地模式（可直接套用）

模式 1：本地项目助手（最常用）

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 问题处理助手（建议默认白名单 + 关 prompts/resources）

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.

模式 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.

这种场景里：严格白名单远优于排除列表。

7. 端到端示例：GitHub + filesystem 的“可控扩展”流程

这是一个很实用的上线方式：先最小可用，再按需求扩容。

阶段 1：只接 GitHub + 严格白名单

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，再把 update_issue 加进 include：

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

然后重载：

/reload-mcp

阶段 3：添加 filesystem，实现跨系统工作流

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 先检查本地，再去 GitHub 创建结果）：

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

这就是 MCP 的强大之处：无需修改 Hermes 核心，就能把多个系统串成一个工作流。

8. 安全使用建议（Best Practices 核心）

  1. 对危险系统优先使用允许列表（tools.include）
    金融、面向客户、可破坏数据的系统：从最小集合开始，不要“先全开再慢慢关”。

  2. 将 server 作用域限制到最小

    • 文件系统 server：只指向单个项目目录

    • Git server：只指向单个仓库

    • 内部 API：尽量只开放“读为主”的工具（或专门拆出只读 server）

  3. 禁用未用的 prompts/resources
    不需要模型去浏览“资源/提示”时，直接关掉：

tools:
  resources: false
  prompts: false

  1. 所有配置变更后都要 /reload-mcp
    include/exclude、启用标志、prompts/resources 开关、认证头/环境变量等变更后都要重载。

9. 按症状排查（最常见的三类问题）

9.1 “服务器已连接，但我预期的工具缺失”

排查清单：

  • 是否被 tools.include 过滤掉了（最常见）

  • 是否被 tools.exclude 排除了

  • 是否通过 resources: false 或 prompts: false 禁用了封装器

  • server 本身是否不支持 resources/prompts（Hermes 不会假装支持）

9.2 “服务器已配置，但没有任何内容加载”

排查清单：

  • 配置里是否留下 enabled: false

  • 命令/依赖是否可用（npx / Node.js / uvx 等）

  • 鉴权环境变量是否生效（token 是否配置/权限是否足够）

  • 看日志：连接失败通常会给出更直接的原因

9.3 “工具能用，但我越来越不敢让它跑”

这是典型的“暴露面过大”：

  • 把当前 server 的工具集收敛到白名单

  • 拆分 server：只读 vs 可写、低风险 vs 高风险

  • 用更窄的作用域（路径、仓库、租户、项目）

10. 一份可执行的落地检查表

  • 先用 filesystem server 在单一目录跑通

  • 验证工具已加载（启动信息 / 询问工具列表 / /reload-mcp）

  • 对敏感系统使用 tools.include 白名单

  • 不需要就关掉 prompts/resources

  • 每次变更后 /reload-mcp

  • 用“窄作用域 + 可观测 + 最小权限”作为长期默认

# 运维
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

Google能索引，AI却抓不到

很多技术团队有个错觉：只要Google能正常收录，内容就没问题。但现实是，你的页面在Google搜索结果里好好的，在ChatGPT、Perplexity、Claude的答案里却像从未存在过一样。

avatar MCP技术社区
cover

Windows 下部署 New API 中转站全过程实录（含 6 个真实踩坑）

avatar MCP技术社区

初识智能体

在过去两年中，几乎所有人都体验过大语言模型（如 ChatGPT、Claude、DeepSeek）的强大能力：写周报、润色邮件、解答编程疑难。被动响应：你问一句，它答一句。如果你的 Prompt 没有写清楚约束条件，它无法主动追问或修正目标。知行脱节：大模型能用流畅的文字告诉你“如何部署一个高可用 K8s 集群”，但它无法替你登录服务器敲下命令、查看报错日志并自动回滚。信息孤岛：大模型的知识止步于预

avatar MCP技术社区