Which surface should you use?

Four ways to drive Hermoso. They reach the same account, the same brand workspace and the same connected channels, and none of them is a lesser version of another. Pick by what is doing the work.

MCP, when an agent is deciding what to do next

The MCP server carries the whole toolset: 718 tools spanning ad research, creative generation, publishing, scheduling, eleven ad platforms and analytics. The CLI carries the same 718; what MCP adds is the shape, not the reach. Reach for it when the interesting part of the job is judgement rather than a fixed sequence, because the client holds the tools as a manifest and the agent can look at what came back and choose the next call.

Connect the hosted server at https://app.hermoso.ai/mcp, or run it over stdio with npx -y hermoso mcp. Both expose the identical toolset.

Handing a client every tool at once would swamp it, so the roster is sized for accuracy rather than for a headline: a working default set is on from the start, and the rest, mostly ad campaign management and analytics, switch on in a single free enable_tools call when a session needs them. Most of the defaults need no connected account at all, so a brand new key can do real work immediately.

CLI, when the caller is a shell

The CLI is the same 718 tools at a shell prompt. npm install -g hermoso, then hermoso auth login once. It is the right answer for scripts, cron jobs and CI, and for terminal agents that would rather shell out than carry a large tool manifest.

The REST API, when your own backend is calling

The REST API at /v1 is plain HTTPS with a bearer token and JSON. No SDK, no MCP client, no terminal — reach for it when the thing calling us is your own backend, in whatever language it is written in.

It comes in two tiers, and the difference is the promise rather than the reach. Modelled resources — posts, channels, media, credits — are a small versioned contract whose shape holds still: fields and endpoints get added, enums grow, and nothing already there is removed or retyped inside a version, so code you write this month keeps working. The tool passthrough at /v1/tools reaches all 718 tools, the same set MCP and the CLI carry, with the same scoping and the same spend; its envelope is stable and the tools inside it keep improving, so you read the roster rather than pinning it. Hard-code the first, introspect the second.

Server-side only. We send no CORS headers, because an API key carries full account authority and a key shipped to a browser is a key you have published.

An agent with no account at all can start here: POST /v1/signup provisions one on a paid plan and returns its own key.

The web app, for the things a browser is genuinely needed for

app.hermoso.ai is where you connect channels, review creative before it goes out, watch the calendar and manage billing.

One thing here is not an inconvenience we can engineer away. Linking a social or ad account means an OAuth consent screen, and a consent screen cannot be completed headlessly on any platform. list_connectors and GET /v1/channels both report what is already linked and what is not, so an agent can tell a person exactly which account to go and approve. Everything after that runs with no browser: research, generation, publishing to a channel that is already connected, campaign builds, reporting.

You do not have to pick one

Everything lives in one workspace, so the surfaces compose. Schedule a week of posts from your backend over /v1, watch them fire on the calendar in the app, and ask an agent over MCP why the one on Thursday did better than the rest.

Side by side

Next

• Quickstart. A key and a working connection in about two minutes.
• REST API. Endpoints, auth, rate limits and the compatibility promise.
• MCP server. Both transports, and the workspace headers.