The Lumorig MCP server gives any Model Context Protocol client 25 tools to create, rebuild, animate, export and embed mascots. Every tool goes through the public REST API via the TypeScript SDK, so the hosted server and the local one behave the same way, spend the same credits and see the same workspace.
Hosted server#
The hosted server speaks streamable HTTP at https://lumorig.com/api/mcp. There is no key to paste: add the URL, and the first time the client connects your browser opens a Lumorig page where you pick a workspace and click Allow. The client keeps a token from then on (OAuth 2.1 with PKCE, and clients register themselves), and you can disconnect it any time under Settings → Account → Connected apps.
claude mcp add --transport http lumorig https://lumorig.com/api/mcp
# then, in Claude Code: /mcp → lumorig → Authenticate (your browser opens once)A connected app acts as you in the one workspace you allowed, with your role there (a member can't manage keys or people through it). Tokens expire and refresh on their own; if a client ever shows “needs login” again, allow it again. The server's OAuth metadata is at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource for clients that discover it themselves.
Local server (stdio)#
Run the server on your machine with npx -y @lumorig/mcp and LUMORIG_API_KEY set. It still calls the API, but local mode adds three file parameters: image_path (create_mascot), video_path (animate_mascot) and save_to (export_mascot, create_scene), so an agent can rebuild the logo in your repo and write the Lottie file next to your code. Set LUMORIG_URL to point at a self-hosted server.
claude mcp add lumorig -e LUMORIG_API_KEY=lr_sk_… -- npx -y @lumorig/mcpWithout LUMORIG_API_KEY the stdio binary exits with an error pointing you at the studio settings. lumorig mcp uses your lumorig login key instead. See CLI & terminal companion.
Tools#
Parameters marked (local) exist only on the stdio server. Defaults are shown with =. Tools that change nothing are annotated read-only (list_mascots, get_mascot, analyze_website, suggest_animations, wait_for_job, list_jobs), so clients can run them without asking.
| Tool | Parameters | What it does |
|---|---|---|
create_mascot | prompt?, style?, image_url?, image_path? (local), notes?, max_credits? | Design a new mascot from a prompt, or rebuild an image as a rig. Waits (1–4 min) and returns a description plus a preview image. |
list_mascots | none | Every mascot in the workspace, with status and animation count. |
get_mascot | id | Name, status, palette tokens, parts and states, animations, and a preview image. |
edit_mascot | id, instruction, variant_name? | Change the design in words. With variant_name, makes a new look of the same rig and keeps the current one (switch_look switches between them). |
recolor_mascot | id, palette | Instant palette change by token name, e.g. { fur: "#3b82f6" }. No credits. |
set_logo_tagline | id, text, font? | A logo only: a tagline or web address under it, in sans, bold or mono. 10 credits to set or change; empty text takes it off. |
make_cinematic_intro | id, style, backdrop?, frame?, sound? | A logo only: generated sparks, smoke or ink that resolve into the logo and end on it exactly as drawn, as a 1080p MP4 of about 5 s, with a reveal sound if asked. 60 credits; a few minutes. |
switch_look | id, look | Make one of the mascot's looks current by name ("Original" or a variant). Instant, no credits. |
set_props | id, props | Show or hide props by id or name, e.g. { mug: false }. Instant, no credits. |
add_gear | id, gear | Give the mascot a ready-made prop with its motion (notes, book, laptop, sign, magnifier, phone, mug, megaphone, skateboard, stool, party), as a look of its own; none puts it away. Instant, no credits. |
turn_mascot | id, facing, amount? | Turn the mascot to a slight side view (left, right, or front to go back), as a look of its own. Instant, no credits. |
add_prop | id, description, name? | Draw something the mascot holds or wears as its own part, so it can be switched off later. A paid edit. |
animate_mascot | id, preset?, prompt?, video_url?, video_path? (local), intensity?, arm?, duration?, name? | A preset (instant, free), a motion described in words, or a motion copied from a reference video. arm (wave): auto, left, right or both. |
export_mascot | id, format, animation?, size?, fps?, background?, duration?, frame?, sound?, save_to? (local) | Render a file (lottie, dotlottie, animated-svg, gif, email-gif, mp4, webm, mov, prores, wav, webp, apng, sprite, stills). duration sets the length, frame the shape (landscape, portrait, feed, tight), sound a logo intro's reveal sound. Hosted: returns a download URL. Local: save_to writes it to disk. |
list_clips | id | A clip mascot's motion library: each clip's name, status, length and size. |
create_clip | id, motion? | prompt?, name?, regenerate?, max_credits? | A new video clip of an uploaded mascot's own art, from a preset motion or one described in words, or a new take of an existing clip. |
set_clip_kind | id, clip, kind (reaction | state) | Whether a clip plays once and returns (reaction) or holds as a loop (state). |
export_clip | id, clip, format, size?, background?, matte? | Render a clip as a file. Hosted: returns a download URL. |
get_embed_code | id, animation = "idle", framework = "html" | "react" | "lottie", trigger = "auto" | "hover" | "click", public?, look?, props? | A ready embed snippet, optionally showing one look or switching props for that embed only. Private mascots get a signed link that expires in 30 days; public: true makes the mascot public so the embed never expires. |
create_canvas | id, name, template? (chatbot | ai_agent | onboarding), graph? | An interactive state machine, from a template or a custom graph. |
analyze_website | url | Reads a site and proposes three mascot concepts, each with a prompt and style ready for create_mascot. |
create_scene | id, prompt, size = "wide" (square | wide | banner | portrait), animation?, save_to? (local) | An illustrated vector scene around the mascot. Returns SVG and PNG. |
suggest_animations | id, use_case? | Signature-motion ideas for this character and the product moments it lives in. |
wait_for_job | job_id | Wait for a long-running job and return its result. |
list_jobs | status? (queued | running | succeeded | failed | canceled) | The 20 most recent jobs with type, status and credits. |
Enumerations#
style: polished (default), outlined, playful, flat, kawaii, soft3d, retro, pixelish, or realistic (a photo-real picture animated as video; add motions with create_clip).preset: idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep, fly, point, shrug, float, peek, laugh, type, ride, notes, read, sign, search, phone, sip, announce, walk (fly only on winged characters).intensityis 0.25–2 (0.5 subtle, 1 normal, 1.5 big);durationis 0.3–20 seconds.format: lottie, animated-svg, gif, mp4, webm, webp, apng, sprite (animated, needanimation: an animation name, id or preset); png, svg, sticker, logo, logo-png (stills).size64–2048,fps6–60,background#rrggbb.
A typical session#
create_mascot { "prompt": "a sleepy moth who guards the docs", "style": "outlined" }
animate_mascot { "id": "msc_…", "preset": "wave" }
animate_mascot { "id": "msc_…", "prompt": "yawns, stretches both wings, then settles" }
export_mascot { "id": "msc_…", "format": "lottie", "animation": "wave", "save_to": "./public/" }
get_embed_code { "id": "msc_…", "animation": "idle", "framework": "react", "trigger": "hover" }Prefer recolor_mascot over edit_mascot for colour changes: it is instant and free. Use variant_name for outfits and seasonal looks so every animation keeps working.
Progress and long jobs#
Tools that start a job (create, edit, custom motion, export, scene, website analysis) wait for it. When the client sends a progress token, the server relays the job's live notes as notifications/progress messages (“drawing”, “reviewing a draft”, the agent's own progress lines), so the user sees the character being built instead of a spinner.
A tool waits up to 8 minutes. If the job is still running after that, create_mascot returns a note telling the agent to find the job with list_jobs and call wait_for_job. Nothing is lost: the job keeps running server-side. Cancelling the tool call on the client aborts the wait, not the job.
Claude Code skill and llms.txt#
Agents do better with a map. Three machine-readable entry points ship with Lumorig:
- Claude Code skill.
integrations/claude-code/skills/lumorig/SKILL.mdin the repository. Copy the folder into.claude/skills/and Claude Code picks the right interface (MCP tools, the CLI or REST), writes specific prompts, and knows that presets and recolors are free and that downloads cost credits on Free. - /llms.txt: the skill plus the API essentials as plain text, for any agent that reads the web.
- /api/v1/openapi.json: the full OpenAPI 3.1 document, the same one the REST reference is rendered from.