第24篇：MCP——让 AI 接入千万工具

你有没有想过，让 Hermes 直接用上 GitHub、数据库、浏览器，甚至你们公司内部的 API？以前你可能得专门写一个 Hermes 原生工具，现在不用了——MCP（Model Context Protocol） 就是干这个的。

简单说，MCP 让 Hermes 能连上外部的工具服务器，把别人已经做好的工具直接拿过来用。如果你想让 Hermes 用某个已经存在的工具，MCP 通常是最省事的方式。

从 Claude Code 迁移过来的朋友注意：~/.claude.json 里的 mcpServers 对应 Hermes 的 mcp_servers，用 hermes import-agent claude-code（来自 agent-importers 插件）可以迁移，连 skills 和 instructions 一起搬。

本页的 Python 依赖命令都基于 PM 准备好的源码检出。改完依赖后，重新激活检出并重启 Hermes。

MCP 能给你什么？

不用先写原生工具，直接接入外部工具生态
本地 stdio 服务器和远程 HTTP 服务器可以写在同一个配置里
启动时自动发现并注册工具
支持按服务器过滤，只暴露你想让 Hermes 看到的工具

快速上手

MCP 随标准安装自带，不需要额外步骤。在 ~/.hermes/config.yaml 里加一个服务器：

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

然后启动 Hermes：

hermes chat

接着直接问它：

列出 /home/user/projects 里的文件，并总结一下仓库结构。

Hermes 会自动发现 MCP 服务器的工具，像用普通工具一样调用它们。

精选目录：一键安装

Hermes 自带一个经过 Nous 团队审核的 MCP 服务器目录，默认全部禁用，按需安装：

hermes mcp                   # 交互式选择器（默认）
hermes mcp catalog           # 纯文本列表，适合脚本
hermes mcp install deepwiki  # 按名称安装

你也可以直接在聊天里说一句“add the Linear MCP”。Hermes 会调用 manage_connections，带上 mcp: true 的目标，然后弹出一张设置卡片。这张卡片在桌面版（对话框）、终端 UI（hermes --tui，输入框上方的提示条）和经典 CLI（面板）里表现一致：

字段。 如果条目声明了设置项，卡片会一次性全部显示。普通值会预填默认值，密钥会打码。你打字的过程中不会保存任何东西。
连接或取消。 取消只会跳过这一个服务器，同一次请求里的其他服务器继续。
授权。 OAuth 条目会在卡片上显示授权链接。Hermes 从不自己打开浏览器：桌面版点 Open in browser，终端里按 Enter。走 SSH 时卡片会告诉你怎么访问回调端口，或者怎么粘贴重定向后的 URL。
保存。 等服务器接受了新 token、首次连接返回后，Hermes 会把服务器配置、token 和你的设置值一起保存。如果服务器拒绝 token，或者你在此之前取消，这次尝试的任何东西都不会保留，你之前的配置和 token 原样不动，失败的表单会带着你填过的内容重新打开。已经授权过的服务器会用保存的 token 直接连；只有 token 失效时 Hermes 才会再让你授权。
工具。 接着 Hermes 会列出服务器的工具并注册它们，agent 可以在同一轮里调用。如果授权成功但工具列表拉取失败，卡片会显示 “Authorized. Tools unavailable.”，agent 之后可以重新跑一次发现，不用再让你授权。

在消息应用里没有卡片，agent 会转达下面的命令。

选择器会显示每个条目的状态：

deepwiki     available              Ask questions about public GitHub repositories
linear       enabled                Linear issue/project management (remote OAuth)
github       installed (disabled)   GitHub repo + PR tools

按 Enter 即可安装、启用、禁用或卸载。目录条目存放在 hermes-agent 仓库的 optional-mcps/ 目录下——出现在那里就意味着 Nous 审核过。没有社区提交这一层，条目都是通过合并 PR 加进去的。

有些条目还会声明一个可选的 suggest: 块，里面是 keywords: 和/或 hosts: 列表。UI（目前是桌面版的输入框）会用它来做一键提示：当你的草稿里把某个关键词当作完整单词提到，或者粘贴了一个主机名以某个 host 后缀结尾的链接时，就会弹出一个 “Add <server>” 的小药丸。它纯粹是建议性质——安装还是走同一套经过校验的目录/配置流程——大多数托管型远程条目（Atlassian、Sentry、Notion、Stripe、Vercel、Supabase 之类）都声明了它。可选的 applications:（最多 16 个应用名）、requires_app: true（表示这个 MCP 需要本地装了那个应用；这类条目永远不会作为一键药丸出现）和 examples:（最多六条一句话的成果示例）用来描述那些驱动桌面应用的条目。

注意：第三方 n8n 桥接已经不再支持从目录安装了。已经装过的连接、凭证、文件和工具选择都保留，会继续作为自定义条目出现在选择器里，你仍然可以配置工具、启用或禁用，只是不能再从目录重装。这个变化不会把老连接迁移到 n8n 官方 MCP 服务器。

