Hermes Agent 学习笔记 09：MCP 集成，让 Agent 连接外部工具生态

1. 为什么需要 MCP？

前面几期已经学习了 Hermes Agent 的几个核心模块。

Tools 让 Hermes 能读取文件、执行命令、搜索网页和调用浏览器；

Memory 让 Hermes 能记住用户偏好和长期项目背景；

Skills 让 Hermes 能沉淀做事流程；

Messaging Gateway 让 Hermes 能进入 Telegram、Discord、Slack、Email 等平台；

Cron 让 Hermes 能按时间主动执行任务。

到这里，Hermes 已经像一个比较完整的长期 Agent 了。

但还有一个问题：如果我想让 Hermes 使用外部系统里的工具怎么办？

例如：

让 Hermes 操作 GitHub issue 和 PR；
让 Hermes 查询数据库；
让 Hermes 读取公司内部文档；
让 Hermes 操作浏览器自动化服务；
让 Hermes 查询向量数据库；
让 Hermes 调用某个内部 API；
让 Hermes 接入项目管理工具 Linear、Jira 或 Notion。

如果每接入一个系统，都要在 Hermes 本体里重新写一个原生 tool，那么开发成本会非常高。更麻烦的是，不同 Agent 框架可能都要重复写一遍同样的集成。

这就是 MCP 要解决的问题。

MCP 的核心思想是：不要让每个 Agent 都为每个工具单独写一套适配代码，而是用一种标准协议，把外部工具以统一方式暴露给 Agent。

简单来说：

没有 MCP：每个 Agent 单独适配每个工具。
有了 MCP：工具以 MCP server 形式暴露，Agent 作为 MCP client 接入。

这让工具生态从"各接各的"变成"按标准连接"。

2. MCP 是什么？

MCP 全称是 Model Context Protocol，可以理解为一种让 AI Agent 连接外部工具、资源和数据源的协议。

在 MCP 架构中，通常有三个角色：

MCP Host
MCP Client
MCP Server

在 Hermes Agent 的场景下，可以这样理解：

Hermes Agent 是使用工具的 Agent 应用；
Hermes 内部的 MCP client 负责连接 MCP server；
MCP server 负责暴露外部工具、资源或提示词。

例如，一个 GitHub MCP server 可以向 Hermes 暴露这些能力：

列出 issue；
创建 issue；
查看 pull request；
搜索代码；
读取仓库文件；
添加评论。

Hermes 不需要自己原生实现全部 GitHub API，而是通过 MCP client 发现 GitHub MCP server 暴露出来的工具，然后像调用普通工具一样调用它们。

这就是 MCP 的核心价值：

把外部系统能力包装成标准化工具，让 Agent 可以发现、选择和调用。

3. MCP 和 Hermes 内置 Tools 的区别

第四期讲过 Hermes 的工具调用系统。那 MCP 工具和 Hermes 内置工具有什么区别？

可以这样理解：

内置 Tools：Hermes 自己提供的基础能力。
MCP Tools：外部 MCP server 提供的扩展能力。

例如，Hermes 内置工具可能包括：

读取文件；
写入文件；
执行 shell；
搜索网页；
调用浏览器；
管理记忆；
发送消息。

这些能力属于 Hermes 的核心能力集。

而 MCP 工具则来自外部系统，例如：

GitHub issue 工具；
数据库查询工具；
Notion 页面工具；
Linear 项目管理工具；
Slack 工作区工具；
内部业务 API 工具。

所以，MCP 不是替代 Hermes 的内置工具，而是扩展 Hermes 的工具边界。

可以用一句话概括：

内置 Tools 解决通用基础能力；
MCP 解决外部系统集成能力。

4. MCP 和 Skills 的区别

MCP 也容易和 Skills 混淆。

第六期讲过，Skill 是 Agent 的"过程记忆"，它告诉 Agent 遇到某类任务应该怎么做。

而 MCP 是外部工具协议，它告诉 Agent 可以调用哪些外部能力。

例如：

GitHub MCP server 提供 create_issue 工具。

这是 MCP 工具。

而一个 GitHub PR workflow skill 可能告诉 Agent：

