使用 MCP

> 📖 本文档翻译自 Hermes Agent 官方文档 > 最后更新：2026-04-16

---

在 Hermes 中使用 MCP

本指南展示如何在实际日常工作流中使用 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

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

如果你后来也需要更新 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
• 从最小的集合开始

禁用未使用的工具

如果你不希望模型浏览服务器提供的资源/提示，关闭它们：

tools:
  resources: false
  prompts: false

保持服务器范围狭窄

示例：

• 文件系统服务器仅限一个项目目录，而非整个主目录
• git 服务器仅指向一个仓库
• 内部 API 服务器默认以读为主的工具暴露

配置更改后重新加载

/reload-mcp

在更改以下内容后执行此操作：

• include/exclude 列表
• 启用标志
• resources/prompts 开关
• 认证头 / 环境变量

按症状排查故障

"服务器连接了但我期望的工具缺失"

可能的原因：

• 被 tools.include 过滤了
• 被 tools.exclude 排除了
• 工具包装器通过 resources: false 或 prompts: false 被禁用
• 服务器实际不支持资源/提示

"服务器已配置但什么都没有加载"

检查：

• 配置中没有遗留 enabled: false
• 命令/运行时存在（npx、uvx 等）
• HTTP 端点可达
• 认证环境变量或头信息正确

"为什么我看到的工具比 MCP 服务器声明的少？"

因为 Hermes 现在遵循你的逐服务器策略和能力感知注册。这是预期行为，通常是理想的。

"如何在不删除配置的情况下移除 MCP 服务器？"

使用：

enabled: false

这会保留配置但阻止连接和注册。

推荐的首个 MCP 设置

大多数用户的首选服务器：

• filesystem
• git
• GitHub
• fetch / 文档 MCP 服务器
• 一个范围较窄的内部 API

不太好的首选服务器：

• 拥有大量破坏性操作且没有过滤的庞大业务系统
• 任何你还不够了解以至于无法约束的东西

相关内容 docs

• MCP (Model Context Protocol)
• 常见问题
• Slash Commands