跳到主要内容

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/mcp
Claude Code 配置指南

登录流程

只需在浏览器中登录一次,无需把 API 密钥复制到客户端。

  1. 1客户端先在不带令牌的情况下调用端点,服务器返回 401,WWW-Authenticate 头指向资源元数据。
  2. 2客户端读取元数据,找到授权服务器并自行注册。注册无需审批,但必须使用 PKCE。
  3. 3浏览器打开 Hermes AI 登录页。用 Google 或 GitHub 登录,然后在授权页允许请求。
  4. 4客户端获得为该 MCP 服务器签发的访问令牌,以及用于保持登录的刷新令牌。

应用可以做什么

运行模型并使用你的预付额度,读取你的任务、结果和余额。

应用不能做什么

管理 API 密钥、账单或付款,或使用任何管理功能。

随时断开

“账户安全”会列出所有已连接的应用。断开后其访问权限立即失效。

管理已连接的应用

工具

每个工具调用与你的代码相同的 API,价格、额度预留和限制完全一致。

工具说明输入
search_models
列出 Hermes AI API 的图像、视频、音乐和文本生成模型。可按输出类型或关键词筛选。返回每个模型的 slug,create_task 需要用到。
  • query string, optional
    在名称、slug 或描述中匹配的词
  • output image | video | audio | text, optional
    只返回该输出类型的模型
get_model
获取一个模型的输入字段(类型、可选值、默认值、限制)和当前价格。调用 create_task 前先用它构造有效输入。
  • model string
    search_models 返回的模型 slug
create_task消耗额度
提交异步生成任务。仅在任务成功时从用户的预付额度中扣除报价金额。返回 task_id,之后调用 wait_for_task 或 get_task。网络出错后使用相同的 idempotency_key 重试是安全的。
  • model string
    模型 slug
  • input object
    get_model 返回的字段
  • idempotency_key string, optional
    可选;省略时自动生成,并在结果中返回以便重试
  • expected_price_micros integer, optional
    报价不一致时以 PRICE_CHANGED 拒绝
wait_for_task
每 4 秒查询一次任务,直到完成或超时,然后像 get_task 一样返回。若仍在运行,再调用一次。
  • task_id string
    create_task 返回的任务 ID
  • timeout_seconds integer 5–120, optional
    默认 60
get_task
获取任务状态和结果。生成的图片完成后会直接返回。
  • task_id string
    create_task 返回的任务 ID
list_tasks
列出用户最近的任务,最新的在前。
  • limit integer 1–100, optional
    默认 20
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 中。

错误码账单Agent Skills