安装时可能需要：

API key——安装时提示，写入 ~/.hermes/.env
OAuth（远程 MCP）——首次连接时自动打开浏览器
第三方 OAuth（如 Google/GitHub）——Hermes 会提示你先运行 hermes auth <provider>

n8n 官方 MCP 服务器

n8n-official 这个目录条目会通过 HTTP + 浏览器 OAuth 直连你的 n8n Cloud 或自托管实例，不需要本地桥接，也不需要 n8n API key。

让 owner 或 admin 在 n8n 里打开 Settings > Instance-level MCP
进 Connect，复制完整的 Server URL（结尾是 /mcp-server/http，不是编辑器地址）
运行 hermes mcp install n8n-official，提示时填入这个 URL
完成浏览器 OAuth；需要的话可以跑 hermes mcp login n8n-official，或在 Desktop / 面板里点 Authorize
用 hermes mcp configure n8n-official 挑工具，然后开个新会话或用 /reload-mcp

Hermes 后端必须能访问到这个 URL。权限和工作流暴露由 n8n 控制，有些工具会修改或运行工作流，用之前留意一下。

安装时选工具

配置好凭证后，Hermes 会探测服务器上的所有工具，让你勾选：

Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues       Find issues matching a query
  [x] get_issue         Get a single issue
  [x] create_issue      Create a new issue
  [ ] delete_workspace  Delete a Linear workspace

默认勾选规则：你之前的安装选择 > 清单里的 tools.default_enabled > 全部勾选。如果探测失败，安装仍会成功，只是暂时不写过滤规则，等服务器可达后再用 hermes mcp configure <name> 调整。

图片结果

MCP 工具返回的 ImageContent 块（截图、渲染出来的图表、页面抓取）会被存进 Hermes 的图片缓存，并在结果里以 MEDIA:/path/to/image.png 的形式给出路径，这样你可以在任何支持附件的界面上要这个文件。当主模型能看懂工具结果里的图片时，图片本身也会被附到结果上，模型直接读像素。MCP 结果和 vision_analyze 遵循同一套规则：agent.image_input_mode、显式配置的 auxiliary.vision 后端以及模型自身的视觉能力都会生效（详见 Vision）。附上的图片会被缩放到 vision.embed_target_bytes（每个结果最多 4 张），因为它们会在之后每一轮里被重新发送。纯文本模型只会拿到路径。

需要自带 OAuth 应用的条目（不支持 DCR）

有些厂商的远程 MCP 走 OAuth，但不提供动态客户端注册（DCR）——每个客户端都得是你在厂商开发者后台预先注册的应用。Asana 的 V2 服务器（https://mcp.asana.com/v2/mcp）就是例子：老的 V1 https://mcp.asana.com/sse 接受任意客户端，V2 不行。

这类清单会把凭证声明在 auth.env、把客户端固定在 auth.oauth 里，安装时（命令行、面板或 Desktop）会提示你填 Client ID / Client secret，存进 profile 的 .env，config.yaml 里只写 ${VAR} 引用。装完记得看清单里的 post_install 说明，按它要求的应用类型和回调地址去注册，然后跑 hermes mcp login <name> 并重启（或 /reload-mcp）对应的会话或网关。因为客户端带了固定的 redirect_port，Hermes 会保留注册好的本地回调（比如 http://localhost:27890/callback），所以点授权的浏览器必须和 Hermes 进程在同一台机器上；远程主机的话用 SSH 端口转发跑 hermes mcp login。

重新加载 MCP：`/reload-mcp`

改完配置、装完新服务器，或者刚拿到一个新凭证，怎么让 Hermes 立刻用上？答案是 /reload-mcp。

这个命令会从配置里重新加载 MCP 服务器，并刷新可用的工具列表。它也是重新探测那些“看条件才出现”的工具的明确方式——比如 Docker、需要凭证的插件（像 HASS_TOKEN）、OAuth 之类。

为什么要专门做这一步？因为一个会话里的工具集默认是冻结的：会话跑到一半才出现的凭证或后台服务，只有在你执行 /reload-mcp、开新会话（/new），或者触发上下文压缩（context compaction）时才会被捡起来。

如果工具变化是服务器自己推过来的（而不是你这边配置变了），那属于动态工具发现（Dynamic Tool Discovery）的范畴，不用手动 reload。

会花钱的工具：成本标注与预算上限

有些 MCP 服务器每调一次就真金白银地扣额度（画图、生成视频、3D 渲染、付费 API）。现在可以在服务器条目里声明每个工具大概花多少，并给每个对话设个预算上限：

mcp_servers:
  renders:
    command: "render-mcp"
    trust: untrusted
    tool_costs:
      create_image: 20                                   # 每次约 20 credits
      animate: {credits: [5, 20], note: "per animation"}  # 给个区间，附一句说明
      get_status: 0                                       # 免费，等于不写
    spend_limit: 100     # 每个对话的上限；0 或不写 = 不限制
    cost_unit: credits   # 提示里显示的单位（默认就是 credits）

