# Sprite-AI MCP: AI Assistant Guide

Generate game-ready pixel-art sprites and animations directly from your AI
coding assistant via the Model Context Protocol (MCP).

## IMPORTANT: these are MCP tools, not REST endpoints
- If you see Sprite-AI tools (sprite_generate, sprite_generate_animation, ...),
  call them directly. Do NOT use curl or the REST API for these.
- Tool names may be bare (sprite_generate) or prefixed
  (mcp__sprite-ai__sprite_generate) depending on the client.
- If you do NOT see these tools, tell the user the MCP server isn't configured
  (see Setup) instead of guessing at HTTP calls.

## What this is
A hosted MCP server. One line to install, no local package, no Node needed.
Generation spends tokens from the user's Sprite-AI account (the API key carries
the balance). A still sprite costs 1 token (4 for tile, background, ui, or
effect). An animation costs 14 to 20 tokens, scaling with frame count (8
frames = 14 tokens, 16 frames = 20), plus 2 for a Custom prompt. A restyle is
4 tokens flat. A rotation (8 directions) is 12 tokens. A normal map is 1 token
per frame. Background removal is free (standard) or 1 token (refined).

## Setup
  claude mcp add --transport http sprite-ai \
    https://www.sprite-ai.art/api/mcp \
    --header "Authorization: Bearer sai_sk_your_key"
Get a key at https://www.sprite-ai.art/account?tab=api-keys

## Tools

### sprite_generate  (blocking, about 10 to 40s, 1 to 4 tokens)
Generate ONE static sprite from a text prompt. Returns the PNG inline as a
viewable image AND as base64 to save to a file in the user's project.
Params: prompt (required), asset_type (character, creature, prop, weapon,
vehicle, tile, background, ui, effect; inferred if omitted), width, height
(default 64; see Sizes below), direction, camera_perspective,
reference_asset_id (id of a sprite you own to style-match — generate or import
one first, then pass its id; no bytes to send).
SAVE THE RESULT: the tool returns a download URL (plus a small inline preview).
Fetch the URL (no auth header needed) and write the bytes to a .png file in the
project (e.g. assets/sprites/<name>.png). Do not leave the sprite only in chat.
The user wants a file.
TIP: if you intend to animate the sprite afterward, generate it at 256 px or
smaller. The animation model rejects source images larger than 256x256.

### sprite_import  (free, 0 tokens, no AI)
Add a sprite you already have (e.g. a local PNG you read off disk) to the user's
account. Returns a generation id. This is the one door for getting external
bytes into the system; everything else then works by id. The agent reads the
file off disk and base64-encodes it (the server can't reach the user's disk).
Params: image_base64 (required; raw base64 or a data: URL, 16 to 256px per
side), title, asset_type.
USE THIS for any file the user already has, then pass the returned id to either:
sprite_generate_animation as source_generation_id (to animate it), OR
sprite_generate as reference_asset_id (to style-match new sprites to it). For
sprites you generated here, skip import — you already have the id.

### sprite_generate_animation  (blocking, about 15s, 14 to 20 tokens)
Animate an existing sprite into a frame-by-frame spritesheet. BLOCKING: it waits
for the animation to finish and returns the spritesheet PNG inline (a download
URL plus a preview), exactly like sprite_generate. (If it runs unusually long it
returns a job_id instead — then poll sprite_get_job until done.)
Only one animation runs at a time per account, so N animations take about
N x 15s in total. Submitting them all at once is fine and is the fastest
option: each is accepted immediately and queued server-side, and a queued
job reports 0% progress until its turn comes.
Reference the source by source_generation_id — the id of a sprite you own, from
sprite_generate, sprite_list_creations, or sprite_import. No bytes to send. The
source must be a still sprite 256x256 px or smaller (not a sprite sheet or an
existing animation). To animate a file the user already has, sprite_import it
first and pass the returned id.
Params: source_generation_id (required), preset (Idle, Walk, Run, Jump, Attack,
Hurt, Death, Custom), frame_count (even, 4 to 16, default 8), custom_prompt
(required for the Custom preset; Custom needs a Creator plan).
SAVE THE RESULT: fetch the download URL and write the spritesheet to a .png.

### sprite_restyle  (blocking, about 15-90s, 4 tokens flat)
Redraw a sprite the user owns in a different style — same character, same pose,
new look (gold, ice, zombie, or anything you describe). BLOCKING: waits for the
finished sprite and returns it inline (a download URL plus a preview), exactly
like sprite_generate. (If it runs unusually long it returns a job_id instead —
then poll sprite_get_job until done.)
Reference the source by source_generation_id — the id of a sprite you own, from
sprite_generate, sprite_list_creations, or sprite_import. No bytes to send. To
restyle a file the user already has, sprite_import it first.
Params: source_generation_id (required, source must be 16 to 512px per side),
then EXACTLY ONE of preset (fire, ice, gold, zombie, holy, cursed, poison,
royal, shadow, steampunk) or custom_prompt (free-form style text, same price,
any plan). Rerolling = call it again; each run samples fresh.
SAVE THE RESULT: fetch the download URL and write the sprite to a .png.

