Skip to main content

使用 MCP 与 Hermes

本指南聚焦一件事：如何把 MCP 服务器真正接入 Hermes，并在日常工作中稳定、安全地用起来。

如果功能页解释的是 MCP 是什么，那么这一页更关心“第一台服务器怎么接”“工具怎么筛”“上线前怎么控风险”。

如需完整功能参考，请参阅 MCP 集成 和 MCP 配置参考。

什么时候适合用 MCP​

当你遇到下面这些场景时，MCP 通常很合适：

  • 已经有现成的 MCP 服务器，不想再单独开发原生 Hermes 工具
  • 想把 Hermes 接到数据库、内部 API、文件系统或团队平台
  • 需要用“服务器”为单位控制工具暴露范围
  • 希望把外部系统接入 Hermes，但又不想改 Hermes 核心代码

不太适合用 MCP 的情况通常是：

  • 内置工具已经足够完成任务
  • 只需要一个非常窄的小集成，用原生工具会更简单
  • 某个 MCP 服务器暴露了过多危险能力，而你暂时还没准备好做筛选

一个简单的心智模型​

可以把 MCP 理解成一层工具适配层：

  • Hermes 仍然是做决策的代理
  • MCP 服务器负责暴露工具、资源或提示词
  • Hermes 在启动或重载时发现这些能力
  • 模型把它们当成普通工具来调用
  • 你通过配置决定“哪些能力能被看见”

真正高质量的 MCP 使用方式，不是“把所有东西都接进来”，而是“只接正确的服务器，并只暴露必要的表面”。

第一步：先接一台安全的服务器​

最好的起点通常是单台、只读或低风险的服务器。

例如，先只开放某个项目目录的文件系统访问：

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 工具
  • 修改配置后使用 /reload-mcp
  • 如果连接失败，去日志里看报错

一个很好用的测试提示是：

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

第三步：尽早做工具筛选​

不要默认把整台服务器的全部能力都暴露给模型。多数情况下，应该在接入时就开始筛选。

白名单方式​

如果你已经知道只想开放哪些工具，优先用 include：

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

这种方式最稳，因为模型根本看不到你没有列出的工具。

黑名单方式​

如果服务器本身很有用，但其中只有少数几个危险工具需要禁掉，可以用 exclude：

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

经验上，面向生产系统时更推荐白名单；黑名单更适合你已经充分了解该服务器能力时使用。

第四步：资源和提示词也要按需开放​

除了工具，许多 MCP 服务器还支持资源和提示词。默认并不是所有场景都需要它们。

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      include: []
      resources: true
      prompts: false

如果你只需要资源检索，不需要实际工具调用，就可以把工具表面尽量缩小。

第五步：重载配置，而不是来回重启​

修改 config.yaml 后，通常不需要重启整个会话，直接在 Hermes 中执行：

/reload-mcp

这通常是调试 MCP 接入时最高频的动作。

常见的安全做法​

从低风险服务器开始​

推荐的接入顺序通常是：

  1. 文件系统只读或受限目录
  2. 文档 / 知识库类服务器
  3. GitHub、Issue、检索类服务器
  4. 数据库、支付、生产控制系统

生产能力默认最小暴露​

如果服务器可以：

  • 删除数据
  • 修改生产配置
  • 调用真实外部 API
  • 操作金钱、账户或部署环境

那就优先只开放只读工具，或者只开放经过白名单筛选后的极少数写操作。

把权限控制前置​

MCP 不是权限系统本身。真正的权限边界仍应在服务器端、令牌作用域和后端系统里控制好。Hermes 的筛选配置是重要的一层，但不应该是唯一的一层。

几种常见工作流​

文档和知识库检索​

适合：

  • 内部文档
  • API 手册
  • 知识库
  • 项目规范

典型用法是接一个文档类服务器，然后让 Hermes 在回答问题时优先引用这些资源。

开发辅助​

适合：

  • GitHub
  • 文件系统
  • 内部代码索引
  • 研发平台 API

这类组合通常很适合代码审查、Issue 跟进、仓库调研和变更追踪。

内部业务系统​

适合：

  • 数据库查询
  • CRM / ERP
  • 内部服务 API

但这类系统风险也最高，建议先做白名单，再逐步放开。

一个实用配置习惯​

不要一开始就在同一个 Hermes 实例里塞很多台 MCP 服务器。更稳的做法通常是：

  1. 先接一台服务器
  2. 验证能否连接、发现和调用
  3. 做工具筛选
  4. 跑几个真实任务
  5. 再接下一台

这样出了问题更容易定位，也不容易把模型一下子暴露在过大的工具表面前。

排错建议​

如果 MCP 看起来没生效，可以按这个顺序检查：

  1. command / args 或 url 是否正确
  2. 所需环境变量、Header 或认证是否存在
  3. /reload-mcp 后有没有错误输出
  4. 工具是不是被 include / exclude 筛掉了
  5. 服务器是否真的支持 resources 或 prompts
  6. 日志里有没有连接超时、启动失败或权限错误

一个简单的使用原则​

把 MCP 当成“把外部能力安全地接进 Hermes”的方式，而不是“越多越好”的插件槽。

多数时候，真正决定体验的不是你接了多少服务器，而是：

  • 接入的服务器是否对
  • 暴露的工具是否足够小
  • 你的任务是否真的需要它

如果你先把这三件事做好，MCP 通常会非常稳。