Hermes AI API runs a remote MCP server at https://api.hermes-ai.net/mcp. Once Claude Code is connected to it, you can ask for an image, a video or a song in plain language: Claude Code looks up a model, reads its input schema, runs the task on your credits and returns the result. You do not handle an API key; you sign in once in the browser.
This tutorial covers the setup, what the connection is allowed to do, the tools Claude Code gets, and the problems you may run into.
Add the server
Run this in a terminal. It registers the server under the name hermes-ai-api and talks to it over Streamable HTTP.
claude mcp add --transport http hermes-ai-api https://api.hermes-ai.net/mcpSign in
In Claude Code, run /mcp and choose hermes-ai-api. Your browser opens the Hermes AI sign-in page. Sign in with Google or GitHub and allow the request on the consent page.
Behind that one click, the client follows the standard MCP sign-in flow:
- Claude Code calls the endpoint without a token. The server answers
401with aWWW-Authenticateheader that points to its resource metadata. - Claude Code reads that metadata, finds the authorization server and registers itself. Registration is open and requires PKCE.
- You sign in and approve the request in the browser.
- Claude Code receives an access token issued for this MCP server, plus a refresh token so it stays signed in.
What the connection can do
- It can run models and spend your prepaid credits, and read your tasks, results and balance.
- It cannot manage API keys, billing or payments, or use any admin feature.
- You can disconnect it any time. Account security lists every connected app, and disconnecting stops its access immediately.
Tasks are charged only when they succeed, at the quote fixed when the task is accepted.
The tools Claude Code gets
| Tool | What it does |
|---|---|
search_models | Find models by output type or keywords, with prices. |
get_model | Read a model's input fields, allowed values and current price. |
create_task | Run a model. Charges credits only if the task succeeds. |
wait_for_task | Wait until a task finishes and return its results. |
get_task | Check a task. Finished images are returned inline. |
list_tasks | List your recent tasks. |
get_balance | Show available, reserved and spent credits. |
The MCP server page lists each tool's inputs.
Ask for something
Describe what you want and which model to use, if you have one in mind. For example:
Use Hermes AI API to make a 16:9 image at 2k with Nano Banana Pro: a ceramic pour-over coffee set on a walnut counter in morning window light. Tell me the price before you run it.A typical run uses the tools in this order:
search_modelsto find Nano Banana Pro and its model ID,nano-banana-pro-text-to-image-economy.get_modelto read the input schema:prompt,aspectRatioandresolution, with their allowed values.create_taskwith an input such as{ "prompt": "…", "aspectRatio": "16:9", "resolution": "2k" }.wait_for_taskuntil the task finishes. Images come back inline, so Claude Code can show you the result.
Asking for the price first is worth keeping in your prompts: get_model returns it, and create_task accepts expected_price_micros so the task is refused if the price changed in between.
Long tasks
wait_for_task waits at most 120 seconds (60 by default). Video and music tasks can take longer. When it returns with the task still running, nothing is wrong: the task keeps going, and calling wait_for_task again with the same task_id picks it up. If Claude Code stops early, ask it to keep waiting. You can also check the task yourself in Task logs.
Troubleshooting
| Problem | Fix |
|---|---|
| 401 with "Sign in to use Hermes AI API" | Sign-in has not finished. Run /mcp and choose hermes-ai-api. |
| 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. |
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. |
get_model says the model cannot run | The model has no price configured right now. Pick another one; search_models shows which ones can run. |
Without OAuth: use an API key
If you would rather not sign in through the browser, send an API key instead. Create one in API keys, export it as HERMES_API_KEY, and add the header to the server configuration:
{"mcpServers": {"hermes-ai-api": {"url": "https://api.hermes-ai.net/mcp","headers": { "Authorization": "Bearer ${HERMES_API_KEY}" }}}}Optional: the Agent Skill
The Hermes AI API skill is a SKILL.md that teaches an agent the same workflow over the REST API. When the MCP server is connected, the skill tells the agent to use its tools instead. To install it for all your projects:
mkdir -p ~/.claude/skills
curl -L https://api.hermes-ai.net/skills/hermes-ai-api.zip -o /tmp/hermes-ai-api.zip
unzip -o /tmp/hermes-ai-api.zip -d ~/.claude/skillsNext steps
- The Claude Code integration guide has the same steps in short form.
- Other clients (Codex, Cursor, VS Code, Claude) are on the MCP server page.
- To call the API from your own code instead, follow Generate images with the Nano Banana Pro API.