Automating Character Animation From Claude Code and Cursor With MCP

Why generate assets from inside the coding session

The traditional loop for adding a mascot to a product has a gap in the middle: a developer opens a design tool or a browser app, generates something, downloads files, renames them, drags them into the repository, and only then starts writing the code. Each hop loses context (what size, which format, which state was this for?) and each is an excuse to postpone.

With an MCP server, the assistant that is already editing your EmptyState.tsx can also call a tool that generates the character, poll until the animation is ready, fetch the download URLs, save the files next to the component, and write the <video> markup with the correct paths. The asset becomes part of the same change as the code that uses it, in one session, reviewed in one pull request.

The Model Context Protocol is the open standard that makes this possible: a server exposes named tools with typed inputs, and any compatible client (Claude Code, Claude Desktop, Cursor, and a growing list of others) can discover and call them. Character Animation AI ships an MCP server with every account, including free ones; the integration page has the reference configuration, and this article is about what to do once it is connected.

Connecting in two minutes

1. Sign in to the studio and open MCP connection. Create an access key. It is displayed once; copy it now.
2. Add the server to your client. The server speaks Streamable HTTP with a Bearer token, which every current client supports.

Claude Code (one command, project-scoped by default):

claude mcp add --transport http character-animation-ai \
  https://api.characteranimationai.com/mcp \
  --header "Authorization: Bearer YOUR_MCP_ACCESS_KEY"

Claude Desktop and Cursor (JSON in the client’s MCP settings):

{
  "mcpServers": {
    "character-animation-ai": {
      "type": "http",
      "url": "https://api.characteranimationai.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_ACCESS_KEY" }
    }
  }
}

Restart or reload the client and ask it to list the character tools; if it names seven, you are connected. Keys expire after 30 days, so put a note in your calendar or, better, ask the assistant to tell you when a call fails with an authentication error, which is the only symptom of an expired key.

Do not commit the key. In Claude Code, prefer the user-scoped install (--scope user) so the key lives in your home directory rather than the repository’s .mcp.json. If a project-scoped entry is required for a team, reference an environment variable in the header and set it locally.

The seven tools and the approval contract

The important design decision is in the two paid tools: both require an approved: true argument, and their descriptions instruct the assistant to show you the design and confirm the credit cost before setting it. This is not a soft convention; the tool call is rejected without the flag. In practice it means an agent cannot burn through a credit balance in a loop, because every spend is a question you answered. Failed jobs refund automatically, so a retry is never a double charge.

animate_character also folds approval of the design into the first animation: calling it on an unapproved character approves the design and starts the motion in one step. That matches the studio workflow (nothing is animated until a design is approved) without requiring a separate tool.

Recipe 1: a five-state motion system in one session

The most valuable single task: turn one approved design into the set of clips a product needs. A prompt to the assistant that works well:

Check my credits, then list my characters. If "Pip" exists and is approved, use it;
otherwise stop and ask me. For Pip, create these animations one at a time, asking me
before each spend, and wait for each to finish before starting the next:
  1. Idle preset, name "idle"
  2. Wave preset, name "greet"
  3. Bounce preset, name "small-win"
  4. Dance preset, name "big-win"
  5. Custom: "shrugs apologetically with both shoulders, then gestures to the right", name "oops"
When all five are complete, fetch the download URLs and save each WebM and GIF into
public/mascot/<name>.webm and public/mascot/<name>.gif. Then print a table of file sizes.

Two things make this reliable. Naming each animation gives you stable identifiers later (get_animation_downloads accepts an animationId, and the names appear in list_characters). Serialising the jobs, rather than starting five at once, keeps the approval prompts readable and makes progress obvious. Each animation takes a few minutes; the assistant polls get_character and reports progress, and you can carry on with other work in the meantime.

Which five states a product needs, and why these five, is covered from the design side in the app mascot guide.

Recipe 2: a design review loop with a human in it

Designs cost a credit each, and the difference between a keepable character and a generic one is in the prompt. Let the assistant draft the prompt and you judge the result:

We need a mascot for a sleep-tracking app. Draft a character design prompt using the
six-part structure (body type, one signature feature, precise palette, resting expression,
material, framing) for the Soft 3D style. Show me the prompt and wait. After I approve
the wording, generate the design, poll until it is ready, and show me the preview URL.
Do not animate anything until I say the design is right.