1. 先查看当前分支；
2. 再读取 git diff；
3. 再运行测试；
4. 然后创建 PR；
5. 最后在 PR 描述中写清楚修改内容和验证方式。

这是 Skill。

二者可以配合使用：

MCP 提供"能操作 GitHub"的能力；
Skill 提供"应该如何规范地操作 GitHub"的流程。

这就是 MCP 和 Skills 的关系：

MCP 负责连接工具；
Skills 负责组织流程。

5. MCP 和 Cron 的关系

第八期讲过 Cron 定时任务。Cron 负责在特定时间触发 Agent 任务。

如果 Cron 任务需要访问外部系统，MCP 就很有价值。

例如：

每天上午 9 点，通过 GitHub MCP 查询项目 issue 和 PR，生成项目日报。

这个任务背后是：

Cron：每天上午 9 点触发；
MCP：连接 GitHub 并查询 issue/PR；
Agent：理解、筛选、总结；
Gateway：把结果发到 Telegram 或 Slack。

所以，MCP 可以成为 Cron 自动化任务中的外部系统接口。

这也说明 Hermes 的这些模块不是孤立的，而是可以组合：

MCP + Cron：定时访问外部工具；
MCP + Skills：按固定流程使用外部工具；
MCP + Gateway：从消息平台远程触发外部工具操作；
MCP + Memory：结合长期背景判断工具结果。

6. MCP 的基本工作流程

Hermes 使用 MCP 的基本流程可以拆成几步：

1. 用户在 Hermes 配置文件中添加 MCP server；
2. Hermes 启动时连接这些 server；
3. MCP server 返回自己支持的工具、资源或 prompts；
4. Hermes 自动发现并注册这些能力；
5. 模型在对话中看到这些工具；
6. 当任务需要时，模型选择合适的 MCP 工具；
7. Hermes 把调用请求发送给对应 MCP server；
8. MCP server 执行工具并返回结果；
9. Hermes 把结果交给模型继续推理。

这个流程和内置工具调用很像。区别在于，内置工具的执行逻辑在 Hermes 内部，而 MCP 工具的执行逻辑在外部 server 中。

也就是说，Hermes 不需要知道 GitHub API 细节，只需要知道 MCP server 暴露了哪些工具、每个工具需要哪些参数、调用后会返回什么结果。

7. 本地 stdio MCP server 和远程 HTTP MCP server

Hermes 支持两类常见 MCP server：

本地 stdio server；
远程 HTTP server。

7.1 本地 stdio server

本地 stdio server 是通过本地命令启动的 MCP server。

例如：

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

这个配置的意思是：Hermes 启动时通过 npx 运行一个 filesystem MCP server，并把 /home/user/projects 暴露给这个 server。

这种方式适合本地工具，例如：

文件系统；
本地数据库；
本地浏览器工具；
本地脚本封装；
开发环境工具。

优点是简单、直接、适合个人开发环境。

缺点是它依赖本机环境，如果 Node、Python、依赖包或路径有问题，就可能启动失败。

7.2 远程 HTTP MCP server

远程 HTTP server 是通过 URL 连接的 MCP server。

例如：

mcp_servers:
  internal_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

这种方式适合企业内部服务、云端工具、远程 API、托管型 MCP 服务等。

优点是服务可以集中部署、统一维护，也更适合团队共享。

缺点是需要处理认证、网络、TLS、超时和权限问题。

可以简单理解：

stdio MCP：本机启动，适合本地工具。
HTTP MCP：远程连接，适合服务化工具。

8. 在 Hermes 中配置 MCP server

Hermes 的 MCP 配置通常写在：

~/.hermes/config.yaml

一个最简单的配置示例是：

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

配置完成后启动 Hermes：

hermes chat

Hermes 会在启动时发现这个 MCP server 暴露的工具，并把它们注册到工具系统中。

之后你就可以问：

请列出 /home/user/projects 目录下的项目，并总结它们的大致结构。

如果 MCP server 正常启动，Hermes 就可以像使用普通工具一样使用它提供的能力。

不过，这里要特别注意路径边界。比如 filesystem MCP server 暴露的是 /home/user/projects，就不要随便把整个 / 或用户 home 目录全部暴露给 Agent。

安全原则是：

