GUIDE

What is an MCP server for game assets?

MCP is a protocol that lets an AI client call tools and read resources hosted somewhere else. A game-asset MCP server applies that to art: instead of describing your sprites in chat, the client queries them. PX-Art runs one named perfectpixel-scene — read-only, JSON-RPC over HTTP, twelve tools, and scene and asset URIs the client can read directly.

The protocol in one paragraph

The Model Context Protocol standardises how an AI client talks to an external capability provider. The client performs a handshake, discovers what the server offers, then either calls a tool (a named function with typed arguments, invoked with tools/call) or reads a resource (an addressable document identified by a URI, fetched with resources/read). Servers may also publish resource templates — URI shapes with placeholders — so a client can construct addresses it was never explicitly handed. Everything travels as JSON-RPC.

The practical consequence: capability is discovered at runtime, not compiled in. A client that has never heard of pixel art can still ask a game-asset server what it can do and get a machine-readable answer.

What makes an asset server different from a documentation server

Most early MCP servers return text. Art does not fit that shape, and a server that pretends otherwise is useless to a game build. Four differences matter:

• Binary payloads do not belong in a model's context. Full-resolution PNGs must be delivered out-of-band, by link, not pasted into a conversation. Only small preview images are worth returning inline.
• Identity and versioning are load-bearing. "The player idle sprite" is not a stable reference. An asset needs an ID, and a scene needs a revision number so the same query twice returns the same bytes.
• Frames are not always animation. A four-frame strip may be an animation, a set of button states, or a glyph row. Playing the wrong one at 8 fps is a visible bug.
• Coordinates need a declared convention. Origin corner, axis directions, unit, transform model and draw ordering must be stated by the server, because an agent guessing at them produces a scene that is subtly wrong everywhere.

The PX-Art server: identity and shape

The twelve tools

All read-only, all free to call. Tool names are exact:

analyze_layout is deliberately factual: overlap pairs, bounding boxes and counts, with no aesthetic judgement. Whether an overlap is a bug or an intentional composition is the agent's call, not the server's.

The resource URIs

The composition is where the two halves join: every asset entry inside it carries a resourceRef.uri such as asset://12@1784099933, and that URI can be passed straight to resources/read. Assets are not enumerated in resources/list — there are too many — so you either search for them or follow the URIs the composition already gives you.

Connecting to one, step by step

1. Get a tokenIssued per user from the MCP panel in the app. The plaintext is shown once. Any subscription payment or top-up purchase unlocks read-only MCP permanently.
2. Add the server to your clientAnything speaking Streamable HTTP works. For Claude Code: claude mcp add --transport http px-art https://px-art.com/api/mcp --header "Authorization: Bearer pxr_YOUR_TOKEN"
3. Verify the handshakeA single tools/list POST tells you whether auth, transport and protocol version all agree. If you send an MCP-Protocol-Version header it must match the negotiated version, or you get a 400; omitting the header is fine.
4. Discover the URI shapesresources/templates/list returns the scene and asset templates; resources/list pages through your actual scenes with an opaque cursor — echo nextCursor back verbatim, do not parse it as a page number.
5. Read the composition before reading imagesIt contains the coordinate convention, the revision and the asset catalogue, which is everything needed to decide what to fetch.

Reading errors correctly

The server separates protocol failures from tool failures, and the distinction matters when you are debugging an agent:

-32700  parse error          -32601  no such method
-32600  invalid request      -32602  bad call (unknown tool, bad URI or cursor)
-32002  resource missing or not permitted (resources/read; data.uri names it)
-32603  internal server error

A tool failure is not a protocol error. It comes back as a normal result with {"isError":true} and a sentence explaining what went wrong — wrong argument type, missing required field, over a limit, or a scene that does not exist. That text is written to be read by the agent, so a failing tool call usually already contains its own fix. Missing and forbidden return the same message on purpose, so the server never confirms that someone else's scene ID exists.

Limits and caveats

• Read-only, permanently. No writes, no generation, no undo, no editor state, and no way to spend credits.
• No whole-scene rendering. Per-asset thumbnails are available; a picture of the assembled scene is not.
• Scoped to one account. A token covers all of that user's games and nothing else. It is not a web login credential, and paid status is verified on every call.
• Thumbnails are for choosing, not shipping. They are capped at 220px on the longest side. Final exports happen in the app or through the download tools.
• The Tiled resource exists only for square and isometric scenes. UI scenes have no tiled representation, and reading scene://{id}/tiled alone gives you JSON without image bytes — you still need get_asset_downloads, or use get_scene_bundle which resolves paths for you.
• Treat the token as a password. It ends up in third-party client config files by design. Never commit it. Regenerating invalidates the old one immediately.

The product view of this surface is on MCP game assets and Agent / MCP. What the assets themselves look like is covered on tileset generator.

FAQ

Related