用起来是这样：

审批提示会直接告诉你价钱：Costs about 20 credits. 或 Costs 5-20 credits (per animation).；这个对话已经花过钱后，还会补一句 This chat has used about 40 credits on 'renders' (limit 100).。
Hermes 按对话、按服务器记一个累计数（区间取上限），只算它批准并发出去的那些调用；被拒绝或拦下的不计。
累计数跟着对话走：上下文压缩或 /branch 分出来的新会话继续累计；开新对话（CLI 的 /new、桌面端新聊天）重新计数；消息平台上额度属于那个聊天，所以在那儿 /new 不会清零；每次 cron 运行各自独立；重启 Hermes 全部归零。
设了 spend_limit 后，会让这个对话超支的调用一定会先问——哪怕服务器是 trust: full；而且之后的付费调用每次都会再问一次，只给“仅本次允许”和“拒绝”两个选项。没人能应答的场合（cron、hermes chat -q、没有审批人的网关），调用直接被拒，并告诉模型别重试。
/yolo 和 approvals.mode: off 能跳过 trust: untrusted 的审批，但跳不过预算上限。
写错了不会静默丢：tool_costs、spend_limit、cost_unit 格式不对，这个服务器会被跳过并报出是哪个键出错；tool_costs 里写了服务器并不提供的工具名（打错字，或者把 Hermes 的 mcp_<服务器>_ 前缀也抄进去了），连接时会给你一条警告。

MCP 也能主动“推消息”：Events（实验性）

有些 MCP 服务器能在上游发生变化时通知 agent（来了新邮件、出了新故障、订阅源里有了新条目）。这套机制还处在 MCP 工作组的草案阶段，Hermes 实现的是其中的 webhook 投递模式：服务器把事件 POST 到 gateway 的 webhook 监听，每个事件就像一条普通 webhook 路由那样触发一次 agent 运行。

开启方式（每台服务器单独开，并且要告诉 Hermes 监听器的公网 HTTPS 地址——服务器会拒绝明文 HTTP 回调，所以要在 8644 端口前面挂一个做 TLS 终结的反向代理或隧道）：

mcp_servers:
  ambush:
    url: "https://example.com/mcp"
    events: true          # 为这台服务器注册事件工具

platforms:
  webhook:
    enabled: true
    extra:
      public_url: "https://hermes.example.com"

开了之后多出三个工具：list_event_types（服务器支持哪些事件类型、你当前订阅了哪些）、subscribe_event（订阅：事件参数、收到后做什么（instructions，最多 2000 字）、结果送到哪（deliver / deliver_chat_id））、unsubscribe_event（取消订阅）。因为订阅会拉起无人值守的 agent 运行，每次订阅都要你批准，审批里会完整显示指令和投递目标。

服务器中途要你填表：elicitation

MCP 服务器可以在工具调用过程中反过来问你问题（elicitation/create 协议，需要 mcp Python SDK ≥ 1.11.0）。表单模式的请求会走 Hermes 现有的审批界面——CLI/TUI 里是交互提示，Telegram、Slack 这类网关上就是审批按钮，所以不管你在哪个界面都能作答。每次回答只覆盖那一个请求，所以只给“仅本次允许”和“拒绝”；/yolo 和 approvals.mode: off 不会替你回答（服务器是在问你问题，不是在求你授权）。URL 模式（服务器丢给你一个外部链接）目前直接按不支持拒绝。

响应太大怎么办

Hermes 单个 HTTP 响应（或流式响应里的单个 SSE 事件）最多接受 10 MiB，所以很大的 tools/list 目录或工具结果（比如一张编辑器截图）都装得下。老式 SSE 传输（transport: sse）受 MCP SDK 限制，每个事件只有 1 MiB 且无法调高——如果这台服务器同时也支持 Streamable HTTP，把条目里的 transport: sse 删掉就行。

信任模型

安装目录条目会执行清单里定义的命令（git clone、pip install 等）。虽然每个条目都经过 Nous 的 PR 审核，但安装前还是建议读一下 manifest，特别是 source: 仓库地址和 install.bootstrap: 命令。清单在 GitHub 的 optional-mcps/<name>/manifest.yaml，选择器安装时也会打印 source: URL 方便你快速核实。

版本兼容与变量替换

清单会锁定 manifest_version。如果你装的 Hermes 版本太老，选择器会提示 ⚠ '<name>' requires a newer Hermes，运行 hermes update 升级即可。

另外，transport.command、transport.args、transport.url 和 headers 里的 ${VAR} 占位符会在运行时自动替换成环境变量值——方便你管理密钥和动态配置。也支持 Cursor 风格的上下文变量（区分大小写）：${userHome}、${workspaceFolder}、${workspaceFolderBasename}、${pathSeparator} / ${/}。

MCP 让 Hermes 的边界一下子拓宽了。不用再造轮子，直接接上现成的工具生态。 去 hermes mcp 看看有什么好玩的吧！