只暴露任务需要的目录；
不要暴露整个系统；
不要暴露包含密钥、Token、SSH key 的目录。

9. Hermes MCP Catalog：从人工配置到一键安装

除了手动编辑配置文件，Hermes 还提供 MCP catalog。

可以运行：

hermes mcp

进入交互式选择器。

也可以查看可用条目：

hermes mcp catalog

安装某个 catalog 条目：

hermes mcp install github

或者：

hermes mcp install n8n

Catalog 的意义是降低 MCP 接入门槛。用户不需要自己从零查找每个 MCP server 的命令、参数和环境变量，而是可以通过 Hermes 提供的条目进行安装和配置。

不过，catalog 不是说"所有都应该安装"。相反，MCP server 应该按需安装。

因为每多一个 MCP server，就意味着：

更多工具暴露给 Agent；
更多上下文 schema；
更多凭据和权限；
更多潜在安全风险；
更多排错成本。

所以我的建议是：

先只安装一个最需要的 MCP；
确认能用；
再逐步扩展；
不要一次装一堆。

10. MCP 工具命名：为什么会出现 mcp_xxx_xxx？

Hermes 会把 MCP server 中暴露的工具注册成模型可见工具。为了避免和内置工具重名，通常会加上前缀。

例如，一个名为 github 的 MCP server 暴露了 create_issue 工具，注册到 Hermes 后可能会变成：

mcp_github_create_issue

如果 server 名或工具名里有连字符、点号等不适合作为函数名的字符，Hermes 会进行名称清洗，例如把 - 和 . 替换为 _。

例如：

server 名：my-api
工具名：list-items.v2
注册名：mcp_my_api_list_items_v2

这个机制有两个好处：

避免工具重名；
保证工具名适合模型函数调用接口。

但配置 include/exclude 过滤时要注意：过滤通常使用 MCP server 原始工具名，而不是清洗后的 Hermes 注册名。

11. 工具过滤：不要把所有 MCP 工具都暴露出来

MCP server 可能暴露很多工具，但不代表 Hermes 都应该看到。

例如，一个 GitHub MCP server 可能有：

list_issues；
create_issue；
update_issue；
delete_issue；
create_pull_request；
merge_pull_request；
search_code。

如果你只是想让 Hermes 总结 issue，就没必要暴露 merge、delete 这类高风险工具。

Hermes 支持 include 和 exclude 过滤。

11.1 include：白名单

只允许指定工具：

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]

这种方式最安全，因为没有列出的工具都不会注册。

11.2 exclude：黑名单

暴露大部分工具，但排除危险工具：

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

这种方式适合你基本信任该 server，只想屏蔽少数高风险工具。

11.3 include 优先

如果 include 和 exclude 同时出现，include 优先。

也就是说，只要设置了 include，Hermes 只注册 include 中列出的工具。

我的建议是：

个人学习可以用 include；
生产或团队环境强烈建议用 include；
少用"默认全开放再 exclude 少数工具"的方式。

因为你可能并不知道某个 MCP server 未来更新后会新增哪些工具。如果默认全部暴露，新增工具也可能被暴露出来。

12. Resources 和 Prompts：MCP 不只有 Tools

MCP server 不一定只暴露 tools，也可能暴露：

resources；
prompts。

Resources 可以理解为外部资源，例如文档、文件、数据库记录、配置项等。

Prompts 可以理解为 server 提供的可复用提示模板。

Hermes 可以为这些能力注册 utility wrappers，例如：

list_resources；
read_resource；
list_prompts；
get_prompt。

如果不需要这些能力，可以在配置中关闭：

tools:
  resources: false
  prompts: false

例如，对于 GitHub issue 操作场景，如果你只需要 issue 工具，不需要额外 resources 和 prompts，就可以关闭它们，减少工具暴露面。

这也是 MCP 安全配置的一部分：

不用的能力就不要启用。

13. Remote MCP 的认证方式

远程 MCP server 经常涉及认证。

常见方式包括：

HTTP headers；
Bearer token；
OAuth；
mTLS 客户端证书。

最简单的是在 headers 中配置 token：

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

如果 server 支持 OAuth，可以设置：

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

这种情况下，Hermes 会走 OAuth 授权流程，并把 token 保存在本地 token 目录中，后续会话复用。

