autohero/docs/pixellab-mcp-schema.md

PixelLab MCP — verified tool surface (AutoHero)

Reference date: aligned with 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 PNGs under frontend/assets/ (tiles/, prop/, building/, enemies/, characters/). Register each texture in frontend/public/assets/game/manifest.json (file paths are relative to frontend/assets/).

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.