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/mcpEndpoint
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 | Value |
|---|---|
| Endpoint | 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.
claude mcp add --transport http hermes-ai-api https://api.hermes-ai.net/mcpcodex mcp add hermes-ai-api --url https://api.hermes-ai.net/mcp
codex mcp login hermes-ai-api{
"mcpServers": {
"hermes-ai-api": {
"url": "https://api.hermes-ai.net/mcp"
}
}
}{
"servers": {
"hermes-ai-api": {
"type": "http",
"url": "https://api.hermes-ai.net/mcp"
}
}
}https://api.hermes-ai.net/mcp{
"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. Create API key
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.
What the app can do
Run models and spend your prepaid credits, and read your tasks, results and balance.
What it cannot do
Manage API keys, billing or payments, or use any admin feature.
Disconnect any time
Account security lists every connected app. Disconnecting stops its access immediately.
Tools
Each tool calls the same API as your code, with the same prices, credit holds and limits.
| Tool | 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.