HoRain云--Hermes Agent MCP 集成

MCPModel Context Protocol是 Anthropic 提出的开放协议用于标准化 LLM 与外部工具的交互。Hermes 原生支持 MCP无需修改核心代码就能接入 GitHub、数据库、文件系统、浏览器堆栈、内部 API 等任何 MCP 兼容服务。本章将深入 MCP 的两种接入方式、工具过滤策略、安全隔离机制以及常见问题排查。什么是 MCPMCP 解决了一个实际问题每接入一个新服务传统做法需要写适配代码、定义工具 Schema、处理认证——每个服务都是一次性工作。MCP 把这些标准化了。任何实现 MCP 协议的服务Hermes 都能直接接入无需额外开发。MCP 的核心角色Hermes AgentMCP 客户端 │ ├── stdio ──→ MCP 服务器 A本地子进程 │ └── 暴露工具git_commit, git_push... │ ├── HTTP ───→ MCP 服务器 B远程服务 │ └── 暴露工具list_issues, create_issue... │ └── HTTP ───→ MCP 服务器 C远程 OAuth └── 暴露工具search_docs, create_page...标准安装已包含 MCP 支持无需额外步骤。所有 MCP 服务器在~/.hermes/config.yaml中统一配置。MCP 不是 Hermes 的专有协议——它是开放的。为其他支持 MCP 的工具编写的服务器如 Claude Code 的 MCP 服务器可以直接在 Hermes 中使用反之亦然。两种 MCP 服务器类型本地 stdio 服务器以子进程形式在本地运行通过标准输入/输出stdin/stdout与 Hermes 通信。通信使用 JSON-RPC 协议每条消息以换行符分隔。适用场景工具已本地安装需要低延迟访问本地资源文件系统、Git 仓库、本地数据库。实例# 文件路径~/.hermes/config.yaml# MCP stdio 服务器配置mcp_servers:# GitHub 服务器通过 npx 启动github:command: npxargs: [-y, modelcontextprotocol/server-github]env:GITHUB_PERSONAL_ACCESS_TOKEN: ghp_...# 文件系统服务器限制 Agent 的访问范围filesystem:command: npxargs:- -y- modelcontextprotocol/server-filesystem- /home/user/projects # 只允许访问此目录# Git 服务器通过 uvx 启动git:command: uvxargs:- mcp-server-git- --repository- /home/user/projectstdio 服务器的生命周期由 Hermes 管理会话启动或/reload-mcp时Hermes 启动子进程会话结束或禁用服务器时Hermes 终止子进程子进程崩溃会自动重启最多重试 3 次远程 HTTP 服务器通过 HTTP 请求直接连接远程 MCP 端点支持多种认证方式。适用场景工具在远端托管或组织内部已有 MCP 接口。实例# 文件路径~/.hermes/config.yaml# MCP HTTP 服务器配置mcp_servers:# 方式一静态 Bearer Token 认证internal_api:url: https://mcp.internal.example.com/mcpheaders:Authorization: Bearer ${MY_TOKEN} # 支持环境变量# 方式二OAuth 2.1 认证Linear、Sentry、Figma、Stripe 等linear:url: https://mcp.linear.app/mcpauth: oauth# 方式三需要预注册 OAuth 客户端的提供商googledrive:url: https://drivemcp.googleapis.com/mcp/v1auth: oauthoauth:client_id: your-oauth-client-id # 预注册获取client_secret: your-oauth-client-secret两种类型对比维度stdio 服务器HTTP 服务器运行位置本机子进程远程独立服务通信方式stdin/stdout JSON-RPCHTTP 请求生命周期Hermes 管理启停独立于 Hermes延迟极低进程内通信取决于网络延迟认证环境变量传递Bearer Token / OAuth 2.1典型场景本地 Git、文件系统、数据库GitHub API、Linear、Sentry配置复杂度低一行 command中需配置 URL 认证Nous 精选 MCP 目录Hermes 内置了一个经 Nous Research 审核的 MCP 目录提供一键安装体验。浏览与安装打开交互式选择器TUI浏览所有目录条目:hermes mcp其他命令# 纯文本列表适合脚本化 hermes mcp catalog # 按名称一键安装 hermes mcp install n8n hermes mcp install github hermes mcp install linear交互式选择器显示每个条目的当前状态n8n available 管理和检查 n8n 工作流 linear enabled Linear 问题/项目管理远程 OAuth github installed (disabled) GitHub 仓库 PR 工具 filesystem installed (enabled) 安全的文件系统操作 postgres available PostgreSQL 数据库查询 slack available Slack 消息和频道管理状态说明状态含义available可安装尚未安装installed (enabled)已安装且已启用Agent 可以使用installed (disabled)已安装但已禁用Agent 不可使用enabled远程 OAuth 服务器已授权启用桌面版在设置菜单中查看配置仪表盘在左侧 MCP 菜单查看配置安装过程发生了什么一键安装自动完成三步配置引导提示填写 API Key 或引导 OAuth 浏览器授权流程工具探测连接服务器获取其暴露的完整工具列表工具选择展示工具清单让你勾选要启用的工具默认全选第三步工具选择是重要的安全环节——不是每个工具你都需要。比如 GitHub 服务器暴露了 delete_repo如果你不需要可以取消勾选。工具过滤只暴露你需要的每个 MCP 服务器都支持精细的工具过滤。这是减少 Agent 攻击面的关键安全机制。include 模式白名单只注册列表中的工具其余全部排除实例# 文件路径~/.hermes/config.yaml# include 白名单模式——最安全的选择mcp_servers:github:command: npxargs: [-y, modelcontextprotocol/server-github]env:GITHUB_PERSONAL_ACCESS_TOKEN: ghp_...tools:include:- list_issues- create_issue- update_issue- search_code# 这 4 个之外的任何工具都不会注册exclude 模式黑名单排除列表中的工具其余全部注册实例# 文件路径~/.hermes/config.yaml# exclude 黑名单模式——排除高风险操作mcp_servers:stripe:url: https://mcp.stripe.comheaders:Authorization: Bearer ${STRIPE_KEY}tools:exclude:- delete_customer- refund_payment- create_live_key# 这 3 个之外的任何工具都会注册过滤规则优先级配置行为适用场景仅 include只注册 include 列表中的工具安全优先最小权限原则仅 exclude注册全部工具排除 exclude 列表方便优先排除少数高风险操作两者都设置include 优先exclude 被忽略—两者都不设置注册服务器暴露的所有工具完全信任该 MCP 服务器关闭资源和提示词MCP 服务器除了工具还可能暴露资源和提示词Prompts。如果不需要可以关闭实例# 文件路径~/.hermes/config.yaml# 在平台配置中引用 MCP 工具集platform_toolsets:cli:- hermes-cli- file- terminal- mcp-github # GitHub MCP 工具- mcp-linear # Linear MCP 工具telegram:- hermes-gateway- mcp-github # Telegram 上也启用 GitHub 工具discord:- hermes-gateway# Discord 上不启用 GitHub 工具安全策略MCP 环境变量隔离这是 Hermes 的 MCP 安全机制中最容易被忽略但最重要的设计。MCP stdio 子进程接收一个经过过滤的环境默认只传递以下变量PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR 以及所有 XDG_* 变量其他所有环境变量API Key、Token、密码都被屏蔽。只有在 MCP 服务器配置的env:块中显式声明的变量才会传入子进程实例env:GITHUB_PERSONAL_ACCESS_TOKEN: ghp_... # 只有这一个变量传入# 即使你在 Shell 中 export 了 GITHUB_TOKEN# 没有在这里声明就不会传入 MCP 子进程为什么这样设计假设你在 .env 中存了 10 个 API KeyOpenAI、Anthropic、SerpAPI、Telegram Bot Token...。如果 MCP 服务器能读取所有环境变量一个恶意的 MCP 服务器工具就可以窃取所有凭据。环境变量隔离确保它只能看到显式声明的那个。错误信息自动脱敏MCP 工具的错误信息在返回给 LLM 前会自动脱敏——敏感信息API Key、Token、密码替换为[REDACTED]。这防止了 Agent 在分析错误时意外看到明文凭据。手动添加 MCP 服务器除了从 Nous 目录一键安装你也可以手动添加任何 MCP 兼容服务器。实例# 手动添加 stdio 服务器hermes mcp add my-git-server \--command uvx \--args mcp-server-git,--repository,/home/user/project# 手动添加 HTTP 服务器hermes mcp add internal-db \--url https://mcp.internal.example.com/db \--header Authorization: Bearer ${DB_TOKEN}# 测试连接是否正常hermes mcp test my-git-server# 配置工具过滤hermes mcp configure my-git-serverhermes mcp configure会打开交互式工具选择界面让你重新勾选要启用的工具。重新加载 MCP 配置修改了 config.yaml 中的 MCP 配置后无需重启整个 Agent实例# ─── 浏览与安装 ─────────────────────────────────────────────hermes mcp # 交互式目录选择器TUIhermes mcp catalog # 纯文本目录列表hermes mcp install name # 从目录一键安装# ─── 手动管理 ───────────────────────────────────────────────hermes mcp add name --command cmd --args ... # 添加 stdio 服务器hermes mcp add name --url url # 添加 HTTP 服务器hermes mcp remove name # 移除服务器配置hermes mcp list # 列出所有已配置服务器hermes mcp test name # 测试服务器连接hermes mcp configure name # 重新选择启用的工具# ─── OAuth 认证 ─────────────────────────────────────────────hermes mcp login server # 启动 OAuth 授权最长等 5 分钟# ─── 运行时操作 ─────────────────────────────────────────────/reload-mcp # 会话内重新加载 MCP 配置hermes mcp reload # 命令行重新加载常见问题排查问题可能原因解决方案MCP 工具不出现服务器未启用或连接失败运行 hermes mcp list 检查状态hermes mcp test 测试连接工具过滤不生效使用了 Hermes 注册后的工具名改用 MCP 原始工具名含连字符如 list-issues 而非 list_issuesstdio 服务器频繁崩溃依赖缺失或权限不足检查 command 是否在 PATH 中手动运行测试OAuth 授权超时/reload-mcp 的 30 秒不够先 hermes mcp login完成后再 /reload-mcp环境变量不生效未在 env: 块中显式声明在 mcp_servers.name.env 中声明不要依赖 Shell 环境变量HTTP 服务器连接拒绝URL 不可达或认证失败检查 URL 和 Authorization header确认网络连通