P20 20_能力篇_MCP远程服务器工具使用

课时概要

能力篇 · MCP 远程服务器工具使用。Hermes 可接入远端 MCP server 的工具；MCP 服务会在 apps/desktop 的 capabilities 面板里管理（探测/日志/状态）。

本分P 没有逐P 的官方简介（视频简介只有资源链接）。以下「本节要点 / 关键概念 / 代码实操」均改写自 Hermes 官方文档（MCP 页 + Use MCP with Hermes 指南）与官方仓库原文并标注来源；「我的收获」里标 本机实测 的是在本机实跑得到的真实状态。

视频：20_能力篇_MCP远程服务器工具使用｜时长 12:57 ｜ P20

本节要点

HTTP 型 MCP 配置（官方原文）：用 url + headers 直连远程端点，例如 url: "https://mcp.example.com/mcp" 配 Authorization: "Bearer ***"。适合「服务器托管在别处」「组织暴露内部 MCP 端点」「不想让 Hermes 为该集成起本地子进程」。
代理支持：HTTP/SSE 服务器遵循标准代理设置 —— HTTPS_PROXY / HTTP_PROXY / ALL_PROXY（socks:// 会规范成 socks5://），其次看 OS 代理（Windows 注册表 / macOS 系统设置），NO_PROXY 里的主机（含 CIDR 段与 *.example.com）直连。
OAuth 自动托管：多数托管型 MCP（Cloudflare / Linear / Sentry / Atlassian / Asana / Figma / Stripe…）要 OAuth 2.1 而非静态 token → 写 auth: oauth，Hermes 负责发现、客户端标识、PKCE、token 交换、刷新与 step-up 认证（走 MCP Python SDK）。
客户端标识：Hermes 先用 Client ID Metadata Document 自报身份，服务器不支持时回退 Dynamic Client Registration（DCR） —— 两者都自动，无需配置。
两个已知特例（官方专门写了）：① Figma 的 https://mcp.figma.com/mcp 按 client_name 白名单放行 DCR —— 裸 "Hermes Agent" 会 403，而 "Claude Code"/"Codex" 可以，所以 Hermes 对该域名自动设 oauth.client_name: "Claude Code" ② Google 托管（Gmail/Calendar）只在授权请求带 access_type=offline 时才发 refresh token，而 MCP 发现流程不广告它 → Hermes 对 accounts.google.com 自动补 access_type=offline + prompt=consent。
token 存放与绑定：token 缓存在 ~/.hermes/mcp-tokens/<server>.json（0600 权限）；refresh token 绑定签发它的授权服务器 —— Hermes 记下发现的 issuer，若服务器广告的授权服务器变了（迁移/元数据被改/被劫持）就丢弃旧 refresh token 而不是发给新 issuer。
远程 / 无头环境的登录方式（loopback 回调到不了你的笔记本时）：① Hermes Desktop 自动（Desktop 在你机器上托管回调并中继）② paste-back（打印授权链接 + “Or paste the redirect URL here…”，浏览器报连接错误是预期的）③ device-code（hermes mcp login <server> --flow device，在任意设备输码，无需回调监听）④ SSH 端口转发 ⑤ oauth.redirect_uri 代理回调（Tailscale Funnel / 反代指向回调端口）。
启动发现与并发：服务器在启动时发现并注册；一次发现默认最多同时连 4 台（mcp.discovery_concurrency，0 = 不限），每波 120s 预算、整轮上限 300s —— 避免多服务器同时 spawn 造成 CPU/内存尖峰。
lazy 惰性启动：lazy: true 的服务器先从磁盘 schema 缓存注册工具，进程（或 HTTP 连接）推迟到第一次调用该工具时才起；缓存每次真实连接都会重写，所以新/改过的服务器第一次仍是 eager。
Dynamic Tool Discovery：服务器可发 notifications/tools/list_changed 通知 Hermes 运行时工具变了 → Hermes 自动重取工具列表并更新注册表，无需手动 /reload-mcp（有锁保护，避免同一服务器高频通知导致重叠刷新）。
重载与自动监视：改完 MCP 配置用 /reload-mcp；运行中的 gateway 也会自己盯着 config.yaml —— 删条目或置 enabled: false 后约一分钟内拆掉连接，新加条目会连上；首次连接失败的服务器按冷却（30s 起、翻倍至 10 分钟）自动重试。会话的工具集本来会「冻结」，所以要靠 /reload-mcp / /new / 上下文压缩来捡起中途出现的凭证或守护进程。
按服务器过滤（=安全控制）：enabled: false 完全不连｜ tools.include: [create_issue, list_issues] 白名单｜ tools.exclude: [delete_customer] 黑名单｜两者都支持 fnmatch 风格通配（include: ["*_dns_*"]），这是对付 Cloudflare 那种 ~3,300 个工具的大面积接口的实用手段｜ 同时存在时 include 优先 ｜ tools.prompts: false / tools.resources: false 关掉 utility 包装｜无通配符的条目是精确匹配（docs 只匹配名叫 docs 的工具，不会匹配 docs_search）。
Toolset：每个贡献了至少一个工具的 MCP 服务器会创建一个运行时 toolset mcp-<server>，便于在 toolset 层面理解与开关。

