hermosodocs

Quickstart

Two minutes from nothing to an agent that can research, generate and publish ads. Pick the hosted connector if your client supports remote MCP; pick stdio if you are in a terminal.

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.

2a. The hosted connector — no key, no install

If your client speaks remote MCP, 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 the same endpoint installs from the terminal:

claude mcp add --transport http hermoso https://app.hermoso.ai/mcp

2b. An agent key — for stdio, 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.

3. Connect

Claude Code, with the published npm package (no clone, no install step):

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_…"
      }
    }
  }
}

4. 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