The Lumorig MCP server gives any Model Context Protocol client fourteen 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. It is stateless, and it authenticates with your API key as a Bearer token (or a ?key= query parameter for clients that can't send headers). Create a key first: see Authentication.
claude mcp add --transport http lumorig https://lumorig.com/api/mcp \
--header "Authorization: Bearer lr_sk_…"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_cost_usd? | 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, creates a rig-compatible look variant instead of an edit. |
recolor_mascot | id, palette | Instant palette change by token name, e.g. { fur: "#3b82f6" }. No credits. |
animate_mascot | id, preset?, prompt?, video_url?, video_path? (local), intensity?, duration?, name? | A preset (instant, free), a motion described in words, or a motion copied from a reference video. |
export_mascot | id, format, animation?, size?, fps?, background?, save_to? (local) | Render a file. Hosted: returns a download URL. Local: save_to writes it to disk. |
get_embed_code | id, animation = "idle", framework = "html" | "react" | "lottie", trigger = "auto" | "hover" | "click", public? | A ready embed snippet. 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 cost. |
Enumerations#
style: polished (default), outlined, flat, kawaii, soft3d, retro, pixelish.preset: idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep.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 exports are 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.