关键概念

HTTP MCP server：远程端点，Hermes 直接连，不起本地子进程。
auth: oauth：声明该服务器走 OAuth 2.1，其余（发现 / 注册 / PKCE / 刷新）由 Hermes 自动完成。
DCR（Dynamic Client Registration）：服务器不支持 Client ID Metadata Document 时的回退注册方式。
~/.hermes/mcp-tokens/：OAuth token 缓存（0600），并记录 issuer 以绑定 refresh token。
lazy start：先注册（用缓存 schema）、后拉起，省启动时间与内存。
Dynamic Tool Discovery：服务器主动通知工具变化，Hermes 自动刷新注册表。
tools.include / tools.exclude + glob：按服务器粒度的工具白/黑名单（include 优先），既是易用性也是安全边界。
mcp-<server> toolset：MCP 服务器在 toolset 层面的表示。

代码 / 实操

yaml

# OAuth 型远程 MCP（官方原文）
mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

yaml

# 大面积接口用 glob 黑名单（官方原文，Cloudflare ~3300 工具）
mcp_servers:
  cloudflare:
    url: "https://mcp.cloudflare.com/mcp?codemode=false"
    auth: oauth
    tools:
      exclude: ["*_radar_*", "*_accounts_dlp_*", "*_zones_web3_*"]

yaml

# 惰性 + 回收 + 过滤 + 关掉 utility（官方键的实战组合）
mcp_servers:
  playwright:
    command: "npx"
    args: ["-y", "@playwright/mcp@latest", "--headless"]
    idle_timeout_seconds: 900
    max_lifetime_seconds: 86400
    tools:
      include: ["browser_*"]
      prompts: false
      resources: false

bash

hermes mcp login linear            # 授权 / 重新授权
hermes mcp reauth --all            # 全部重授权
/reload-mcp                        # 会话内重载

本机实测（2026-09-25）：2 个 HTTP 型服务器 —— vercel（https://mcp.vercel.com，OAuth）与 tavily（URL 里内嵌 API key）；~/.hermes/mcp-tokens/ 里有 vercel 的三件套（vercel.json / vercel.client.json / vercel.meta.json，最后一次写入 5 月 29 日）→ 与官方说的 token 缓存路径完全一致。本机 7 个服务器都没有配 tools 过滤。

我的收获

用户此前已完成本模块的学习与配置；以下是本机实测状态（2026-09-25）：

本机 vercel 就是官方说的「托管型 + OAuth」那一类：config 里只有 url: https://mcp.vercel.com + enabled: true，没有写任何 token —— 凭证全在 ~/.hermes/mcp-tokens/vercel*.json（三件套，0600），与官方文档描述一致。
tavily 是另一种形态：把 API key 直接写在 url 的查询串里（https://mcp.tavily.com/mcp/?tavilyApiKey=tvl…），属于「静态 token 型」而非 OAuth 型 —— 同一份配置里两种都能共存，正是官方说的「local stdio 与 remote HTTP 同配置」。
本机没有任何 tools.include/exclude：7 个服务器的工具面都是全开的。官方把过滤定位成安全控制（「disable dangerous tools you do not want the model to see」），这条对我这台来说是明确的待收紧项（尤其 open-knowledge 之类能读本地库的服务器）。
官方那条「gateway 会自己盯 config.yaml，约一分钟内生效、无需重启」解释了为什么改完 MCP 配置有时立刻见效、有时要等 —— 会话内的工具集是冻结的，得靠 /reload-mcp 或 /new 才会捡起来。

（个人感想部分待补写。）

待深入

（待填：没听懂、想回头查的。）

课时概要

本节要点

关键概念

代码 / 实操

我的收获

待深入

Related Posts