# PixelLab MCP — verified tool surface (AutoHero)

Reference date: aligned with [https://api.pixellab.ai/mcp/docs](https://api.pixellab.ai/mcp/docs) (auto-generated from FastMCP). **Re-check the live docs** if tools fail or names differ in your Cursor client (tools may appear as `mcp__pixellab__<name>` or similar).

## Cross-cutting behavior

- Creation tools **return immediately** with IDs; generation runs in the background (order of minutes).
- Poll with matching **`get_*`** tools until status is **completed** (or handle `processing` / `failed` per response).
- **Do not** treat remote URLs as durable storage for the repo: **download or decode base64 and write files under** `frontend/public/assets/game/` immediately.

## Character and animation

| Tool | Role | Key parameters |
|------|------|----------------|
| `create_character` | Queue 4/8-direction character | `description`, `n_directions` (4\|8), `size` (default 48), `body_type` (`humanoid`\|`quadruped`), `template` (quadruped: bear, cat, dog, horse, lion), `proportions` (JSON preset), `view` |
| `animate_character` | Queue animation on existing character | `character_id`, `template_animation_id`, optional `action_description`, `confirm_cost` |
| `get_character` | Status, rotations, animations, download | `character_id` |
| `list_characters` | Paginated list | `limit`, `offset`, `tags` |
| `delete_character` | Remove character | `character_id`, `confirm` |

Per docs: characters are **stored on PixelLab** for reuse; still **export PNGs/ZIP into the repo** for builds and versioning.

## Isometric tiles

| Tool | Role | Key parameters |
|------|------|----------------|
| `create_isometric_tile` | Single isometric tile | `description`, `size` (default **32**, docs recommend ≥32), `tile_shape` (`thin`\|`thick`\|`block`), `outline`, `shading`, `detail`, `seed` |
| `get_isometric_tile` | Status + **base64 PNG** / download URL | `tile_id` |
| `list_isometric_tiles` | Paginated list | `limit`, `offset` |
| `delete_isometric_tile` | Delete | `tile_id` |

## Map objects (transparent props)

| Tool | Role | Key parameters |
|------|------|----------------|
| `create_map_object` | Prop with alpha | `description`, `width`, `height`, `view`, `outline`, `shading`, `detail`, `background_image`, `inpainting` |
| `get_map_object` | Status and asset data | `object_id` |

Marketing copy elsewhere mentioned **time-limited hosting** for some assets; **treat all MCP outputs as ephemeral until checked into the project.**

## Tiles Pro (optional)

| Tool | Role | Key parameters |
|------|------|----------------|
| `create_tiles_pro` | Batch / pro tiles | `description`, `tile_type` (default `isometric`), `tile_size`, `n_tiles`, `tile_view`, `seed`, `style_images`, … |
| `get_tiles_pro` | Status and data | `tile_id` |
| `list_tiles_pro` | List | `limit`, `offset` |
| `delete_tiles_pro` | Delete | `tile_id` |

## Top-down and sidescroller Wang tilesets

- `create_topdown_tileset` / `get_topdown_tileset` / `list_topdown_tilesets` / `delete_topdown_tileset` — corner Wang sets, `tile_size` default 16×16, chain via `lower_base_tile_id`.
- `create_sidescroller_tileset` / `get_sidescroller_tileset` / `list_sidescroller_tilesets` / `delete_sidescroller_tileset` — platformer side-view sets.

Less central to AutoHero’s **diamond isometric** ground plane but valid for experiments or UI.

## MCP configuration (local)

Cursor `mcp.json` should use HTTP transport and Bearer token (see PixelLab setup). **Never commit API tokens** to the game repository.