Lumorig

npx add-mcp 'https://lumorig.com/api/mcp'

Mascots as an API.

Create, rebuild, animate and embed characters from your code, your terminal or your agent.

MCP, hosted https://lumorig.com/api/mcp

$ lumorig create "a vector control point that came alive"  drawing body, pupils, eyes, brows…  reviewing a draft✔ Designing your mascot ($0.28)Pip msc_4hq8z  readypalette  cobalt_hi #6682FF  cobalt #3A5BFF  cobalt_mid #3452F2$ lumorig play msc_4hq8z wave

Pip · wave · Ctrl-C to stop

The studio, the API, the SDK, MCP and the CLI all call the same service layer.

• REST API Jobs, long-poll and SSE, webhooks, signed links. /api/v1 Docs
• TypeScript SDK Typed, zero dependencies, runs anywhere fetch does. @lumorig/sdk Docs
• MCP server Hosted over HTTP, or local over stdio. /api/mcp Docs
• CLI Create, animate, export, and play in the terminal. lumorig Docs studio REST SDK MCP CLI packages/core

Create, wait, export, embed.

1. 1

   Create

   From an idea, an upload or an image URL. Returns at once with a job.

   curl -X POST https://lumorig.com/api/v1/mascots -H "Authorization: Bearer $LUMORIG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "prompt": "a sleepy moth who guards the docs" }'
   # 202 → { "mascot": { "id": "msc_…" }, "job": { "id": "job_…" } }
   

2. 2

   Wait

   Long-poll the job, stream its events over SSE, or get a webhook.

   curl "https://lumorig.com/api/v1/jobs/job_…?wait=30" -H "Authorization: Bearer $LUMORIG_API_KEY"
   # or stream progress as it draws
   curl -N "https://lumorig.com/api/v1/jobs/job_…/events" -H "Authorization: Bearer $LUMORIG_API_KEY"
   

3. 3

   Export

   Any format, any size, and no credits, on Maker and Studio.

   curl -X POST https://lumorig.com/api/v1/mascots/msc_…/exports -H "Authorization: Bearer $LUMORIG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "format": "lottie", "animation": "wave" }'
   

4. 4

   Embed

   Or skip files: one line of HTML, live and interactive.

   curl "https://lumorig.com/api/v1/mascots/msc_…/bundle"   # what <lumorig-player> loads
   

Uploads, custom motion, canvases and webhooks are in the full quickstart and the API reference.

14 tools your agent already understands.

claude mcp add --transport http lumorig \
  https://lumorig.com/api/mcp
# no key: sign in once when it asks

{
  "mcpServers": {
    "lumorig": {
      "command": "npx",
      "args": ["-y", "@lumorig/mcp"],
      "env": { "LUMORIG_API_KEY": "lr_sk_…" }
    }
  }
}

Plus the MCP guide, llms.txt, OpenAPI and a Claude Code skill, so agents can read the docs the way they like them.

• create_mascot New character from an idea, or rebuild an image
• list_mascots Everything in the workspace
• get_mascot Parts, palette, motions and a preview image
• edit_mascot Change it in plain words, or branch a look variant
• recolor_mascot Swap palette tokens instantly
• animate_mascot A preset (free), a described motion or a reference video
• suggest_animations Signature-motion ideas for your product
• export_mascot Lottie, SVG, MP4, WebM, GIF, stickers…
• get_embed_code A ready <lumorig-player> or Lottie snippet
• create_canvas Chatbot, AI-agent or onboarding behaviour
• create_scene The mascot in an illustrated vector scene
• analyze_website Three mascot concepts from a brand's site
• wait_for_job Block until a long job finishes
• list_jobs Recent jobs, status and cost

A mascot that watches your agent work.

Run lumorig companion in a side terminal and add the hooks. It shows working during tool calls, waiting when Claude Code needs you, and done when it stops.

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "lumorig state working" }] }],
    "PreToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "lumorig state working" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "lumorig state waiting" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "lumorig state done" }] }]
  }
}

lumorig companion

idle

$ claude "fix the flaky auth test"

<lumorig-player>: ~8 KB gzipped, one line of HTML.

<lumorig-player
  src="https://lumorig.com/api/v1/mascots/pip/bundle"
  animation="wave"
  trigger="auto"
  follow-cursor
></lumorig-player>

attribute	type	does
src	URL	Mascot bundle (spec + motions + canvases)
animation	string	Preset or motion name to play
trigger	auto · hover · click · none	When it plays
speed	number	Playback rate, 1 = normal
loop	boolean	Loop the animation
palette	JSON	Recolour by token, e.g. {"fur":"#3A5BFF"}
follow-cursor	boolean	Eyes and head track the pointer
canvas	string	Run a state machine from the bundle
no-shadow	boolean	Hide the soft floor shadow

• play(name?) Play a motion now
• pause() · seek(t) Control the timeline
• setInput(name, value) Drive a canvas input
• fire(name) Fire a canvas trigger
• ready · ended · statechange · error Events you can listen to

React wrapper · npm package coming soon

import { MascotPlayer } from "@lumorig/player/react";

export function Helper() {
  return (
    <MascotPlayer
      src="https://lumorig.com/api/v1/mascots/pico/bundle"
      animation="idle"
      trigger="hover"
      followCursor
    />
  );
}

Everything slow is a job. Every job tells you what it cost.

1. queued
2. running
3. succeeded
4. …or failed · canceled. Events stream over SSE while it runs.

• Long-poll with ?wait=30, or stream /jobs/:id/events.
• Webhooks for job.succeeded, job.failed, job.canceled, HMAC-signed and retried.
• Signed share links for private mascots, with an expiry you choose.
• Spend caps: pass max_credits on create, edit, variant, motion and scene jobs to set the most a job may charge; a job that would need more stops and is refunded.

POST https://your.app/hooks/lumorig
lumorig-signature: t=1790000000,v1=5f2c…

{
  "type": "job.succeeded",
  "created_at": "2026-09-25T10:04:12Z",
  "data": {
    "id": "job_…", "type": "export", "status": "succeeded",
    "credits": 0, "result": { "file": { "url": "/api/v1/files/file_…" } }
  }
}

curl -X POST https://lumorig.com/api/v1/webhooks \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your.app/hooks/lumorig", "events": ["job.succeeded", "job.failed"] }'

Reliability and limits

Sanitised SVG

Every drawing passes a restricted-subset sanitiser before it's stored or served. No scripts, no external references.

Versioned formats

Specs, clips and canvases carry a version field (specVersion, clipVersion, canvasVersion), and every save is validated against the schema.

No surprise bills

Every action shows its price in credits up front, a failed job gives its credits back, and max_credits caps what any job may charge. Presets are always free, and downloads are included on Maker and Studio.