Hermes AI API MCP 服务器
任何客户端都能通过 HTTP 访问的远程 MCP 服务器。添加一个地址,用 Hermes AI 账号登录,智能体就能查找模型、运行任务并获取结果,费用从预付额度中扣除。
https://api.hermes-ai.net/mcp端点
这个地址就是服务器本身,不是网页。MCP 客户端连接它;在浏览器中打开会返回 401 并要求登录。
| 设置项 | 值 |
|---|---|
| 端点 | https://api.hermes-ai.net/mcp |
| 传输方式 | Streamable HTTP |
| 服务器名称 | hermes-ai-api |
| 登录方式 | OAuth 2.1,使用 PKCE 和动态客户端注册 |
| 不使用 OAuth 时 | Authorization: Bearer <API key> |
| 资源元数据 | https://api.hermes-ai.net/.well-known/oauth-protected-resource/mcp |
| 授权服务器 | https://api.hermes-ai.net/.well-known/oauth-authorization-server/api/auth |
添加到你的客户端
选择客户端并复制命令或配置。每个客户端在文档中都有完整指南。
terminal
claude mcp add --transport http hermes-ai-api https://api.hermes-ai.net/mcpterminal
codex mcp add hermes-ai-api --url https://api.hermes-ai.net/mcp
codex mcp login hermes-ai-api~/.cursor/mcp.json
{
"mcpServers": {
"hermes-ai-api": {
"url": "https://api.hermes-ai.net/mcp"
}
}
}.vscode/mcp.json
{
"servers": {
"hermes-ai-api": {
"type": "http",
"url": "https://api.hermes-ai.net/mcp"
}
}
}Settings → Connectors → Add custom connector
https://api.hermes-ai.net/mcpmcp.json
{
"mcpServers": {
"hermes-ai-api": {
"url": "https://api.hermes-ai.net/mcp",
"headers": {
"Authorization": "Bearer ${HERMES_API_KEY}"
}
}
}
}适用于不支持 OAuth 登录的客户端。在控制台创建密钥,不要把它放进共享文件。 创建 API 密钥
登录流程
只需在浏览器中登录一次,无需把 API 密钥复制到客户端。
- 1客户端先在不带令牌的情况下调用端点,服务器返回 401,WWW-Authenticate 头指向资源元数据。
- 2客户端读取元数据,找到授权服务器并自行注册。注册无需审批,但必须使用 PKCE。
- 3浏览器打开 Hermes AI 登录页。用 Google 或 GitHub 登录,然后在授权页允许请求。
- 4客户端获得为该 MCP 服务器签发的访问令牌,以及用于保持登录的刷新令牌。
应用可以做什么
运行模型并使用你的预付额度,读取你的任务、结果和余额。
应用不能做什么
管理 API 密钥、账单或付款,或使用任何管理功能。
随时断开
“账户安全”会列出所有已连接的应用。断开后其访问权限立即失效。
工具
每个工具调用与你的代码相同的 API,价格、额度预留和限制完全一致。
| 工具 | 说明 | 输入 |
|---|---|---|
search_models | 列出 Hermes AI API 的图像、视频、音乐和文本生成模型。可按输出类型或关键词筛选。返回每个模型的 slug,create_task 需要用到。 |
|
get_model | 获取一个模型的输入字段(类型、可选值、默认值、限制)和当前价格。调用 create_task 前先用它构造有效输入。 |
|
create_task消耗额度 | 提交异步生成任务。仅在任务成功时从用户的预付额度中扣除报价金额。返回 task_id,之后调用 wait_for_task 或 get_task。网络出错后使用相同的 idempotency_key 重试是安全的。 |
|
wait_for_task | 每 4 秒查询一次任务,直到完成或超时,然后像 get_task 一样返回。若仍在运行,再调用一次。 |
|
get_task | 获取任务状态和结果。生成的图片完成后会直接返回。 |
|
list_tasks | 列出用户最近的任务,最新的在前。 |
|
get_balance | 获取用户以美元计的可用、预留和已消费预付额度。 | 无 |
故障排查
- 401,提示“Sign in to use Hermes AI API”
- 请求未携带令牌,说明登录尚未完成。在 Claude Code 中运行 /mcp 并选择 hermes-ai-api;在 Codex 中运行 codex mcp login hermes-ai-api;在其他客户端中点击服务器旁的“连接”或“启动”。
- 401,提示“The access token is invalid or expired”
- 令牌已过期、被撤销,或应用已在“账户安全”中断开。请在客户端中重新登录。
- 工具返回 INSUFFICIENT_CREDITS 或其他错误码
- 工具错误带有与 REST API 相同的状态码和错误码。可在“账单”中充值,或在错误码参考中查找。
- wait_for_task 返回时任务仍在运行
- 它最多等待 120 秒(默认 60 秒)。视频和音乐可能更久,用相同的 task_id 再调用一次即可。
- get_model 提示模型无法运行
- 该模型目前没有配置价格。从 search_models 中换一个模型,runnable 字段表示能否运行。
- 我的客户端不支持 OAuth 登录
- 改用 API 密钥:使用上方的 API 密钥标签页,并把密钥放在 HERMES_API_KEY 中。