hermosodocs

Quickstart

Two minutes from nothing to an agent that can research, generate and publish ads. In a coding agent it is one install command and one sign-in. In a chat app like Claude or ChatGPT it is the hosted connector.

1. Get an account

Sign up at app.hermoso.ai. The free tier is enough to explore, and the plans and credits are the same ones the web Studio uses. There is no separate developer billing.

Onboard a brand while you are there. It takes one field (a website domain, a description, or a social handle) and it is what makes the difference between a generated picture and a usable ad. See brand context.

2. In a coding agent: one command

Each install adds four Hermoso skills (research, ad-from-brand, generate, product-photoshoot) that drive the CLI through npx. No MCP server comes with them, so no tool list is loaded into your sessions, and nothing costs context until a command runs. The CLI still reaches every tool.

Claude Code:

claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso

Already inside a session? Type /plugin marketplace add hermoso-ai/hermoso, then /plugin install hermoso@hermoso.

Codex CLI (it reads the same marketplace file):

codex plugin marketplace add hermoso-ai/hermoso && codex plugin add hermoso@hermoso

Gemini CLI (installs the latest release of the extension):

gemini extensions install https://github.com/hermoso-ai/hermoso

Cursor, Cline, OpenCode, OpenClaw, Hermes and many more, through the open skills installer. It asks which agents to install into; -a cursor (or cline, opencode, openclaw, hermes-agent) picks one, and -g installs it for every project:

npx skills add hermoso-ai/hermoso

Then sign in once. It opens your browser; your agent also runs it by itself the first time it needs Hermoso:

npx -y hermoso auth login

On a machine with no browser, use a key instead (see step 4): npx -y hermoso auth login --token hmk_…. Rather install the CLI by hand? npm install -g hermoso puts the same hermoso command on your PATH, and the skills use it when it is there.

Now ask for what you want in your normal prompts. The agent picks the skill for the job and runs the commands.

3. In Claude, ChatGPT or another chat app: the hosted connector

If your client runs in a browser, this is the whole setup. In Claude: Settings → Connectors → Add custom connector, then paste:

https://app.hermoso.ai/mcp

Approve it with your Hermoso account and you are done. Authorisation is OAuth, so no key is created or stored anywhere, and the connection is bound to your account, your brand workspace and your plan.

In Claude Code, use the install in step 2 instead. The hosted endpoint is accepted there, but the client will not start the OAuth flow by itself: claude mcp list then reports ! Needs authentication, and you have to open a session, run /mcp, find the server and press Authenticate. Measured against Claude Code 2.1.241 on 2026-08-23.

4. An agent key: for a machine with no browser, CI and scripts

In the app: Settings → Agents & API → Create API key. You get a key beginning hmk_.

The full key is shown exactly once. Only its first 12 characters are retrievable afterwards. Keys do not expire; you revoke them. An account may hold up to 10 at a time.

5. Optional: the MCP server in a coding agent

The skills are the recommended path, because a tool list costs context in every session. If you also want Hermoso's tools in the agent's own tool list, sign in once and register the stdio server. No key goes into .claude.json:

npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp

Or pass the key explicitly, which is what CI wants:

claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp

Cursor, or anything else that reads an mcp.json (Codex takes the TOML equivalent):

{
  "mcpServers": {
    "hermoso": {
      "command": "npx",
      "args": ["-y", "hermoso", "mcp"],
      "env": {
        "HERMOSO_API_BASE": "https://app.hermoso.ai",
        "HERMOSO_TOKEN": "hmk_…"
      }
    }
  }
}

6. First calls

Ask your agent for something real. Under the hood the useful opening move is always the same:

hermoso_capabilities   # free. Model ids, exact credit costs, which channels are connected.
hermoso_credits        # free. What the balance is before anything spends it.
get_brand              # free. What the workspace already knows about this brand.

All three cost nothing. hermoso_capabilities matters most: it is the only honest source for valid model ids and their prices, and it reports the live connector state, so an agent never tells someone to connect a channel this build does not offer.

Then try the real thing, in plain language to your agent:

“Find the longest-running Meta ads for a competitor, then plan and render a 15-second version for my brand.”

That runs search_meta_ads → plan_ad → render_ad. The render is a job: it is submitted, polled to completion, and returns a served URL.

Choosing a brand workspace

One account can hold many brand workspaces. That is how an agency runs several clients through one connection.

list_brands            # what this account has
use_brand              # pin this key to one of them
create_brand           # take on a new client

use_brand pins the workspace on the server, against the key. Every later request re-resolves and re-authorises that pin, so a workspace whose access was revoked stops working immediately, and a caller cannot select a workspace by setting a header.

What a key cannot do

Deliberately, and it will answer 403 rather than half-succeeding:

Next