一、先说结论：MCP 是 Hermes 的“外部工具总线”

如果把 Hermes Agent 比作一个会思考、会拆任务的“项目经理”，那么 Tools 就是它能调动的“员工”，而 MCP 就是把外部员工接进团队的统一门禁和工牌系统。没有 MCP，每接一个系统都要在 Hermes 内部写一套专用工具；有了 MCP，只要外部系统按 MCP 规范暴露能力，Hermes 就能在启动时发现它们、注册它们，并让模型在合适时机调用它们。

用更直白的话说，MCP 解决的是三个问题：

1. 外部工具怎么被 Hermes 发现？

2. 外部工具怎么变成模型可调用的 tool？

3. 调用外部工具时，鉴权、超时、过滤、安全、结果回填怎么管理？

这也是为什么 MCP 在 Agent 工程里越来越重要：模型本身不会访问 GitHub、数据库、工单系统、公司 API，它必须通过工具层间接行动。Hermes 的 MCP 设计，就是把这个工具层做成可扩展、可过滤、可复用的协议化接入层。

二、MCP 在 Hermes 里的位置：不是模型能力，而是运行时能力

很多人容易把 MCP 理解成“某种插件”。这个说法不完全准确。MCP 更像一个“工具协议”，它规定了客户端和服务器之间如何发现工具、描述工具、调用工具、返回结果。Hermes 在这个体系里有两个身份。

第一个身份是 MCP Client。Hermes 作为客户端，连接 GitHub、文件系统、数据库、公司内部 API 等 MCP Server。外部 MCP Server 把自己的能力描述给 Hermes，Hermes 再把这些能力注册为可调用工具。

第二个身份是 MCP Server。Hermes 也可以通过 `hermes mcp serve` 暴露自己的能力，让 Claude Code、Cursor、Codex 或其他 MCP Client 使用 Hermes 的跨平台消息能力，比如读取会话、发送消息、处理权限审批等。

这两个身份放在一起看，Hermes 就不只是“会调用工具的 Agent”，而是一个能连接外部工具生态、也能被其他 Agent 调用的 Agent 基础设施。

三、外部工具接入 Hermes 的完整链路

一次外部工具接入，大致分成七步。第一步，你在 `~/.hermes/config.yaml` 里配置 MCP Server。第二步，Hermes 启动时读取 `mcp_servers` 配置并连接对应服务器。第三步，Hermes 向 MCP Server 拉取工具列表。第四步，Hermes 把工具注册到自己的普通 Tool Registry。第五步，当用户任务需要外部能力时，模型在可用工具列表中选择相应 MCP 工具。第六步，Hermes MCP Runtime 代替模型去调用外部 Server。第七步，工具结果回到 Hermes，上下文更新，模型继续推理或输出答案。

这里最关键的一点是：模型并没有真正“直连数据库”或“直连 GitHub”。模型只是产生 tool_call。真正的连接、鉴权、超时、错误处理、日志、过滤、结果封装，都由 Hermes 的 MCP 层处理。

四、两种 MCP Server：stdio 和 HTTP

Hermes 官方文档把 MCP Server 分成两类：stdio server 和 HTTP server。

stdio server 是本地子进程。比如通过 `npx` 启动一个文件系统 MCP Server，Hermes 和它通过 stdin/stdout 通信。它适合本机工具、本地文件系统、本地 CLI、低延迟项目资源。

HTTP server 是远程端点。比如公司内部暴露了一个 `https://mcp.internal.example.com`，Hermes 通过 URL 和 headers 连接它。它适合企业内部 API、云端 MCP 平台、SaaS 服务、跨网络共享能力。

可以这样选择：

类型	适合场景	典型配置
stdio	本地工具、本地文件系统、npx 启动服务、低延迟资源	command + args + env
HTTP	远程服务、内部 API、SaaS、云端 MCP 平台	url + headers

五、配置不是只写地址，还要控制权限和暴露面

Hermes 从 `~/.hermes/config.yaml` 的 `mcp_servers` 下读取配置。一个最小的 stdio 配置可以只包含 command 和 args；一个最小的 HTTP 配置可以只包含 url 和 headers。但在真实项目里，只写连接信息远远不够。

建议把 MCP 配置拆成三类理解：

1. 连接信息：stdio 用 command、args、env；HTTP 用 url、headers。

2. 运行控制：timeout、connect_timeout、enabled、supports_parallel_tool_calls。

3. 暴露面控制：tools.include、tools.exclude、tools.resources、tools.prompts、sampling.enabled。

示例：只暴露 GitHub issue 相关能力，不暴露 prompt/resource 包装能力。

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