对于企业内部服务，也可能使用 mTLS：

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/secrets/mcp-client.pem"

这些认证方式说明，MCP 不是简单"把工具连上就完事"。真实场景中，权限、凭据、证书和 token 管理都很重要。

14. Tool Search：MCP 工具多了以后怎么办？

MCP 最大的好处是扩展工具生态，但工具太多也会带来问题。

每个工具都有名称、描述、参数 schema。模型每一轮都要看到这些工具信息，才能决定是否调用它们。如果 MCP server 很多，工具 schema 会占用大量上下文窗口。

这会带来几个问题：

上下文成本变高；
模型注意力被无关工具干扰；
响应变慢；
工具选择更困难；
prompt cache 更容易失效。

Hermes 的 Tool Search 就是为了解决这个问题。

Tool Search 是一种 progressive disclosure 机制。简单理解：

平时不把所有 MCP 工具完整 schema 都塞给模型；
模型需要时先搜索工具；
再加载某个工具的完整 schema；
最后调用该工具。

它会把大量 MCP 工具替换成三个桥接工具：

tool_search：搜索工具；
tool_describe：查看某个工具的完整 schema；
tool_call：调用这个工具。

例如模型想创建 GitHub issue，可能会先：

tool_search("create github issue")

然后：

tool_describe("mcp_github_create_issue")

最后：

tool_call("mcp_github_create_issue", {...})

这样做的意义是：当工具很多时，不需要每轮都把所有工具完整描述给模型。

不过 Tool Search 也不是没有代价。它可能增加一次搜索和描述工具的额外步骤。因此，在工具很少时没必要强行开启；在 MCP 工具很多时才更有价值。

15. MCP 的安全问题

MCP 很强大，但安全风险也很明显。

因为 MCP 本质上是把外部系统能力暴露给 Agent。如果配置不当，Agent 可能获得过多权限。

常见风险包括：

暴露了不该暴露的工具；
把高权限 token 给了 MCP server；
没有限制文件系统路径；
远程 MCP server 不可信；
工具描述被恶意设计；
工具返回内容诱导模型执行危险操作；
生产环境 API 被 Agent 误调用；
数据库写操作没有人工确认；
支付、退款、删除、合并 PR 等高风险操作没有限制。

所以使用 MCP 时，至少要遵守几个原则。

第一，只连接可信 MCP server。

不要随便安装来源不明的 MCP server。

第二，只暴露需要的工具。

优先使用 include 白名单，而不是默认全开放。

第三，使用最小权限凭据。

GitHub token 只给需要的 repo 权限；数据库账号只读就不要给写权限；内部 API token 不要给管理员权限。

第四，限制文件系统范围。

filesystem MCP 不要直接暴露整个 home 目录，更不要暴露 .ssh、.config、密钥目录。

第五，高风险操作保留人工确认。

删除、付款、退款、部署、合并、发布都应该有确认环节。

第六，区分学习环境和生产环境。

初学时尽量使用测试仓库、测试数据库、测试账号。

16. 一个适合初学者的 MCP 学习路线

我认为初学 Hermes MCP 不应该一开始就接很多复杂服务。

更好的路线是：

第一步：先理解 MCP 和内置工具的区别；
第二步：配置一个简单 filesystem MCP；
第三步：确认 Hermes 能发现 MCP 工具；
第四步：尝试只读文件操作；
第五步：学习 include/exclude 工具过滤；
第六步：尝试 GitHub MCP，但只开放 list/search/create issue 这类低风险工具；
第七步：学习 Tool Search；
第八步：最后再考虑数据库、企业 API、远程 HTTP MCP。

也就是说，先从低风险、本地、只读场景开始，再逐步进入高权限外部系统。

17. 一个 GitHub MCP 使用场景示例

假设我希望 Hermes 每天总结一个项目的 issue 状态，可以这样设计：

目标：
每天上午 9 点检查 GitHub 仓库中的 open issues 和 pull requests，生成项目状态日报。

MCP：
GitHub MCP server。

工具过滤：
只开放 list_issues、search_code、create_issue、update_issue。
不开放 delete、merge、release、repo admin 等工具。

