Hermes Agent 入门(六):MCP、自定义 Tools 与 API,让 Hermes 操作你自己的系统
Hermes Agent 入门(六):MCP、自定义 Tools 与 API,让 Hermes 操作你自己的系统
前面五篇,我们已经把 Hermes 从:
终端里的 AI
一步一步变成了:
可以调用工具
+
拥有 Memory
+
拥有 Skills
+
QQ / 飞书等 Gateway
+
Cron 自动任务
+
主动通知
的长期 Agent。
但到这里会出现一个新的问题。
Hermes 默认虽然已经有:
Terminal
Files
Browser
Web
Cron
Memory
Skills
等大量工具,但如果你真正把它用于自己的环境,很快就会产生这样的需求:
“帮我看看 PVE 上有哪些虚拟机。”
“查一下 Minecraft 服务器现在有几个人在线。”
“看看 OpenWrt 当前 WAN IP。”
“检查 NAS 剩余容量。”
“查看我自己写的管理面板上的用户状态。”
“调用内部 API 给某个账户执行操作。”
这些能力显然不可能全部内置到 Hermes。
于是就轮到这一篇的主角:
MCP 和自定义 Tools
出现了。
这一篇要讲清楚三个经常混在一起的概念:
Skill
Tool
MCP
并最终实现:
QQ / 飞书
↓
Hermes
↓
MCP / Custom Tool
↓
自己的 API
↓
PVE / OpenWrt / Minecraft / NAS / 内部系统
一、先把 Skill、Tool 和 MCP 分清楚
这是理解这一篇最重要的部分。
很多人第一次使用 Agent 时,会把:
Skill
Tool
MCP
都理解成:
“给 AI 增加能力的东西。”
这没有错。
但它们增加能力的方式完全不同。
可以简单记成:
Skill
=
教 AI 怎么做
Tool
=
真正给 AI 一个新能力
MCP
=
用统一协议把外部 Tool 接进 AI
二、Skill 并不会凭空给 Hermes 新权限
例如你创建一个 Skill:
proxmox-management
内容写:
查询 PVE 虚拟机时:
1. 请求 PVE API
2. 获取节点信息
3. 获取虚拟机和 LXC 列表
4. 根据 VMID 整理结果
这个 Skill 本身并不能让 Hermes 自动获得:
PVE API
访问能力。
它只是告诉 Agent:
“如果你已经有办法访问 PVE,
应该按照这个流程操作。”
也就是说:
Skill
=
说明书
它可以组合:
Terminal
curl
已有 Tool
MCP Tool
来完成工作。
如果任务能够通过:
说明文档
+
Shell
+
已有工具
解决,通常优先考虑 Skill。
如果涉及专门 API、密钥、二进制数据或者复杂处理逻辑,就更加适合做成 Tool。
三、Tool 才是真正的能力
例如 Hermes 内置:
web_search
那么 Agent 就真正拥有:
搜索网页
能力。
有:
terminal
就可以真正执行命令。
如果我们增加一个:
get_pve_vms
Tool,那么模型看到的可能类似:
get_pve_vms
作用:
获取 Proxmox VE 当前虚拟机和 LXC 列表。
然后你问:
PVE 上现在有哪些机器?
Hermes 可以判断:
这个问题应该调用 get_pve_vms
于是:
Hermes
↓
Tool Call
↓
get_pve_vms
↓
PVE API
↓
JSON
↓
Hermes 分析
↓
回答
这时候才是真正给 Agent 增加了能力。
Hermes 的 Tool 系统还可以把工具组织成不同 Toolset。
也就是说:
CLI
Gateway
Cron
某个特定 Session
可以分别拥有不同的工具权限。
这一点在后面做安全控制时非常重要。
四、那 MCP 又是什么?
MCP 全称:
Model Context Protocol
可以简单把它理解成:
AI 工具世界里的统一接口。
以前如果:
Claude
Hermes
Cursor
Codex
其他 Agent
都想访问你的系统,你可能需要给每个平台分别写一套插件。
MCP 的思路变成:
你的系统
↓
MCP Server
↓
标准 MCP 协议
↓
Hermes
Claude
Codex
Cursor
其他 MCP Client
也就是说:
MCP Server
负责提供 Tool。
Hermes 负责:
发现 Tool
↓
告诉模型 Tool 是干什么的
↓
在需要时调用它
Hermes 当前已经拥有原生 MCP Client,可以连接本地 MCP Server,也可以连接远程 MCP Server。
五、可以把三者理解成这张图
Hermes
│
┌──────────┼──────────┐
│ │ │
↓ ↓ ↓
Skill Tool MCP
│ │ │
│ │ ↓
│ │ MCP Server
│ │ │
↓ ↓ ↓
怎么做 能做什么 外部能力
例如:
Minecraft
可以这样设计:
MCP Tool:
get_players
restart_server
get_server_status
get_recent_logs
再建立:
Skill:
minecraft-troubleshooting
告诉 Hermes:
卡顿时先检查 TPS
再检查玩家
再检查实体
再检查内存
最后检查日志
于是:
Tool
=
手
Skill
=
经验
LLM
=
脑子
这三者组合起来,才是一个完整的 Agent。
六、什么时候应该用 MCP?
如果某个服务:
已经存在 MCP Server
那么一般没必要重新给 Hermes 写一套 Native Tool。
直接接即可。
例如 MCP 很适合:
GitHub
数据库
文件系统
浏览器工具
内部 API
企业系统
如果希望:
内部 API
数据库
公司系统
能够被多个不同 Agent 使用,MCP 通常是非常合适的选择。
但不要产生另一个误区:
什么东西都必须 MCP。
如果只是:
运行一个 Shell 命令
那么直接使用 Terminal 就够了。
如果只是:
告诉 Agent 一套操作步骤
那么 Skill 更简单。
如果只是给 Hermes 自己写一个非常小的 API Tool:
一个 Python Plugin
有时候反而比完整 MCP Server 更省事。
七、Hermes 自带 MCP 管理能力
可以运行:
hermes mcp
查看 MCP 相关功能。
例如可以:
查看 MCP Catalog
安装 MCP
添加自定义 MCP
完成 OAuth 登录
管理 MCP Tool
不同版本命令可能会有所调整,因此具体以:
hermes mcp --help
显示内容为准。
八、先接一个最简单的 MCP:Filesystem
为了理解整个流程,我们先不碰复杂 API。
假设:
/home/user/my-project
是一个项目。
希望 Hermes 只能够通过 MCP 查看这个目录。
可以在 Hermes MCP 配置中加入类似:
mcp_servers:
project_fs:
command: "npx"
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "/home/user/my-project"
然后启动:
hermes chat
告诉 Hermes:
检查一下 my-project 的目录结构,
告诉我这是什么项目。
Hermes 会:
启动 MCP Server
↓
查询它提供哪些 Tools
↓
把 Tools 注册进 Tool Registry
↓
模型发现文件系统 Tool
↓
读取项目
↓
回答
这就是最基本的 MCP 工作方式。
而且这里专门指定:
/home/user/my-project
也意味着 MCP 只能接触这个项目目录。
不要一开始就给:
/
整个系统根目录。
九、stdio MCP 到底是什么?
刚才这个配置:
command: "npx"
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
属于:
stdio MCP Server
Hermes 会启动一个本地子进程:
Hermes
↓
启动 MCP Server
然后通过:
stdin
stdout
进行通信。
结构:
Hermes Process
│
│ stdio
↓
MCP Server Process
│
↓
Local Resource
这种方式特别适合:
本地文件
本地数据库
本地 CLI
本机工具
十、远程 MCP 更适合服务器和内部平台
另外一种结构:
Hermes
↓
HTTPS
↓
Remote MCP Server
↓
你的系统
例如:
mcp_servers:
company_api:
url: "https://mcp.internal.example.com"
headers:
Authorization: "Bearer xxxxxxxxx"
这样 MCP Server 不需要和 Hermes 在同一台机器。
可以变成:
VPS A
Hermes
│
│ HTTPS
↓
VPS B
MCP Server
│
├── PVE
├── NAS
├── Minecraft
└── Internal API
远程 MCP 特别适合:
多个 Agent
↓
共同访问一个统一的内部工具服务
十一、自己的 API 应该怎么接?
假设你已经有一个内部管理 API:
panel.example.com/api
里面有:
GET /servers
GET /servers/{id}
GET /servers/{id}/stats
POST /servers/{id}/restart
有三种常见做法。
第一种:
Hermes
↓
Terminal
↓
curl API
能用,但比较原始。
第二种:
Hermes Plugin
↓
API
适合:
只有 Hermes 自己用
集成很小
逻辑比较固定
第三种:
Hermes
↓
MCP
↓
你的 API
适合:
以后还准备给其他 Agent 使用
Tool 比较多
准备长期维护
希望权限边界清晰
十二、为什么长期使用不建议全靠 curl?
当然可以直接告诉 Hermes:
curl API
但时间长了会出现几个问题。
Agent 每次都要重新理解:
Endpoint 是什么
参数是什么
认证怎么传
返回 JSON 是什么结构
哪些接口危险
而 Tool 可以直接告诉模型:
list_servers
=
查询服务器列表
get_server_stats
=
查询指定服务器 CPU、内存、磁盘
restart_server
=
重启指定服务器
这对 LLM 来说清楚很多。
所以:
API
是系统提供的能力。
而:
Tool / MCP
则是:
把这种能力包装成 AI 更容易稳定调用的接口。
十三、MCP 可以自动发现工具
假设 MCP Server 提供:
list_vms
get_vm_status
start_vm
stop_vm
delete_vm
Hermes 连接以后会进行 Tool Discovery。
随后这些工具就会进入 Hermes Tool Registry。
模型可能同时看到:
terminal
web_search
PVE.list_vms
PVE.get_vm_status
PVE.start_vm
然后自己根据任务选择。
所以用户一般只需要说:
看看 PVE 上 101 现在是不是开机。
而不是:
调用 PVE MCP 的 get_vm_status。
十四、这里马上会出现一个安全问题
刚才 MCP 提供:
list_vms
get_vm_status
start_vm
stop_vm
delete_vm
那么模型理论上也看得到:
delete_vm
如果这是生产环境:
这就不太安全了。
因此真正重要的不只是:
能接多少 Tool
而是:
Agent 到底应该看到哪些 Tool。
十五、生产环境优先使用 Tool 白名单
例如概念上:
mcp_servers:
pve:
url: "https://mcp.example.com/pve"
tools:
include:
- list_vms
- get_vm_status
- get_vm_stats
即使 MCP Server 实际还提供:
delete_vm
stop_vm
destroy_storage
Hermes 也不需要把这些工具暴露给模型。
模型:
根本看不到
通常比:
“Prompt 里告诉模型千万不要调用 delete_vm”
安全得多。
因为真正可靠的权限控制应该发生在:
Tool Layer
而不是只依赖 Prompt。
十六、推荐把“读取”和“修改”拆开
例如:
pve-readonly
只拥有:
list_vms
get_vm_status
get_node_status
get_storage_status
另一个:
pve-admin
拥有:
start_vm
stop_vm
reboot_vm
snapshot_vm
那么:
QQ Gateway
平时只加载:
pve-readonly
而:
本地管理 Session
才开放:
pve-admin
于是:
手机
↓
查询为主
服务器本地
↓
可以管理
这会比:
所有入口
↓
拥有所有工具
安全很多。
十七、这和上一篇 Gateway 权限正好能连起来
例如 QQ Gateway:
web
memory
skills
pve-readonly
minecraft-readonly
而本地:
hermes
可以使用:
terminal
files
pve-admin
minecraft-admin
这样:
不同入口
=
不同权限。
不要因为:
都是同一个 Hermes
就默认所有入口拥有完全相同的能力。
十八、远程 MCP 还涉及认证
如果 MCP 是远程服务:
Hermes
↓
Internet / Private Network
↓
MCP Server
就一定要考虑:
API Key
Bearer Token
OAuth
TLS
网络 ACL
来源 IP
客户端证书
至少不要直接:
0.0.0.0:端口
+
没有认证
暴露 MCP。
因为它背后可能拥有:
数据库
文件
服务器
内部 API
这些非常敏感的能力。
十九、如果没有现成 MCP,可以给 Hermes 写 Plugin
假设你的需求非常简单:
调用自己的 API 查询服务器状态
并且:
只准备给 Hermes 使用。
这时候甚至没必要单独维护 MCP Server。
可以使用 Hermes Plugin。
例如:
~/.hermes/plugins/server-panel/
├── plugin.yaml
├── __init__.py
├── schemas.py
└── tools.py
核心目的:
给 Hermes 增加一个新的 Tool。
二十、一个最小 Plugin
例如:
get_server_status
Tool。
plugin.yaml 可以类似:
name: server-panel
version: 1.0.0
description: 查询内部服务器管理 API
provides_tools:
- get_server_status
requires_env:
- SERVER_PANEL_API_KEY
Tool Schema:
GET_SERVER_STATUS = {
"name": "get_server_status",
"description": "查询指定服务器当前 CPU、内存、磁盘和运行状态。",
"parameters": {
"type": "object",
"properties": {
"server_id": {
"type": "string",
"description": "服务器 ID"
}
},
"required": ["server_id"]
}
}
这里最重要的是:
description
因为模型会根据它判断:
什么时候应该调用这个 Tool。
二十一、真正调用 API
例如:
import json
import os
import urllib.request
def get_server_status(args: dict, **kwargs) -> str:
server_id = args.get("server_id")
if not server_id:
return json.dumps({
"error": "server_id is required"
})
api_key = os.environ.get("SERVER_PANEL_API_KEY")
url = f"https://panel.example.com/api/servers/{server_id}/stats"
request = urllib.request.Request(
url,
headers={
"Authorization": f"Bearer {api_key}"
}
)
try:
with urllib.request.urlopen(request, timeout=10) as response:
data = json.loads(response.read())
return json.dumps(data)
except Exception as e:
return json.dumps({
"error": str(e)
})
核心原则:
输入
→ 明确定义
输出
→ 尽量结构化
错误
→ 返回可理解错误
不要让 Agent 自己猜 API。
二十二、注册 Tool
例如:
from . import schemas
from . import tools
def register(ctx):
ctx.register_tool(
name="get_server_status",
toolset="server-panel",
schema=schemas.GET_SERVER_STATUS,
handler=tools.get_server_status
)
最终:
Hermes
↓
加载 Plugin
↓
register()
↓
Tool Registry
↓
模型获得 get_server_status
以后直接问:
看看 hk01 现在状态怎么样。
模型就可以调用这个 Tool。
二十三、API Key 不应该写死在代码里
不要:
API_KEY = "xxxxxxxx"
更推荐放到:
~/.hermes/.env
例如:
SERVER_PANEL_API_KEY=xxxxxxxx
Plugin 代码:
os.environ.get("SERVER_PANEL_API_KEY")
读取。
这样至少不会:
Git 提交代码
↓
顺手把 Token 一起提交。
二十四、Plugin 和 MCP 怎么选?
可以使用这个简单判断。
如果:
只给 Hermes 用
工具很少
Python 就能完成
优先考虑:
Plugin
例如:
get_router_ip
get_server_status
restart_minecraft
如果:
准备长期维护
Tool 很多
多个 Agent 都需要使用
希望服务和 Agent 解耦
优先考虑:
MCP Server
例如:
PVE 管理平台
内部业务 API
大型数据库系统
企业管理后台
以后:
Hermes
Claude
Codex
Cursor
都可以连接同一套 MCP。
二十五、Skill 依然应该和它们配合
比如:
Minecraft MCP
提供:
get_status
get_players
get_logs
restart_server
send_command
然后建立:
minecraft-troubleshooting
Skill:
出现卡顿:
先检查 get_status
↓
再查看 TPS
↓
再查看玩家
↓
检查最近日志
↓
确认原因
↓
给出建议
↓
不要直接 restart_server
除非用户明确同意
于是:
MCP
=
可以做什么
Skill
=
应该怎么做
二者并不是互相替代。
二十六、完整案例:服务器管理面板
假设你有:
Server Manager API
提供:
list_servers
get_status
get_traffic
restart_server
把它封装为 MCP:
QQ
↓
Hermes Gateway
↓
Hermes Agent
↓
Server Manager MCP
↓
Server API
你在 QQ 发:
看看 hk01 现在状态怎么样。
Hermes:
识别 hk01
↓
调用 get_status
↓
获得:
CPU 17%
RAM 61%
Disk 42%
Uptime 18d
↓
回复
然后你继续:
顺便看看它最近流量。
因为当前 Session 已经知道:
它
=
hk01
所以继续:
get_traffic(hk01)
即可。
二十七、但是 restart_server 不应该默认开放给 QQ
比如:
QQ Gateway
只开放:
list_servers
get_status
get_traffic
而:
本地管理 Session
开放:
list_servers
get_status
get_traffic
restart_server
这样即使:
QQ Bot 出现安全问题
也不会直接拥有:
重启服务器
能力。
这也是 Agent 安全非常重要的思想:
不要只告诉 AI “不能做什么”,最好让它从权限上就做不了。
二十八、API Token 也应该使用最小权限
Tool 层做了只读限制以后:
后台 API Token
也最好是只读。
例如:
Hermes Readonly Token
只允许:
read server
read metrics
read logs
禁止:
delete
shutdown
modify user
change permission
于是安全边界变成:
Gateway Allowlist
↓
Hermes Toolset
↓
MCP Tool Whitelist
↓
API Token Permission
↓
Backend Permission
多层控制。
二十九、不要一次给模型几千个 Tool
有的大型 MCP Server:
可能提供几百甚至几千个 Tool。
全部塞给模型会有两个问题。
第一:
安全。
第二:
模型选 Tool 更困难。
如果模型需要从:
2000 个 Tool
里面选择:
1 个正确 Tool
不仅消耗大量上下文,也更容易误选。
所以:
Tool 不是越多越好。
而应该:
只开放当前场景真正需要的 Tool。
三十、第三方 MCP 本身也属于程序
这一点特别重要。
例如:
command: "npx"
args:
- "-y"
- "some-mcp-package"
本质上意味着:
下载第三方代码
↓
直接在你的服务器执行
所以:
MCP
并不是天然安全的。
第三方 MCP 应该像普通软件一样:
确认来源
检查项目
固定版本
限制运行用户
限制文件权限
限制网络权限
必要时放进 Container
尤其不要在重要生产服务器上随便运行来源不明的 MCP Server。
三十一、MCP 和 Docker 配合非常合适
例如:
Filesystem MCP
Database MCP
Browser MCP
都可以考虑放到:
Docker
里面。
最终:
Hermes
↓
MCP
↓
Container
↓
受限目录 / 数据库 / API
而不是:
Hermes
↓
第三方 MCP
↓
整个宿主机
对于文件系统、数据库和 Shell 类 Tool,这一点尤其重要。
三十二、自己的系统推荐分成 Read 与 Admin 两层
例如:
PVE Readonly MCP
list_vms
get_status
get_storage
以及:
PVE Admin MCP
start_vm
stop_vm
reboot_vm
snapshot_vm
Minecraft:
Minecraft Readonly
get_players
get_tps
get_logs
Admin:
restart_server
send_command
kick_player
NAS:
Readonly
get_storage
get_disk_health
Admin:
delete_snapshot
start_scrub
这样整个权限体系会清晰很多。
三十三、整个 Hermes 扩展体系怎么理解?
现在可以画成:
Hermes
┌────────────┼────────────┐
│ │ │
↓ ↓ ↓
Skills Plugins MCP
│ │ │
↓ ↓ ↓
工作方法 本地新能力 外部新能力
│ │ │
└────────────┼────────────┘
↓
Tools
↓
Agent 可以真正执行
再把前几篇加入:
Memory
=
知道你的环境
Skills
=
知道应该怎么做
Tools
=
真正能够执行
Plugin
=
Hermes 本地扩展
MCP
=
连接外部能力
Gateway
=
你怎么找到 Agent
Cron
=
Agent 什么时候主动工作
整个 Hermes 的架构就比较清楚了。
三十四、给新手一个选择公式
以后想扩展 Hermes 时:
只是说明、经验和步骤?
↓
Skill
需要增加一个 Hermes 专用的小能力?
↓
Plugin
已经有 MCP,
或者准备让多个 AI 共用?
↓
MCP
只是运行几个 Linux 命令?
↓
Terminal + Skill
选择最简单、稳定、安全的方法即可。
三十五、一个完整的私人 Agent 架构
最终可以做到:
手机
│
QQ / 飞书
│
↓
Hermes Gateway
│
↓
Hermes Agent
│
┌─────────────┼─────────────┐
↓ ↓ ↓
Memory Skills Tools
│
┌─────────────┼─────────────┐
↓ ↓ ↓
Built-in Plugin MCP
│ │ │
↓ ↓ ↓
Web/File 私人小工具 外部系统
│
┌─────────┼─────────┐
↓ ↓ ↓
PVE Minecraft NAS/API
Cron 再负责:
定时触发
↓
Hermes
↓
Skill
↓
MCP
↓
真实系统
↓
Gateway 通知
这样前面几篇介绍的组件就全部串起来了。
三十六、最终实战场景
假设家里有:
PVE
+
Minecraft
+
OpenWrt
+
NAS
分别提供:
PVE MCP
list_vms
get_node_status
Minecraft MCP
get_players
get_tps
get_logs
OpenWrt Plugin
get_wan_status
get_public_ip
NAS MCP
get_storage_usage
get_disk_health
你直接在 QQ 问:
家里的设备现在有没有异常?
Hermes:
读取 Memory
↓
知道有哪些设备
↓
加载 home-infra-health-check Skill
↓
PVE MCP
→ 查看虚拟机
↓
OpenWrt Tool
→ 查看 WAN
↓
NAS MCP
→ 查看磁盘
↓
Minecraft MCP
→ 查看服务器
↓
综合分析
↓
QQ 回复
最终可能得到:
整体正常。
需要关注两项:
1. NAS volume1 已使用 84%,
最近空间增长较快。
2. Minecraft 当前 TPS 18.4,
需要关注实体 Tick。
PVE 节点正常。
OpenWrt WAN 正常。
当前未执行任何修改操作。
这时候你已经不需要自己记:
PVE API 怎么调用
Minecraft 怎么查询
NAS Endpoint 是什么
OpenWrt 怎么认证
这些细节全部被:
Tool
封装起来。
Hermes 只负责:
理解你的目的
↓
选择正确工具
↓
组合结果
↓
给出判断
这才是 Agent 真正适合做的事情。
三十七、最后总结
这一篇最重要的,不只是:
学会 MCP。
而是理解整个扩展体系:
Memory
=
环境与事实
Skill
=
经验与工作流程
Tool
=
真正的能力
Plugin
=
Hermes 本地扩展
MCP
=
标准化外部能力
Gateway
=
消息入口
Cron
=
自动触发
最终:
用户
↓
QQ / 飞书
↓
Gateway
↓
Hermes
↓
Memory
+
Skills
↓
Tools
↓
Plugin / MCP
↓
真实系统
当这一层打通以后,Hermes 就不再只是:
能帮你执行 Shell 的 AI。
而开始真正成为:
你自己整个数字基础设施的自然语言控制层。
能力越强,安全问题也越重要。
建议始终坚持:
能只读
就不要给写入
能白名单
就不要全开放
能限制一个目录
就不要开放整个文件系统
能用专用 Token
就不要使用管理员 Token
危险操作
尽量需要人工确认
Agent 最安全的 Tool:
不是 Prompt 告诉它“不要乱用”的 Tool。
而是:
从权限上就根本无法执行危险操作的 Tool。
下一篇
现在我们已经有:
Memory
Skills
Gateway
Cron
MCP
Custom Tools
那么下一步就是:
一个 Agent 面对非常复杂的任务时,能不能自己拆任务、并行调查?
所以下一篇可以写:
《Hermes Agent 入门(七):Subagent、Delegate 与多 Agent 协作,让 AI 学会分工》
比如:
QQ:
“昨晚网站为什么出现几次 502?”
↓
主 Agent
├── Agent A
│ 查 nginx
│
├── Agent B
│ 查 Docker
│
├── Agent C
│ 查 CPU / IO
│
└── Agent D
查数据库
↓
主 Agent 汇总
↓
发现:
23:14 - 23:18
数据库连接池耗尽
↓
QQ:
完整故障分析
+
建议方案
+
当前未执行任何修改
到了这一阶段,Hermes 就会从:
一个会调用很多工具的 Agent
进一步变成:
能够拆任务
+
并行调查
+
分工
+
汇总结果
的 Agent 系统。
- 点赞
- 收藏
- 关注作者
评论(0)