Hermes AI API MCP server
A remote MCP server any client can reach over HTTP. Add one URL, sign in with your Hermes AI account, and your agent can find models, run tasks and fetch results, paid from your prepaid credits.
https://api.hermes-ai.net/mcp엔드포인트
This URL is the server itself, not a web page. MCP clients connect to it; opened in a browser it answers 401 and asks for sign-in.
| Setting | 값 |
|---|---|
| 엔드포인트 | https://api.hermes-ai.net/mcp |
| Transport | Streamable HTTP |
| Server name | hermes-ai-api |
| Sign-in | OAuth 2.1 with PKCE and dynamic client registration |
| Without OAuth | Authorization: Bearer <API key> |
| Resource metadata | https://api.hermes-ai.net/.well-known/oauth-protected-resource/mcp |
| Authorization server | https://api.hermes-ai.net/.well-known/oauth-authorization-server/api/auth |
Add it to your client
Pick your client and copy the command or config. Each one has a full guide in the docs.
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}"
}
}
}
}For clients without OAuth sign-in. Create a key in the console and keep it out of shared files. API 키 생성
How sign-in works
You sign in once in your browser. No API key is copied into the client.
- 1Your client calls the endpoint without a token. The server answers 401 with a WWW-Authenticate header that points to its resource metadata.
- 2The client reads that metadata, finds the authorization server and registers itself. Registration is open and requires PKCE.
- 3Your browser opens the Hermes AI sign-in page. Sign in with Google or GitHub, then allow the request on the consent page.
- 4The client receives an access token issued for this MCP server, plus a refresh token so it stays signed in.
앱이 할 수 있는 일
모델을 실행해 선불 크레딧을 사용하고 작업, 결과, 잔액을 읽습니다.
앱이 할 수 없는 일
API 키, 결제 또는 지불 관리, 관리자 기능 사용.
언제든지 연결 해제
계정 보안에 연결된 모든 앱이 표시됩니다. 연결을 해제하면 즉시 접근이 중단됩니다.
도구
각 도구는 코드와 같은 API를 호출하며 가격, 크레딧 예약, 한도가 동일합니다.
| 도구 | Description | Inputs |
|---|---|---|
search_models | List Hermes AI API models for image, video, music and text generation. Filter by output type or a search query. Returns each model's slug, which create_task needs. |
|
get_model | Get one model's input fields (types, allowed values, defaults, limits) and its current price. Call this before create_task to build a valid input. |
|
create_taskSpends credits | Submit an asynchronous generation task. Charges the quoted price from the user's prepaid credits only if the task succeeds. Returns a task_id; then call wait_for_task or get_task. Reuse the same idempotency_key to retry safely after a network error. |
|
wait_for_task | Poll a task every 4 seconds until it finishes or the timeout passes, then return it like get_task. Call again if it is still running. |
|
get_task | Get a task's status and results. Generated images are returned inline when ready. |
|
list_tasks | List the user's most recent tasks, newest first. |
|
get_balance | Get the user's available, reserved and spent prepaid credits in USD. | None |
Troubleshooting
- 401 with “Sign in to use Hermes AI API”
- The request carried no token, so sign-in has not finished. In Claude Code run /mcp and choose hermes-ai-api; in Codex run codex mcp login hermes-ai-api; in other clients choose Connect or Start next to the server.
- 401 with “The access token is invalid or expired”
- The token expired, was revoked, or the app was disconnected in Account security. Sign in again from your client.
- A tool returns INSUFFICIENT_CREDITS or another code
- Tool errors carry the same status and code as the REST API. Add credits in Billing, or look the code up in the error reference.
- wait_for_task returns while the task is still running
- It waits at most 120 seconds (60 by default). Video and music can take longer; call it again with the same task_id.
- get_model says the model cannot run
- The model has no price configured right now. Pick another model from search_models; runnable shows which ones work.
- My client has no OAuth sign-in
- Send an API key instead: use the API key tab above, with the key in HERMES_API_KEY.