Run Hermoso from any MCP client

Hermoso’s server is a plain Model Context Protocol server, so “which client?” is mostly a question about config syntax rather than capability. There are two ways in and both reach the same 301 tools.

The two transports

• Hosted, streamable HTTP — https://app.hermoso.ai/mcp. This is the one most clients want. It supports OAuth with dynamic client registration and PKCE, so a client that speaks the full authorization flow needs no key at all; a client that does not can send an Authorization: Bearer hmk_… header instead. Note it is streamable HTTP only — there is no legacy HTTP+SSE endpoint, so a client that speaks only the old transport has nothing to connect to here.
• stdio, via npm — npx -y hermoso mcp, with your key in HERMOSO_TOKEN. Any stdio MCP client can load it. The same package is also a CLI (npm install -g hermoso), which is the token-cheap path for terminal agents: they shell out per command instead of carrying a 301-tool manifest through every turn.

Agents can auto-discover the server card at /.well-known/mcp.json, and it is listed in the official MCP registry as io.github.hermoso-ai/hermoso.

The generic config block

Most clients take some spelling of this:

{ "mcpServers": { "hermoso": {
    "url": "https://app.hermoso.ai/mcp",
    "headers": { "Authorization": "Bearer <your key>" }
} } }

Create the key in Hermoso under Settings → Agents & API keys. One client is a genuine exception: Codex reads TOML, not JSON, so a copied mcpServers block will not load there — see the Codex page for the four lines it wants instead.

Clients with their own page

• Claude — connects with OAuth, nothing to paste.
• ChatGPT — connects with OAuth, nothing to paste.
• Claude Code — takes an API key in an Authorization header; a terminal agent, so the CLI is the cheaper path for long runs.
• Cursor — takes an API key in an Authorization header.
• Codex — takes an API key in an Authorization header; a terminal agent, so the CLI is the cheaper path for long runs.
• Cline — takes an API key in an Authorization header.
• OpenClaw — takes an API key in an Authorization header; a terminal agent, so the CLI is the cheaper path for long runs.
• Hermes — takes an API key in an Authorization header; a terminal agent, so the CLI is the cheaper path for long runs.

Two clients deliberately have no page of their own, and it is worth saying why rather than implying broader support than we have tested. VS Code: Hermoso publishes a one-click VS Code deeplink, but there is no VS Code install block anywhere in the product and no tested path — so there is no page claiming one. The deeplink installs the bare endpoint and leaves authentication to VS Code’s own OAuth. Claude Desktop: Claude Desktop uses the identical Connectors flow as claude.ai, so it is covered by the Claude page rather than duplicated.

Every channel, from any of them

The client does not change what is reachable. From any of them: publish and schedule to Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest; research the Meta, Google and LinkedIn ad libraries plus organic TikTok, Instagram, YouTube, Reddit and Threads; render finished image and video ads across 50+ models; and build campaigns on Meta, Google Ads, Microsoft Advertising, Reddit Ads, LinkedIn, Pinterest and ChatGPT Ads.

Two publishing surfaces are built and held back, each waiting on the platform: Reddit — post_to_reddit is built and reddit_post_stats reads a post back, but Reddit’s Responsible Builder Policy requires explicit written approval before an app may use the Data API, and that ticket has not been granted. The connector is held back rather than offered as an OAuth screen leading to a dead API. Reddit Ads is a different connection and it is live — the full campaign tree, forecasting, targeting search, pixels and lead forms. Google Business Profile — post_to_google_business is built, with events, offers and a real call-to-action choice, and so are the listing insights. Google allowlists the Business Profile API per project and the default quota is zero, so every call would 403 for every user. It stays gated until Google grants the project access.

What no client can do on its own

An agent with a budget is only useful if the blast radius is bounded, so the fence is in the server rather than in a prompt. Every ad campaign, ad set, ad group and ad is created paused, and the status switches that arm real money refuse to run without an explicit confirmation flag. Every render is quoted first — hermoso_capabilities publishes each model’s exact credit cost before anything spends — and credits are reserved before the first provider call and settled at the exact cost afterwards, so a failed dispatch refunds rather than leaving you billed for nothing. Deletes are confirm-gated too, and every campaign tree is read back from the ad platform before your agent tells you what it built.

One step is deliberately not headless: linking an account is an OAuth consent screen, so you connect the channel once in a browser. Everything after that is a tool call.

Frequently asked questions

Does Hermoso work with any MCP client?

Over stdio, yes — any client that can launch npx -y hermoso mcp gets all 301 tools. Over the hosted endpoint it is streamable HTTP only: there is no legacy HTTP+SSE route, so a client that speaks only the old transport has nothing to connect to.

Do I need an API key, or does OAuth work?

Both paths exist. The hosted endpoint supports OAuth with dynamic client registration and PKCE, which is how the Claude and ChatGPT connectors sign in with nothing pasted. Every other client in our instructions uses an API key (hmk_…) in an Authorization: Bearer header, created under Settings → Agents & API keys.

What is the MCP endpoint URL?

https://app.hermoso.ai/mcp, declared as a streamable-HTTP remote in the server card at /.well-known/mcp.json. The package is hermoso on npm and io.github.hermoso-ai/hermoso in the official MCP registry.

Can an agent spend money without asking?

No. Ad campaigns are created paused with no caller override, the status switches that arm real money refuse to run without an explicit confirmation flag, and every generation call authenticates and bills a real account — there is no anonymous spend. Credits are reserved before the first provider call and settled at the exact cost, so a failed dispatch refunds.