这类配置体现了一个很重要的 Agent 工程原则：不是“能接多少工具就接多少”，而是“只把当前任务需要的能力暴露给模型”。

六、Hermes 如何给 MCP 工具命名和注册

MCP Server 原始工具名可能和 Hermes 内置工具重名，也可能不同服务器之间重名。为了解决这个问题，Hermes 会给 MCP 工具加统一前缀：

mcp_<server_name>_<tool_name>

例如 filesystem 服务器的 read_file 会注册成 `mcp_filesystem_read_file`，GitHub 服务器的 create-issue 会注册成 `mcp_github_create_issue`。这样一来，工具来源清晰，命名冲突减少，也方便按 server 级别管理 toolset。

官方文档也提到，实际使用中你通常不需要手动输入这个长工具名；Hermes 会把工具说明和参数 schema 提供给模型，让模型在正常推理中自己选择合适工具。

七、MCP Utility Tools：不只是函数，还有资源和提示词

MCP 不只支持“可调用工具”。当 MCP Server 支持 resources 和 prompts 时，Hermes 还会为它注册一些工具包装：

`list_resources`：列出服务器暴露的资源。

`read_resource`：读取某个资源。

`list_prompts`：列出服务器提供的提示词模板。

`get_prompt`：获取某个提示词模板。

但这些 utility tools 不是无脑注册。Hermes 官方文档说明，只有当 MCP session 实际支持 resource 或 prompt 能力，并且配置允许时，Hermes 才会注册对应包装工具。这样做能避免工具列表膨胀，也能避免把不该暴露的上下文能力交给模型。

八、工具过滤：MCP 安全治理的第一道门

MCP 最容易被低估的一点是：它不仅是扩展能力，也是安全边界。Hermes 支持按 server 做 include 和 exclude。

include 是白名单：只注册列出的工具。exclude 是黑名单：除了列出的危险工具，其他都注册。如果 include 和 exclude 同时出现，官方文档给出的规则是 include 优先。

举个例子，Stripe MCP Server 可能有查询付款、退款、删除客户等能力。如果你只是想让 Agent 分析失败支付原因，就不应该让模型看到 `delete_customer` 或 `refund_payment` 这类高风险工具。

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

这就是企业接入 Agent 时必须坚持的最小权限原则：工具不是越多越好，暴露面越小，Agent 越可控。

九、动态工具发现和 /reload-mcp

Hermes 支持动态工具发现。MCP Server 可以在工具列表变化时发送 `notifications/tools/list_changed` 通知，Hermes 收到后会重新拉取工具列表并更新 registry。

这对企业系统很有用。比如某个数据库 schema 加载后才出现新查询工具，某个服务下线后需要移除工具，或者某个内部平台根据用户权限动态调整能力。

如果你是手动修改 config.yaml，Hermes 也提供 `/reload-mcp`，用于重新加载 MCP Server 并刷新可用工具列表。

十、一次 MCP 工具调用在运行时怎么执行

当模型选择了一个 MCP 工具，Hermes 会经过工具调度层定位工具名，调用 MCP Client，再由 MCP Client 找到对应 server 并发出请求。外部系统执行完之后，结果先回到 MCP Runtime。

这里还有一些容易被忽略的工程细节。Hermes 的源码说明 MCP Client 会处理连接超时、工具调用超时、自动重连、错误信息脱敏、stdio 环境变量过滤、子进程 stderr 日志转储、线程安全等问题。

因此，MCP 工具调用不是“模型直接执行代码”，而是一套受控的运行时流程。模型只决定“调用哪个工具、传什么参数”；Hermes 负责“是否能调用、怎么调用、结果怎么安全地返回”。

十一、并发工具调用：不是所有工具都能并行

默认情况下，MCP 工具是顺序执行的。如果某个 MCP Server 的工具是安全可并发的，比如多个只读查询、互不影响的 API 调用，可以配置 `supports_parallel_tool_calls: true`。

但并发调用不能随便开。只要工具涉及写文件、写数据库、修改订单、更新任务状态，就可能出现读写竞争、状态覆盖、重复执行等问题。官方文档也提醒，只有确认工具之间没有共享状态冲突时，才应该开启并发。

mcp_servers:
docs:
command: "docs-server"
supports_parallel_tool_calls: true

十二、MCP Sampling：让外部 Server 也能请求 LLM 能力

MCP Sampling 是更高级的能力。简单理解：不是只有 Hermes 可以调用 MCP Server，MCP Server 也可以反过来请求 Hermes 帮它做一次 LLM 推理。