### sprite_normal_map  (synchronous, a few seconds, 1 token per frame)
Generate a tangent-space normal map for a sprite or animation the user owns —
for dynamic lighting in a game engine. AI trained on real 3D geometry, not an
edge-detect filter: the output encodes the subject's actual form, and its alpha
is a pixel-exact copy of the source silhouette. Animations are processed per
frame automatically (the model is deterministic, so frames never flicker) and
come back as the same-layout strip. Truly synchronous — the finished PNG comes
back inline in a few seconds, no job_id.
Reference the source by source_generation_id — a still sprite OR an animation.
Source frames must be 32 to 256px per side.
Params: source_generation_id (required), strength (0 to 5, default 0 — 0 is
truest to the geometry; ~2.5 re-adds the sprite's drawn shading for a
hand-crafted look), flip_green (true for DirectX/+Y-down engines like Unreal;
default is OpenGL/+Y-up for Godot, Unity, WebGL), columns/rows (only for a
still that is really a sprite sheet; max 24 frames).
Cost: 1 token per frame — a still sprite is 1 token, a 8-frame animation is 8.
SAVE THE RESULT: fetch the download URL and write it next to the sprite as
<name>_n.png (the naming most engines auto-detect).

### sprite_rotate  (blocking, about 1 to 2 minutes, 12 tokens)
Turn ONE still sprite the user owns into all 8 facing directions: S, SE, E, NE,
N, NW, W, SW, same character, same palette. Returns a horizontal strip of 8
equal frames in that spin order plus a fidelity score; low-scoring sheets are
re-rolled automatically. Synchronous, the finished strip comes back inline.
Reference the source by source_generation_id. The source must be a STILL,
32 to 256px per side (not an animation).
Params: source_generation_id (required).
SAVE THE RESULT: fetch the download URL, write the strip to a .png, and slice
it every frameWidth pixels for the individual directions.

### sprite_remove_background  (synchronous, under a second, free or 1 token)
Remove a flat, single-color background from a sprite or animation the user
owns and get a transparent PNG back, saved as a NEW sprite id that can be
animated, restyled or normal-mapped like any other. Sprites generated here
already have transparent backgrounds, so this is for files the user has:
sprite_import the screenshot or render first, then pass the returned id. A
source whose corners are already transparent is refused.
Params: source_generation_id (required), method ("standard" = free chroma key,
the default; "refined" = 1 token palette matting, the cleanest edges on
AI-generated pixel art), matte_color (#rrggbb; omit to sample the corners),
tolerance (standard only, 0 to 300, default 200), palette_size (refined only,
16 to 256, default 64), alpha_threshold (refined only, 0.3 to 0.9, default 0.7).
An animation source is keyed as one strip and comes back as an animation.
SAVE THE RESULT: fetch the download URL and write the cutout to a .png.

### sprite_get_job  (poll)
Check an async job (animation or restyle) by job_id. While running, returns
status "processing" (keep polling every 5s or so). Animations run one at a time
per account, so a queued job stays at 0% until the one ahead of it lands. When
done, returns a download URL for the finished PNG (plus a preview). Animation
results are a horizontal strip: slice into frame_count frames. Restyle results
are a single sprite.

### sprite_list_creations  (read)
List the user's past sprites and animations (newest first), metadata only.
Params: limit (1 to 100, default 20), offset, asset_type, status. Use to find a
previous generation id (e.g. to animate it).

### sprite_get_balance  (read)
Current token balance and plan. Check before generating if you're unsure there
are enough tokens.

### sprite_list_asset_types  (read)
Supported asset types with token cost and recommended pixel size range.

## Recommended workflow
1. (optional) sprite_get_balance to confirm tokens.
2. sprite_generate to make the sprite, then SAVE the PNG to the project.
3. To animate it: sprite_generate_animation with that sprite's
   source_generation_id, then save the returned spritesheet. (To animate a file
   the user ALREADY has, sprite_import it first, then pass the returned id.)
4. For style variants (gold/ice/etc. of the same character): sprite_restyle
   with the sprite's id — cheaper than regenerating and keeps the character.
5. For a top-down or isometric character: sprite_rotate with the sprite's id,
   then slice the 8-frame strip into the facing directions.
6. For dynamic lighting: sprite_normal_map with the sprite's (or animation's)
   id, and save the result as <name>_n.png beside the sprite.
7. For a screenshot or render on a flat color the user already has:
   sprite_import it, then sprite_remove_background with the returned id.
8. Wire the saved files into the game (any engine: Unity, Godot, Phaser,
   Pygame, etc.).

## Notes
- Sizes: characters, creatures, props, weapons, and vehicles 32 to 400px;
  tiles, backgrounds, ui, and effects 16 to 512px. Default 64. Anything you
  plan to animate must be 256px or smaller.
- Each generation returns a download URL (GET /api/sprites/<id>/download). It
  needs no auth header (the id is the key), so saving a sprite is one fetch.
  The server is hosted and cannot write to the user's disk, so YOU (the agent)
  fetch the URL and save the file.
- Rate limit: 60 requests per minute per key.