본문으로 건너뛰기

Tutorial

Use Hermes AI API from Claude Code with MCP

Connect Claude Code to the Hermes AI API MCP server, sign in with OAuth, and let it find a model, run a task and fetch the result for you.

Hermes AI team4 min read

This article is available in English only.

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.

terminal
claude mcp add --transport http hermes-ai-api https://api.hermes-ai.net/mcp

Sign 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:

  1. Claude Code calls the endpoint without a token. The server answers 401 with a WWW-Authenticate header that points to its resource metadata.
  2. Claude Code reads that metadata, finds the authorization server and registers itself. Registration is open and requires PKCE.
  3. You sign in and approve the request in the browser.
  4. 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

ToolWhat it does
search_modelsFind models by output type or keywords, with prices.
get_modelRead a model's input fields, allowed values and current price.
create_taskRun a model. Charges credits only if the task succeeds.
wait_for_taskWait until a task finishes and return its results.
get_taskCheck a task. Finished images are returned inline.
list_tasksList your recent tasks.
get_balanceShow 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:

prompt
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:

  1. search_models to find Nano Banana Pro and its model ID, nano-banana-pro-text-to-image-economy.
  2. get_model to read the input schema: prompt, aspectRatio and resolution, with their allowed values.
  3. create_task with an input such as { "prompt": "…", "aspectRatio": "16:9", "resolution": "2k" }.
  4. wait_for_task until 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

ProblemFix
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 codeTool 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 runThe 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:

mcp.json
{"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:

terminal
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/skills

Next steps

All prompt examples

Product shot on a seamless backdrop

Studio product photo of a matte amber glass dropper bottle on a seamless warm grey backdrop. Soft key light from the upper left, a gentle shadow to the right, a thin rim light on the glass. Shot on a 100mm macro lens at eye level, centered with generous space above. The paper label reads "Night Serum" in a clean serif and "30 ml" underneath in small caps.

이미지Nano Banana Pro

nano-banana-pro-text-to-image-economy