Cron：
每天上午 9 点触发。

Skill：
绑定 project-status-report skill，规定日报格式。

Gateway：
结果发送到 Telegram home channel。

这就形成了一个组合式工作流：

GitHub MCP 提供外部数据；
Cron 负责定时；
Skill 负责报告流程；
Hermes 负责理解和总结；
Gateway 负责投递。

这个例子很好地体现了 MCP 在 Hermes 中的位置：它不是孤立功能，而是连接外部系统的接口层。

18. MCP 和插件化 Agent 的关系

从更大的角度看，MCP 让 Hermes 更接近一个插件化 Agent 平台。

过去，Agent 如果想访问某个工具，通常要在框架内部写集成代码。这会导致工具能力和 Agent 框架强绑定。

MCP 改变了这个关系：

工具不一定属于 Hermes；
工具可以作为独立 server 存在；
Hermes 只需要通过标准协议连接；
同一个 MCP server 理论上也可以被其他 MCP client 使用。

这让工具生态更模块化。

对于开发者来说，MCP 意味着：

如果你有一个内部系统想给 Agent 使用，不一定要改 Hermes 源码，可以先做一个 MCP server，把系统能力按工具形式暴露出来。

对于用户来说，MCP 意味着：

Hermes 的能力不再局限于官方内置工具，而是可以连接越来越多外部工具生态。

19. MCP 的局限

虽然 MCP 很有价值，但也不能把它神化。

MCP 只是连接协议，不自动保证工具好用、安全或可靠。

一个 MCP server 可能存在这些问题：

工具描述写得不清楚；
参数 schema 不合理；
错误信息不明确；
权限边界不清楚；
服务不稳定；
依赖安装困难；
版本更新破坏兼容；
返回结果太长；
没有审计日志；
没有细粒度授权；
没有防 prompt injection 设计。

也就是说：

MCP 解决"怎么连接"的问题；
不自动解决"连接后是否安全可靠"的问题。

所以在生产环境中，MCP server 仍然需要工程化治理，包括认证、授权、日志、速率限制、错误处理、权限隔离和人工确认。

20. 对 Hermes MCP 的理解

学完 MCP 后，我对 Hermes Agent 的整体架构有了进一步理解。

Hermes 本身提供了内置工具、memory、skills、cron、gateway 等能力。但一个长期 Agent 想进入真实工作流，必须连接大量外部系统。MCP 正是这个连接层。

它让 Hermes 可以接入 GitHub、数据库、文件系统、浏览器栈、内部 API 等外部能力，同时通过工具过滤、认证配置、Tool Search 和 per-server 配置控制暴露范围。

因此，MCP 在 Hermes 中的位置可以概括为：

MCP 是 Hermes 连接外部工具生态的标准化接口。

它和前面几个模块的关系是：

Tools：Hermes 能做什么；
MCP：Hermes 能连接哪些外部工具；
Skills：Hermes 应该如何使用这些工具；
Cron：Hermes 什么时候使用这些工具；
Gateway：用户从哪里触发和接收结果；
Memory：Hermes 如何结合长期背景理解工具结果。

21. 小结

这一期主要学习了 Hermes Agent 的 MCP 集成。

我的理解是，MCP 解决的是 Agent 工具生态的标准化连接问题。它让 Hermes 不必为每个外部系统都写原生工具，而是可以通过 MCP client 连接外部 MCP server，并自动发现和注册 server 暴露的 tools、resources 和 prompts。

Hermes 支持本地 stdio MCP server，也支持远程 HTTP MCP server；支持 MCP catalog 一键安装；支持 include/exclude 工具过滤；支持 resources/prompts utility wrappers；支持 OAuth、headers、mTLS 等认证方式；也支持 Tool Search 来缓解大量 MCP 工具占用上下文的问题。

但 MCP 的能力越强，安全边界越重要。真正使用时，要坚持最小权限、白名单过滤、只连接可信 server、限制文件系统范围，并对高风险操作保留人工确认。

下一期，我将进入 Hermes Agent 的源码结构和整体架构总结，梳理 Agent 主循环、模型调用层、工具层、Memory 层、Skills 层、Gateway 层、Cron 调度层和 MCP 接入层之间的关系。