例如，一个外部文档处理 MCP Server 可能需要对一段文本做摘要，但它自己没有模型密钥。它可以通过 sampling/createMessage 请求 Hermes 帮忙生成。Hermes 仍然掌握模型选择、超时、限流、最大 token、最大工具轮数等控制权。

对不可信的 MCP Server，建议显式关闭 Sampling：

mcp_servers:
untrusted_server:
url: "https://mcp.example.com"
sampling:
enabled: false

Sampling 的价值在于：外部工具服务可以“借用” Hermes 的 LLM 能力，但权限和成本控制仍然在 Hermes 侧。

十三、Hermes 反过来作为 MCP Server

Hermes 不只是 MCP Client，也可以通过 `hermes mcp serve` 作为 MCP Server。官方文档说，这可以让 Claude Code、Cursor、Codex 或其他 MCP Client 使用 Hermes 的消息能力。

Hermes 作为 MCP Server 时，会暴露会话与消息相关工具，比如列出会话、读取消息历史、获取附件、轮询事件、等待新事件、发送消息、列出频道、查看待审批权限、响应权限审批等。

这意味着：一个 coding agent 可以通过 Hermes 去读 Telegram/Discord/Slack 的消息，也可以把执行结果发回对应平台。Hermes 此时更像一个“跨平台消息总线”。

十四、企业落地案例：把内部工单系统包装成 MCP Server

假设企业有一个内部工单系统，原来只有 REST API。现在想让 Hermes 帮客服或研发自动查工单、总结问题、创建缺陷单。正确做法不是把所有工单 API 都写进 Hermes，也不是直接给 Agent 一个万能 token，而是这样设计：

1. 把工单系统封装成一个 MCP Server，比如 `ticket_mcp`。

2. 只暴露查询、创建草稿、追加备注等低风险工具。

3. 删除工单、批量关闭、退款等高风险动作不暴露或强制人工审批。

4. 在 Hermes config.yaml 里配置 `mcp_servers.ticket_mcp`。

5. 通过 tools.include 只注册本场景需要的工具。

6. 让 Hermes 在 Agent Loop 中按需调用这些工具，并把结果回填给模型生成最终回复。

这个设计比“把数据库账号交给模型”安全得多，也比“每个系统都写一个 Hermes 内置工具”可维护得多。

十五、常见排查路径：工具没出现怎么办

MCP 工具没出现时，不要第一反应去怀疑模型。更常见的原因是连接失败、依赖没装、配置写错、工具被过滤、server 被禁用、utility capability 不存在。

可以按这个顺序排查：

1. 确认 MCP 依赖已安装：`uv pip install -e ".[mcp]"`。

2. 如果是 npx 服务，确认 `node --version` 和 `npx --version` 可用。

3. 检查 config.yaml：command、args、url、headers、env 是否正确。

4. 检查 server 是否 `enabled:false`。

5. 检查 tools.include / tools.exclude 是否把工具过滤掉。

6. 如果资源或提示工具没出现，确认 server 是否真的支持 resources/prompts。

7. 修改配置后，使用 `/reload-mcp` 重新加载。

十六、源码阅读路线：想深入就看这几块

如果你想进一步从源码层理解 MCP，可以按下面顺序读：

源码/文档	重点问题	阅读目标
website/docs/user-guide/features/mcp.md	MCP 配置、工具注册、过滤、安全、并发、Sampling	建立完整概念主线
tools/mcp_tool.py	MCP Client 如何连接、发现、注册、调用工具	理解运行时实现
hermes_cli/mcp_config.py	hermes mcp add/list/test/configure/login 怎么工作	理解 CLI 配置流程
model_tools.py / tool registry	工具如何被统一 dispatch	理解 MCP 工具和内置工具如何合流
mcp_serve.py	Hermes 如何反过来作为 MCP Server	理解消息桥接能力

十七、总结：MCP 让 Agent 从“会聊天”变成“能接系统”

Hermes Agent 的 MCP 设计，真正有价值的地方不是“多了一个配置项”，而是把外部工具接入变成了一套标准工程流程：配置连接、启动发现、命名注册、工具过滤、模型调用、运行时执行、结果回填、安全控制、动态刷新、并发扩展、Sampling 反向推理、反向暴露 Hermes 能力。

如果用一句话总结：

MCP 是 Hermes Agent 连接真实世界的标准插槽。没有 MCP，Agent 的工具生态容易碎片化；有了 MCP，企业系统、开发工具、数据库、消息平台、SaaS 服务都可以通过统一方式接入 Agent。

对技术人来说，学习 Hermes MCP 不只是学一个框架，而是在学习未来 Agent 应用的关键工程范式：模型负责决策，工具负责行动，MCP 负责把外部世界以可控、可扩展、可治理的方式接进 Agent。