When the preview comes back, give feedback in terms of the six parts (“the signature feature is too small; make the lantern bigger and warmer”) and let the assistant regenerate with a single change. Assistants are good at holding the rest of the prompt fixed, which is exactly the discipline that manual iteration tends to lose. The six-part structure and the reasons for it are in the prompt-writing guide; pointing the assistant at that page produces noticeably better first drafts.

If the design is meant to match an existing mascot, pass the image as the reference instead of relying on words; the tool accepts one, and the redraw keeps the identity while the style changes.

Recipe 3: asset plus component in one pull request

Once a clip exists, the assistant already knows your framework and your conventions. A follow-on prompt:

Using the "oops" animation of Pip: download the WebM and GIF into public/mascot/, use the
approved design preview as a WebP poster, and add a <Mascot> usage to
src/components/ErrorState.tsx following the pattern in src/components/Mascot.tsx
(muted loop playsInline, poster, reduced-motion respected, GIF fallback when VP9 is not
supported). Keep the video under 240px wide. Open a PR titled "Add mascot to error state".

The assistant fetches the URLs from get_animation_downloads, saves the files, and writes the code. Because the exports are already transparent and already in the right formats, there is no conversion step to script. The component pattern referenced here is the one in the website embedding guide, which also explains why the poster should be the LCP element rather than the video.

For teams that want this repeatable, a short project instruction file (a CLAUDE.md or Cursor rule) that says “mascot assets live in public/mascot, always save WebM and GIF, always use the Mascot component” removes the need to restate conventions in every prompt.

Recipe 4: seasonal and campaign variants on a schedule

Marketing sites change with the calendar and the mascot should too: a scarf in December, sunglasses in July, a party hat on the product’s birthday. Because the design is locked, these are motion prompts against the same character, not new designs. A useful pattern is a small script or a scheduled agent task that, once a quarter, proposes three seasonal motions, asks for approval, generates them, and files a pull request that swaps the hero clip behind a feature flag.

Keep two constraints in mind. Custom motion prompts can suggest small props (“wraps a scarf around its neck”) but the base design does not change, so a permanently different outfit is a new design and a new approval. And the clips are 4 to 12 seconds and square, which suits a hero loop and a social post but not a long explainer; for the latter, chain several clips in an editor as described in the video editor guide.

Operational details worth knowing

• Polling cadence. Designs finish in under a minute; animations take a few minutes. Ask the assistant to poll get_character every 15–30 seconds rather than continuously, and to report the progress field it returns. If a client has a per-call timeout, the poll-and-return pattern is what keeps long jobs within it.
• Credit budgeting. One design plus five animations is six credits. Have the assistant call get_account first and refuse to start a batch it cannot finish. Plans and packs are on the pricing page; the free tier’s three credits are enough to test the whole pipeline end to end with one design and one animation.
• Idempotency. Tools that start jobs return a job you can poll; calling them twice starts two jobs and spends two credits. The approval flag makes accidental duplicates unlikely, but if you write your own automation on top, store the returned IDs before retrying anything.
• Failure handling. A failed job refunds its credit and get_character reports the failure. retry_generation reuses saved provider work where possible, so a retry is usually faster than the original. Two failures on the same prompt is a signal to change the prompt.
• Downloads are URLs. get_animation_downloads returns links, not bytes. Have the assistant fetch them into the repository (or your CDN) so your build does not depend on the studio’s storage at deploy time.
• Key rotation. Keys expire after 30 days and can be revoked instantly from the studio. Rotate them the way you rotate any API token: one key per machine or per teammate, never shared in chat, revoked when someone leaves.
• Licensing. Assets generated through MCP carry the same licence as those generated in the browser, which depends on your plan. The FAQ summarises commercial use.

What this does not do, on purpose

The server is deliberately narrow. It will not spend credits without an explicit approval argument. It will not change an approved design; a different character is a new design. It does not expose a “generate ten variations and pick the best” tool, because ten variations is ten credits and the studio’s model is that you look before you pay. And it produces short (4 to 12 second) square clips with alpha, not long-form video.

Those constraints are what make it safe to hand to an autonomous assistant. An agent working inside them can do a great deal (a full motion system, wired into a codebase, in an afternoon) while the worst-case outcome of a misunderstanding is one credit and one question. That is the right shape for a creative tool in an agentic workflow, and it is why the approval contract is enforced by the server rather than left to the client’s good manners.