Elyum MCP

Let Claude, Cursor, Codex — any MCP client — make ad creative in your Elyum workspace: images, UGC clips, avatars and full test packs. Same metering as the studio: renders come back as locked previews and nothing is charged until an ad is kept.

Connect

Endpoint: https://elyum.ai/mcp (Streamable HTTP). Auth: an API key from /account as Authorization: Bearer ek_live_…, or OAuth — clients that support it discover our authorization server automatically and open a consent page where you pick scopes and a daily credit cap. There is also a stdio shim for clients that need one: npx -y @elyum/mcp.

claude mcp add --transport http elyum https://elyum.ai/mcp --header "Authorization: Bearer ek_live_…"

# or, OAuth (no key to paste):
claude mcp add --transport http elyum https://elyum.ai/mcp

Tools

Resources: elyum://guide, elyum://account, elyum://creators, elyum://models, elyum://pricing, elyum://jobs/{id}. Prompts (guided flows): test-pack, ugc-ad, clone-winner.

Scopes & safety

• read — list, estimate, status, library. generate — render (holds credits, charges nothing). spend — keep (the only charge).
• Daily cap per key/app: credits it may hold or spend in a rolling 24 h. A runaway loop stops at the cap, not at zero balance (429 key_cap).
• Everything else the studio enforces applies unchanged: pay-on-keep lock gates, preview budgets, concurrency limits, plan pricing. Locked previews can't be used as inputs; originals only leave once kept.
• clientRef on create tools makes retries idempotent. Revoking a key on /account signs the agent out immediately (OAuth apps included).

The playbook agents get

Served as elyum://guide, returned by elyum_account, and at /llms.txt. Drop it into a Cursor rules file / AGENTS.md / Claude skill if your client doesn't read MCP resources.

# Elyum — agent guide

Elyum makes ad creative for direct-response teams: images, short videos, creator-fronted UGC clips, talking avatars, and — the product we care most about — **test packs**: N finished ads for one product, each a different angle, ready to post.

## The doctrine (read this first)
- **Sell tests, not videos.** Nobody knows which ad will win. Make several distinct angles, post them all with the same budget, kill the losers after 48 h, make more like the winner. Prefer `elyum_run_test_pack` over one hand-crafted clip.
- **Pay only for what you keep.** Every render comes back as a *locked preview* (480p, watermarked). Nothing is charged until you call `elyum_keep`. `elyum_kill` releases the credits (free). Unreviewed previews expire in 72 h and are released. So: render freely inside the preview budget, look at everything, keep only the good ones.
- **Look before you keep.** Results include a thumbnail / poster frame. Judge it: right product? face consistent with the creator? readable framing for 9:16? If it's off, kill it and re-run with a sharper brief. Never keep something you haven't looked at.
- **Quote first.** `elyum_estimate` is free. Say what a run will cost before you run it when the user is watching credits.
- **UGC = creator + product.** For selfie-style talking clips use `elyum_make_video` with `creatorId` (+ `productUrl`) — mode is inferred as `ugc`. 6–15 s. The hook is the first sentence; write it like a person, not a brand.
- **Same creator across a pack** keeps the account looking human; **rotate creators** when you want the audience to see variety. `elyum_run_test_pack` rotates `creatorIds` for you.

## The workflow (test pack)
1. `elyum_account` — balance, plan, previews left today. Stop early if a pack won't fit.
2. `elyum_creators` — pick 1–3 creators that fit the audience (or `elyum_add_creator` from the customer's own photo).
3. `elyum_upload` the product photo if it isn't already a URL.
4. `elyum_estimate` with `variants` — quote it.
5. `elyum_run_test_pack` — product name, a 1–3 sentence description, audience, 3–8 voice-of-customer lines (real phrases customers use), `variants` 4–8, `mode:"ugc"`, `captions:true`.
6. `elyum_wait` until `status:"done"` (a pack takes 3–8 minutes; call again while it says running — it returns the log so you can narrate progress).
7. Look at each ad's poster + hook. `elyum_keep` the 2–4 you'd actually post, `elyum_kill` the rest (or leave them to expire).
8. `elyum_export_pack` — a zip (mp4 + sidecar txt per ad + pack.csv) of the kept ads. Hand the user the URL and the CSV.
9. When the user tells you which one won: `elyum_run_test_pack` again with `seedAngle` = that variant's `angle` — "more like this".

## Single renders
- Image: `elyum_make_image` — product photo as `productUrl` keeps the product pixel-faithful; `creatorId` puts the creator in the shot.
- Video: `elyum_make_video` — `ugc` (creator+product), `i2v` (from an image), `t2v` (text only), `clone` (a reference clip's motion/pacing with your creator/product swapped in), `captions` (burn karaoke subtitles), `edit`, `extend`.
- Avatar: `elyum_make_avatar` — talking head from a photo + script (use a creator's imageUrl).
- After submitting: `elyum_wait` with the returned `jobId`.

## Traps
- A locked render can't be used as an input to another tool (409 `locked`). Keep it first.
- `429 preview_budget`: the plan's 24 h preview budget is used up — keep/kill what's pending, or wait.
- `429 key_cap`: this API key's daily credit cap. Tell the user; don't retry in a loop.
- `402`: not enough credits to keep. Don't kill things to "make room" without asking.
- Don't poll faster than `elyum_wait` does. Don't re-submit a render because a wait timed out — call `elyum_wait` again with the same jobId.
- Pass `clientRef` (any unique string) on create tools; a retry with the same ref replays instead of rendering twice.

REST

Everything the tools do is also plain HTTPS — see the API reference.