# 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 at any asset type and any size. An animation costs
14 to 20 tokens, scaling with frame count alone (8 frames = 14 tokens, 16 frames =
20), Custom prompt included. A restyle is 2 tokens on normal and 9 on pro. A combine
(two sprites in, one out) is 3 on normal and 9 on pro. 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 token)
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. If it
runs unusually long it returns a job_id instead. Poll sprite_get_job until done.
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, palette_id (id
of a palette saved in the user's library, from sprite_save_palette or
sprite_list_palettes; the sprite is drawn in it, held to it, and remembers it,
so animate, restyle and combine keep the same colors), 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, palette_id (a palette from the user's library, see
sprite_list_palettes; the sprite is stamped with it so animate, restyle and
combine hold to it, and its pixels are not changed).
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, 32 to 256 px per side (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), palette_extras (0 to 256, a cap on NEW colors
the animation may add beyond the source palette; 0 keeps the source palette
exact, omit for the preset's tuned default; raise it to 32-64 only when the
motion brings colors the sprite lacks, like fire, magic glow or sparks, so the
effect is not crushed into the old palette), framing_margin + framing_anchor
(framing_margin 0 to 25 is the percent the canvas grows before animating, so
the motion has room instead of being cropped at the sprite's edge. Omitted, it
is 25 for Jump and 0 for every other preset. Send 25 for fire or arrows.
framing_anchor is where the sprite sits in the grown canvas, one of top-left,
top, top-right, left, center, right, bottom-left, bottom, bottom-right, default
bottom for Jump and center for the rest: "bottom" keeps feet grounded, and a
bottom corner OPPOSITE the way the sprite faces opens room in front for a
projected effect).
SAVE THE RESULT: fetch the download URL and write the spritesheet to a .png.

### sprite_restyle  (blocking, about 15-90s, 2 tokens on normal, 9 on pro)
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 32 to 256px 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_combine  (blocking on normal, about 20s, 3 or 9 tokens)
Put an item from one sprite the user owns INTO another sprite they own — "my
knight holding this shield". The FIRST sprite keeps its identity and its exact
dimensions; the SECOND is where the item is copied from, so its shape and its
colours are what you get. The result is locked to both sprites' palettes, so an
item never comes back repainted in the character's colours.
Use this when the item EXISTS as a sprite. Use sprite_restyle in item mode to
swap for something you only have words for.
Both sprites are referenced by id — no bytes to send. Get ids from
sprite_generate, sprite_list_creations, or sprite_import; to use a local PNG,
sprite_import it first.
Params: source_generation_id (required, the sprite that keeps its identity),
item_generation_id (required, the sprite the item comes from, must be a
different id), prompt (required — say WHERE the item goes, not what it is:
"holding this shield in his free hand"), tier ("normal" 3 tokens, the default
and the one that actually puts the item in the character's hands; "pro" 9
tokens, holds the character closer but places the item worse), framing_margin +
framing_anchor (set 15-25 and "bottom" when the item reaches outside the
character's outline, e.g. a raised weapon). Both sprites must be 32-256px per side.
Normal returns the finished sprite inline in about 20s. Pro runs 3-4 minutes and
returns a job_id instead — poll sprite_get_job until completed.
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, so a still sprite is 1 and an 8-frame animation 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. Takes up to 400px per side, per frame for an animation.
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_generate_palette  (free, 0 tokens, saves nothing)
Propose a few color palettes for a description, e.g. "mossy dungeon, 16
colours". Returns each option's colors and its recipe as text, plus one image
of all the options, top to bottom in the same order. Nothing is saved: show the
options to the user, let them pick one or ask for another roll, then call
sprite_save_palette with the chosen option's recipe, exactly as returned.
Params: prompt (required, 3 to 200 chars; read into a theme, a main color and
moods, and a number in the text sets the count), count (colors per option, 4 to
64; defaults to the number in the prompt), options (how many options to
propose, 2 to 4, default 4).
Without a count the options come in four sizes, 8 to 32, so the user picks a
size by picking an option. On a re-roll, keep the count the user last chose.

### sprite_save_palette  (free, 0 tokens)
Save the palette the user picked to their library and get its palette_id back.
Pass that id as palette_id to sprite_generate (the sprite is drawn in it, held
to it, and remembers it, so animate, restyle and combine keep the same colors)
or to sprite_import (the sprite is stamped with it; its pixels are not
changed).
Params: name (required, 1 to 80 chars, a short name the user will recognise),
then EXACTLY ONE of recipe (the chosen option's recipe, exactly as
sprite_generate_palette returned it) or colors (explicit #rrggbb colors, 2 to
256).

### sprite_list_palettes  (read)
List the user's saved palettes, newest first, each with its palette_id, name
and colors. Use to find a palette_id for sprite_generate or sprite_import.
Params: limit (1 to 100, default 20).

### sprite_get_job  (poll)
Check a job that outlasted its call (sprite, animation, restyle or combine) 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. A combine on pro runs about 3 to 4 minutes. When done, returns a
download URL for the finished PNG (plus a preview). Animation results are a
horizontal strip: slice into frame_count frames. Sprite, restyle and combine
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.

### sprite_capabilities  (read, free)
The full capability reference in one call: what each asset-producing tool
makes, which outputs can be chained into which inputs, the still-vs-sheet rule,
every enum value, the pixel-size bands, token costs, expected latency and
worked examples. No params. Call it BEFORE planning any multi-step sequence.
Most failed sequences are a sprite generated too large to animate, or a sheet
fed to a tool that needs a still, and this reference rules both out up front.

## 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: 32 to 400px. 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, 300 on Studio and Production.