# Mable Sprites agent guide

Mable Sprites turns one character image and a motion description into a transparent, row-major WebP sprite sheet for games and interactive web projects.

## Official endpoints

- Product: https://mable.gg/tools/character-animation
- All Mable Tools: https://mable.gg/tools
- Result guide: https://mable.gg/tools/character-animation/best-results
- Coding-agent setup: https://mable.gg/tools/for-agents
- Agent Key portal: https://mcp.mable.gg/developer
- MCP server: https://mable-dev-service.mable.gg/mcp
- Agent Skill package: https://mcp.mable.gg/developer/mable-agent-skills.zip

The MCP server requires an Agent Key with the `assets:generate` scope. Keep the key in the agent's local secret store and send it only in the MCP Authorization header.

## Connect Codex

Store the key in `MABLE_AGENT_KEY`, then configure the remote MCP server:

```sh
codex mcp add mable-sprites --url https://mable-dev-service.mable.gg/mcp --bearer-token-env-var MABLE_AGENT_KEY
```

Confirm the server with `codex mcp list` or `/mcp`.

## Connect Claude Code

Configure the remote HTTP server at user scope. The single-quoted JSON preserves the environment-variable reference instead of expanding the key into the command:

```sh
claude mcp add-json --scope user mable-sprites '{"type":"http","url":"https://mable-dev-service.mable.gg/mcp","headers":{"Authorization":"Bearer ${MABLE_AGENT_KEY}"}}'
```

Confirm the server with `claude mcp get mable-sprites` or `/mcp`.

## Required input image

Prepare a square PNG, JPEG, or WebP data URL, decoded size at most 20 MiB, with one complete isolated character. Use a flat, solid-colored chroma-key background. Pick a color not used anywhere in the character, clothing, or equipment. Do not use a transparent background, white, black, scenery, texture, gradients, shadows, text, or extra objects. The input background is colored; the final atlas output is transparent.

## Tools

### `start_sprite_animation`

Starts an asynchronous image-to-animation-to-atlas job.

Required argument:

- `imageDataUrl`: PNG, JPEG, or WebP base64 data URL.

Optional arguments:

- `motion`: one concise motion description, up to 1,000 characters. Default: a subtle idle loop.
- `stateId`: lowercase identifier matching `[a-z0-9_-]`, up to 64 characters. Default: `idle`.
- `loop`: whether playback should loop. Default: `true`.
- `perspective`: `sideView`, `frontView`, `topDown`, or `isometric`. Default: `sideView`.
- `motionEmphasis`: `active` or `calm`.
- `background`: `auto`, `white`, or `black`. Use `auto` for a prepared chroma-key image.
- `qualityProfile`: `standard`.
- `idempotencyKey`: stable identifier for retrying the same request, up to 160 characters.

The response includes `jobId`, `status`, and `pollAfterMs`.

### `get_sprite_animation_job`

Polls an owner-bound job. Pass the `jobId` returned by the start tool and respect `pollAfterMs` while the job is queued or running.

On success, `result` includes:

- `atlasUrl` and `expiresAt`
- `frames`, `rows`, and `columns`
- `frameWidth`, `frameHeight`, `atlasWidth`, and `atlasHeight`
- `fps`, `loop`, and `layout`
- `mimeType`, `atlasBytes`, `stateId`, and `qualityProfile`

Download the atlas before `expiresAt`. Treat `atlasUrl` as temporary and private. Playback uses the returned row-major grid metadata.

### `retry_sprite_animation_atlas`

Retries only atlas processing for an eligible failed job. Pass its `jobId`, then poll the new returned `jobId`. This reuses retained source video and does not start another provider generation.

Use this tool only after an atlas-processing failure. If it returns `ATLAS_RETRY_NOT_AVAILABLE`, `SOURCE_VIDEO_EXPIRED`, or `SOURCE_INPUT_EXPIRED`, prepare a corrected source image or motion request and start a new job instead.

## Durable result

Save the WebP atlas inside the current project and retain the exact metadata beside the asset. The durable result is the local atlas plus metadata, never the Agent Key or signed storage URL.