Elyum MCP

Let Claude, Cursor, Codex — any MCP client — create in your Elyum workspace: cinematic shots, mini dramas with a recurring cast, music videos, UGC clips, product images, talking avatars, music and voice-overs, and full ad test packs. Same metering as the studio: renders come back as locked previews and nothing is charged until a take is kept.

Connect

Endpoint: https://elyum.ai/mcp (Streamable HTTP). Auth: an API key from /account/developer 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, the kill allowance, 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/developer 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 is a full AI creative studio — every top video, image, audio and avatar model in one place, cheaper than anywhere else in the market. People make cinematic shots and short films, mini dramas with a recurring cast, music videos, UGC and creator content, product and brand work, explainers, talking avatars, music, voice-overs and sound. The disruptive part is **Keep/Kill**: every render comes back as a locked preview, nothing is charged until you keep it, and a render you don't like is killed for a full credit refund. Misses cost nothing — in practice that drives cost per usable output down 70%+ versus the next cheapest alternative. On top of raw model access, the same tools produce finished pieces when asked: creator-fronted UGC clips, talking avatars, and multi-angle ad test packs.

## The doctrine (read this first)
- **Format first.** Find out what is being made before you pick a tool — a film scene, a mini drama, a music video, a UGC clip, a product shot, an explainer. Never assume an ad; a photo or a link is a reference until the user says it is a product.
- **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. Previews are never limited; kills are an allowance per billing period (an expiry counts as one). So: render freely, look at everything, keep only the good ones, and don't kill what you can simply leave.
- **Render freely; the misses are free.** Nobody gets the perfect take first try. Run several attempts (different prompts, different models), judge them all, keep the one that's right. On Elyum extra attempts cost nothing until you keep, so volume of tries is the strategy — never nurse one prompt.
- **Outcomes, not knobs.** Say *what* you want — Elyum routes to the right model, serializes the params, and falls back when a model fails. Pass a specific `model` slug only when the user asks for one; otherwise omit it and let the role default work.
- **Consistency is a reference.** A character, a set or a product stays the same across shots when the same reference stills ride along on every render: `elyum_make_video` mode `ref` with `imageUrl` + `imageUrls` (they are @Image1, @Image2… in the prompt), `productUrl` for a product, `creatorId` for a saved face. Repeat the wardrobe and lighting words too.
- **Look before you keep.** Results include a thumbnail / poster frame. Judge it: right subject? face consistent with the reference? readable framing for the aspect? continuity with the previous shot? 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` when there is a product) — 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 batch** keeps the account looking human; **rotate creators** when you want the audience to see variety. `elyum_run_test_pack` rotates `creatorIds` for you.

## Formats (what to do for each)
Elyum does not stitch clips yet: deliver the parts in order and say so.
- **Cinematic shot / short film**: a shot list → one key frame per shot (`elyum_make_image`, one look sentence — lens, palette, time of day — repeated in every prompt, 16:9) → `elyum_make_video` mode `i2v` per approved frame (5–10 s, audio on, the camera move in the prompt) → music or ambience with `elyum_make_audio`.
- **Mini drama**: cast stills first (`elyum_make_image`, full body, neutral background, wardrobe spelled out — or a saved creator), then one `elyum_make_video` mode `ref` per scene with the stills as `imageUrl` + `imageUrls`, the line of dialogue in quotes, 9:16, 5–10 s, audio on. Same stills, wardrobe words and lighting words in every scene; re-run a scene whose face drifted.
- **Music video**: the track first (`elyum_make_audio` mode `music`, 60–120 s; the price scales with length), then a visual concept and 6–8 clips (`t2v`, or `ref` with a performer still) mapped to its sections, audio off.
- **UGC / creator content**: `elyum_make_video` with `creatorId` (+ `productUrl`), hook first. Ad variants at volume: `elyum_run_test_pack`.
- **Product / brand**: `elyum_make_image` with `productUrl` (pixel-faithful) for studio shots, scenes, lifestyle and thumbnails; animate a still with `i2v`.
- **Explainer / faceless**: script beats → stills → `i2v` on the strongest → `elyum_make_audio` mode `tts` for the voice-over.
- **Talking avatar**: `elyum_make_avatar` from a photo + script.

## The workflow (single renders — the main lane)
1. `elyum_account` — balance, plan, kills left this period.
2. `elyum_estimate` — quote the render before running it.
3. Submit:
   - Image: `elyum_make_image` — a photo as `productUrl` keeps the subject pixel-faithful; `creatorId` puts a saved creator in the shot; `imageUrls` are style/character references.
   - Video: `elyum_make_video` — `t2v` (text only), `i2v` (animate a frame), `ref` (reference stills/clips → a NEW shot that keeps the look — the film and drama move), `ugc` (creator + product), `clone` (a reference clip's motion/pacing with your creator/product swapped in), `captions` (burn karaoke subtitles), `edit`, `extend`.
   - Audio: `elyum_make_audio` — `tts` (voice-over), `music` (a track), `sfx` (one sound). Charged on render.
   - Avatar: `elyum_make_avatar` — talking head from a photo + script (use a creator's imageUrl).
4. `elyum_wait` with the returned `jobId` until `status:"done"`.
5. Judge the preview. `elyum_keep` what's good (the only charge), `elyum_kill` what isn't (full refund), re-run with a sharper brief.

## The workflow (test pack — ads)
When the user wants a batch of finished ads for one product:
1. `elyum_creators` — pick 1–3 creators that fit the audience (or `elyum_add_creator` from the customer's own photo).
2. `elyum_upload` the product photo if it isn't already a URL.
3. `elyum_estimate` with `variants` — quote it.
4. `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`.
5. `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).
6. Look at each ad's poster + hook. `elyum_keep` the ones you'd actually post, `elyum_kill` the rest (or leave them to expire).
7. `elyum_export_pack` — a zip (mp4 + sidecar txt per ad + pack.csv) of the kept ads. Hand the user the URL and the CSV.
8. When the user tells you which one won: `elyum_run_test_pack` again with `seedAngle` = that variant's `angle` — "more like this".

## Traps
- A locked render can't be used as an input to another tool (409 `locked`). Keep it first.
- `409 kill_allowance`: the plan's kills for this billing period are used up — previews are never limited, kills are (an expiry counts as one too). Keep what is good, tell the user, or they can upgrade.
- `429 key_cap`: this API key's daily credit cap. Tell the user; don't retry in a loop.
- `503 maintenance` ("Supplier under maintenance"): every render is refused on every model while the studio's supplier is being serviced; nothing was held. Tell the user and try again later — 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.