hermoso

# Hermoso — MCP, CLI & Skills

Run your whole marketing operation from **any AI agent**: Claude Code, Claude.ai, Cursor, Codex, or your own
scripts. Research the ads already winning in a market, generate finished image & video ads (your real product
composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad
campaigns behind them — all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.

**801 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
catalog with exact per-render credit costs plus the full capability map.

**What it connects to.** Ad platforms: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads,
Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads and ChatGPT Ads, plus product feeds in
Google Merchant Center. Publishing and scheduling — **ten** channels: Facebook, Instagram, Threads, TikTok,
YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. Messaging: WhatsApp (you message a person, so it is not an
eleventh publishing channel). Ad research: the Meta, Google and LinkedIn ad libraries plus organic TikTok,
Instagram, YouTube, Threads and Reddit. Analytics: Google Analytics 4, Google Search Console and every
connected platform's own post and campaign insights. Files: Google Drive, Sheets, Docs and OneDrive.

**It is not all-or-nothing.** Research, creation, publishing/scheduling and ads management are four *independent*
areas — no tool requires that you used another one first. Publish or schedule creative you already have and
generate nothing here (`upload_file` turns any local or external file into a URL every publish, schedule and
ad-build tool accepts); build and read campaigns on your own ad accounts with your own creative; research
competitors with no brand drafted and no channel connected; or generate a file with nothing connected at all and
just download it. Use the one piece you need, or all of it together.

## Which surface should your agent use?

Two shapes, and the right one is decided by **what your client can do**, not by which we prefer.

| Your client | Use | Why |
| --- | --- | --- |
| **Runs in a browser** — Claude.ai, ChatGPT, Claude Desktop | the hosted connector `https://app.hermoso.ai/mcp` | It cannot spawn a local process, so a URL is the only shape it has. Nothing to install, no key to paste, and the full toolset arrives with your saved brand context. This is the right answer for these clients, not a lesser one. |
| **Can run a shell** — Claude Code, Cursor, Codex, Cline, OpenClaw, Hermes, your own scripts | the CLI, `npm install -g hermoso` | A tool manifest is loaded into every session whether or not a tool is called. A shell command costs nothing until it runs, and it reaches **every** tool rather than the default roster. |

**The measured difference** (2026-08-27, counted as real tool definitions rather than estimated from bytes):

| | tools in range | loaded per session |
| --- | --- | --- |
| Hosted connector, default roster | 306 | **181,713 tokens** |
| Hosted connector, `?tools=all` | 718 | **472,062 tokens** |
| stdio server (`npx -y hermoso mcp`) | 306 | **181,713 tokens** |
| **CLI** | **all 718** | **0** |

The CLI answers the same questions on demand instead, and only when asked:

```bash
npx -y hermoso tools --search reddit   # every matching tool, name + one line   2,459 tokens
npx -y hermoso tools plan_ad           # one tool's full argument schema           633 tokens
npx -y hermoso call plan_ad --json '{"product":"…"}'   # run it
```

So a terminal agent reaches its first call in roughly **3.4K tokens with the whole roster in range**, against
**182K for a fraction of it**. `tools` and `tools <name>` read a registry bundled in the package — no key, no
network, no sign-in — so an agent can browse the entire product before anyone signs in. Only `call` spends, and
only that needs `hermoso auth login` once.

**Both at once is fine, and is what we suggest for Claude Code.** One `hermoso auth login` covers the CLI *and*
lets `claude mcp add hermoso -- npx -y hermoso mcp` pick the key up with no `env` block, so the agent can reach for
a native tool when it wants structured results and shell out when it wants breadth. If you only want one, take the
CLI: it covers strictly more.

**When the connector is still the better trade on a shell-capable client:** a session that is going to make many
calls into one area. `enable_tools({groups:['ads']})` turns campaign management on in a single free call and the
tools are then native — no shell quoting, structured results. One shell round trip beats loading a 221K-token
group for a single tool; the reverse is true once a session settles into that area.

## Your agent can sign itself up

An agent with no Hermoso account can provision one, get its own key, and be rendering ads in the same session.
No human at a browser, no ticket, no waiting.

```bash
# 1. Start a signup. This call takes no credential, because the credential is what it creates.
curl -sX POST https://app.hermoso.ai/v1/signup \
  -H 'content-type: application/json' \
  -d '{"plan":"pro","period":"mo","email":"you@yourcompany.com"}'
# -> { "id": "cs_...", "checkout_url": "https://checkout.stripe.com/...", "claim_token": "hsc_...", "email": { "address": "you@yourcompany.com", "verified": false } }
# email = the human behind the account. A verification link goes there; the account works before it is clicked.
# It is a contact mailbox only, never a sign-in. GET /v1/account/email reports the state; POST /v1/account/email/resend re-sends or changes it.

# 2. Pay at checkout_url. Store claim_token first: it is returned only in that response.

# 3. Claim it. Poll until status is "ready".
curl -sX POST https://app.hermoso.ai/v1/signup/cs_.../claim \
  -H 'content-type: application/json' \
  -d '{"claim_token":"hsc_..."}'
# -> { "status": "ready", "api_key": "hmk_...", "credits": 3000 }
```

That `hmk_` key is the same credential everything else on this page takes: `/v1`, the MCP server, the CLI. Point
your client at it and the full surface is open.

**Paying is something a browser-capable agent can already do itself.** Checkout is Stripe's own hosted page, so
Claude in Chrome and clients like it complete it unattended today. Everything else is a one-click handoff: send
`checkout_url` to whoever holds the card. The same shape covers you later, once you are running: `buy_credits`
and `upgrade_plan` mint a ready-to-pay link for more credits or a bigger plan, and `billing_status` reads the
balance any time.

**An agent with its own payment credential can pay with no human at all.** `POST /api/billing/machine-payment`
with `{"packId": "pack-1k"}` answers HTTP 402 carrying a `WWW-Authenticate: Payment` challenge (Stripe, through the
Machine Payments Protocol); pay the challenge and retry, and the same credit pack lands on the same balance.
`GET /api/billing/config` lists the packs under `machinePayments`. Same packs, same prices, no per-call billing.

**The agentic path takes a paid plan.** Any of them. The free plan is there for a person signing up at
[app.hermoso.ai](https://app.hermoso.ai), and asking for it here returns a refusal that says so. Nothing is
created until the payment completes, so an unpaid signup leaves no account behind and charges nothing.

**One thing still wants a person, and it is worth knowing up front.** Connecting a social or ad account means an
OAuth consent screen, and a consent screen cannot be completed headlessly on any platform. `list_connectors`
shows what is already connected and what is not. Everything else runs with no browser at all: research,
generation, publishing to a channel that is already connected, campaign builds, reporting.

Full request and response shapes, plus every other endpoint, are in the OpenAPI document at
[app.hermoso.ai/openapi.json](https://app.hermoso.ai/openapi.json), served live from the same table that mounts
the routes.

## Instant: the hosted Claude.ai connector

Paste **`https://app.hermoso.ai/mcp?src=readme`** into Claude → Settings → Connectors → *Add custom connector*, pick
**Always required** when Claude asks about authentication (its detector suggests "None" because our discovery
handshake is open; "None" would leave every tool call unauthenticated), approve with your Hermoso account, done — the full toolset with your saved brand context, billed to your plan.

## Quickstart for Claude Code (one line)

1. **Get an account** at [app.hermoso.ai](https://app.hermoso.ai) — free tier included; plans & credits are the
   same ones the web Studio uses. Or skip the browser entirely and let your agent sign itself up on a paid plan
   with `POST /v1/signup` (above).
2. **Run one line.** Your browser opens once to sign in. Nothing to paste, and no key lands in `.claude.json`:

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

3. **Ask for what you want**, in your normal prompts. Claude Code reaches for a tool, or runs the `hermoso`
   command in your terminal, whichever the job needs. You type neither.

Ad campaign and analytics tools stay out of the tool list until you switch them on with `enable_tools`, which
keeps it small. On a machine with no browser, sign in with `hermoso auth login --token hmk_…` using a key from
**Settings → Agents & API**, or skip the sign-in and pass the key to the client instead:

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

The hosted URL works in Claude Code too, but it is the worse path there and it is worth knowing why:
`claude mcp add --transport http hermoso "https://app.hermoso.ai/mcp?src=readme"` is accepted, and then `claude mcp list`
reports `! Needs authentication` because the client will not start the OAuth flow by itself — you have to open a
session, run `/mcp`, find the server and press Authenticate. Measured against Claude Code