一、先说结论MCP 是 Hermes 的“外部工具总线”如果把 Hermes Agent 比作一个会思考、会拆任务的“项目经理”那么 Tools 就是它能调动的“员工”而 MCP 就是把外部员工接进团队的统一门禁和工牌系统。没有 MCP每接一个系统都要在 Hermes 内部写一套专用工具有了 MCP只要外部系统按 MCP 规范暴露能力Hermes 就能在启动时发现它们、注册它们并让模型在合适时机调用它们。用更直白的话说MCP 解决的是三个问题1. 外部工具怎么被 Hermes 发现2. 外部工具怎么变成模型可调用的 tool3. 调用外部工具时鉴权、超时、过滤、安全、结果回填怎么管理这也是为什么 MCP 在 Agent 工程里越来越重要模型本身不会访问 GitHub、数据库、工单系统、公司 API它必须通过工具层间接行动。Hermes 的 MCP 设计就是把这个工具层做成可扩展、可过滤、可复用的协议化接入层。二、MCP 在 Hermes 里的位置不是模型能力而是运行时能力很多人容易把 MCP 理解成“某种插件”。这个说法不完全准确。MCP 更像一个“工具协议”它规定了客户端和服务器之间如何发现工具、描述工具、调用工具、返回结果。Hermes 在这个体系里有两个身份。第一个身份是 MCP Client。Hermes 作为客户端连接 GitHub、文件系统、数据库、公司内部 API 等 MCP Server。外部 MCP Server 把自己的能力描述给 HermesHermes 再把这些能力注册为可调用工具。第二个身份是 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 Serverstdio 和 HTTPHermes 官方文档把 MCP Server 分成两类stdio server 和 HTTP server。stdio server 是本地子进程。比如通过 npx 启动一个文件系统 MCP ServerHermes 和它通过 stdin/stdout 通信。它适合本机工具、本地文件系统、本地 CLI、低延迟项目资源。HTTP server 是远程端点。比如公司内部暴露了一个 https://mcp.internal.example.comHermes 通过 URL 和 headers 连接它。它适合企业内部 API、云端 MCP 平台、SaaS 服务、跨网络共享能力。可以这样选择类型适合场景典型配置stdio本地工具、本地文件系统、npx 启动服务、低延迟资源command args envHTTP远程服务、内部 API、SaaS、云端 MCP 平台url headers五、配置不是只写地址还要控制权限和暴露面Hermes 从 ~/.hermes/config.yaml 的 mcp_servers 下读取配置。一个最小的 stdio 配置可以只包含 command 和 args一个最小的 HTTP 配置可以只包含 url 和 headers。但在真实项目里只写连接信息远远不够。建议把 MCP 配置拆成三类理解1. 连接信息stdio 用 command、args、envHTTP 用 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: npxargs: [-y, modelcontextprotocol/server-github]env:GITHUB_PERSONAL_ACCESS_TOKEN: ***tools:include: [list_issues, create_issue, update_issue]prompts: falseresources: false这类配置体现了一个很重要的 Agent 工程原则不是“能接多少工具就接多少”而是“只把当前任务需要的能力暴露给模型”。六、Hermes 如何给 MCP 工具命名和注册MCP Server 原始工具名可能和 Hermes 内置工具重名也可能不同服务器之间重名。为了解决这个问题Hermes 会给 MCP 工具加统一前缀mcp_server_name_tool_name例如 filesystem 服务器的 read_file 会注册成 mcp_filesystem_read_fileGitHub 服务器的 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.comheaders:Authorization: Bearer ***tools:exclude: [delete_customer, refund_payment]这就是企业接入 Agent 时必须坚持的最小权限原则工具不是越多越好暴露面越小Agent 越可控。九、动态工具发现和 /reload-mcpHermes 支持动态工具发现。MCP Server 可以在工具列表变化时发送 notifications/tools/list_changed 通知Hermes 收到后会重新拉取工具列表并更新 registry。这对企业系统很有用。比如某个数据库 schema 加载后才出现新查询工具某个服务下线后需要移除工具或者某个内部平台根据用户权限动态调整能力。如果你是手动修改 config.yamlHermes 也提供 /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-serversupports_parallel_tool_calls: true十二、MCP Sampling让外部 Server 也能请求 LLM 能力MCP Sampling 是更高级的能力。简单理解不是只有 Hermes 可以调用 MCP ServerMCP Server 也可以反过来请求 Hermes 帮它做一次 LLM 推理。例如一个外部文档处理 MCP Server 可能需要对一段文本做摘要但它自己没有模型密钥。它可以通过 sampling/createMessage 请求 Hermes 帮忙生成。Hermes 仍然掌握模型选择、超时、限流、最大 token、最大工具轮数等控制权。对不可信的 MCP Server建议显式关闭 Samplingmcp_servers:untrusted_server:url: https://mcp.example.comsampling:enabled: falseSampling 的价值在于外部工具服务可以“借用” Hermes 的 LLM 能力但权限和成本控制仍然在 Hermes 侧。十三、Hermes 反过来作为 MCP ServerHermes 不只是 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.yamlcommand、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.mdMCP 配置、工具注册、过滤、安全、并发、Sampling建立完整概念主线tools/mcp_tool.pyMCP Client 如何连接、发现、注册、调用工具理解运行时实现hermes_cli/mcp_config.pyhermes mcp add/list/test/configure/login 怎么工作理解 CLI 配置流程model_tools.py / tool registry工具如何被统一 dispatch理解 MCP 工具和内置工具如何合流mcp_serve.pyHermes 如何反过来作为 MCP Server理解消息桥接能力十七、总结MCP 让 Agent 从“会聊天”变成“能接系统”Hermes Agent 的 MCP 设计真正有价值的地方不是“多了一个配置项”而是把外部工具接入变成了一套标准工程流程配置连接、启动发现、命名注册、工具过滤、模型调用、运行时执行、结果回填、安全控制、动态刷新、并发扩展、Sampling 反向推理、反向暴露 Hermes 能力。如果用一句话总结MCP 是 Hermes Agent 连接真实世界的标准插槽。没有 MCPAgent 的工具生态容易碎片化有了 MCP企业系统、开发工具、数据库、消息平台、SaaS 服务都可以通过统一方式接入 Agent。对技术人来说学习 Hermes MCP 不只是学一个框架而是在学习未来 Agent 应用的关键工程范式模型负责决策工具负责行动MCP 负责把外部世界以可控、可扩展、可治理的方式接进 Agent。