MCP server

Pixel Engine is available as a remote Model Context Protocol server, so an AI agent can generate, animate and clean up pixel art for a game on the user's own account. This page is the technical reference. For click-by-click setup in a specific app, see Use Pixel Engine from your AI agent.

Connect

Server URL

https://api.pixelengine.ai/functions/v1/mcp

Property	Value
Transport	Streamable HTTP. Stateless: no session id, every request stands alone.
Authentication	OAuth 2.1 with dynamic client registration. No API key is needed; see Authentication below.
Tools	7 — listed below.
Result viewer	Image and job tools declare an MCP Apps UI resource, `ui://pixel-engine/result-viewer-v1.html`. Clients that support it show the sprite or play the animation under the tool call; others get the image inline and a link.

Clients that read an mcp.json file (Cursor and others)

mcp.json

{
  "mcpServers": {
    "pixel-engine": {
      "url": "https://api.pixelengine.ai/functions/v1/mcp"
    }
  }
}

Then connect the server from the client's MCP settings; a browser window opens to sign in.

Claude Code

claude mcp add --transport http pixel-engine https://api.pixelengine.ai/functions/v1/mcp

Claude, ChatGPT and other apps with a settings screen: step-by-step guide.

Authentication

The server follows the MCP authorization spec. An unauthenticated request gets 401 with a WWW-Authenticate header naming the protected-resource metadata:

Protected-resource metadata

https://api.pixelengine.ai/functions/v1/mcp/.well-known/oauth-protected-resource

It points at the authorization server, which supports dynamic client registration, so a client registers itself and sends the user to pixelengine.ai to sign in and approve. The consent screen asks once whether the app may generate on the account and spend its credits; there are no finer-grained scopes and no read-only option today. The agent never sees the user's password. Token lifetimes, refresh and revocation are the same as for any app using Sign in with Pixel Engine. Users see and disconnect connected agents under Account → Connect an agent.

For your own scripts, a Pixel Engine API key is also accepted as the bearer token.

Tools

Read tools only look things up. Write tools create a job on the user's account and, except pixelate_image, spend credits. None is a sensitive write: no tool moves money, buys credits or plans, sends anything to anyone, or deletes anything. Credits are prepaid on pixelengine.ai, and each tool's description states its cost for that account before it is called.

Tool	Does	Classification	Cost (credits)
`check_balance`	Shows the credit balance	Read	Free
`list_recent_jobs`	Lists jobs made through this connection	Read	Free
`get_job`	Status and output of one job	Read	Free
`generate_sprite`	Pixel-art image from a prompt	Write	6–36, by model
`animate_sprite`	Animation from a still image	Write	20–26, by model
`pixelate_image`	Converts any image to pixel art	Write	Free
`remove_background`	Makes the background transparent	Write	2

Costs are list prices. An account with a partner discount sees its own, lower price in the tool descriptions, and every finished paid job states the actual charge. The tools also carry the standard MCP annotations (readOnlyHint, destructiveHint, openWorldHint): write tools set openWorldHint because they download the HTTPS image URL they are given.

check_balance

No inputs. Returns available credits, credits reserved by running jobs, and the monthly (subscription) and purchased balances.

Classification	Cost	Side effects
Read	Free	None.

list_recent_jobs

Input	Required	Notes
`limit`	No	1–20, default 10. Newest first.

Returns each job's id, kind, status, creation time, credits charged, whether its output can still be fetched, and its prompt (shortened). Only jobs made through this connection are listed, not the user's jobs in the app or from other apps.

Classification	Cost	Side effects
Read	Free	None.

get_job

Input	Required	Notes
`api_job_id`	Yes	A job id returned by any write tool or by list_recent_jobs.

Returns the same result as the tool that made the job (see Results), with a fresh output link.

Classification	Cost	Side effects
Read	Free	None.

generate_sprite

Input	Required	Notes
`prompt`	Yes	What to draw: subject, view, pose and background.
`model`	No	pe_image_v1 (6), nb_flash (12, default), nb_pro (36), oai_gpt25_low (6), oai_gpt25_high (12), oai_gpt25_max (36).
`reference_image_url / reference_image_base64 / source_job_id`	No	An image to iterate on or match in style. At most one. Not with pe_image_v1. A URL must be HTTPS (up to 5 MB); base64 up to 5 MB decoded.
`width, height`	With pe_image_v1	16–128 px. Above 64 px odd sizes are rounded up to even; the longest side may be at most 4× the shortest.
`enhance_prompt`	No	pe_image_v1 only: auto (default), always or never — whether a short prompt is rewritten first.
`seed`	No	pe_image_v1 only: repeat an earlier result with the same prompt and settings.
`colors / palette`	No	Maximum color count (2–256, default 24), or an exact list of 2–64 hex colors.

pe_image_v1 prompts are limited to 100 words and 700 characters, and its sprites come back with the background already removed.

Classification	Cost	Side effects
Write	6–36 by model	Creates a job and spends its credits when it succeeds.

animate_sprite

Input	Required	Notes
`image_url / image_base64 / source_job_id`	Yes, one	The still to animate. In pixel mode (the default) a PNG, at most 256 px per side for pixel-engine-v1.1 or 320 px for pixel-engine-v1.5; in detailed mode a PNG or JPEG, 256–2048 px per side. Give exactly one of the URL, the base64 image or source_job_id. A URL must be HTTPS (up to 5 MB); base64 may be raw or a data: URL (up to 5 MB decoded). source_job_id is an earlier job's id, and keeps working after that job's output link has expired.
`prompt`	Yes	The motion, in order: start, action, how it ends.
`model`	No	pixel-engine-v1.5 (26, default) or pixel-engine-v1.1 (20).
`render_mode`	No	pixel (default) or detailed, for high-resolution non-pixel art.
`output_frames`	No	2–16. v1.5 takes 3–16; v1.1 takes even numbers.
`output_format`	No	webp (default, animated), gif, or spritesheet (one PNG strip, frames left to right).
`canvas`	No	{ scale 1–3, fill, fill_color, anchor }: places the sprite on a larger canvas first, so the motion has room. Needs a PNG input.
`enhance_prompt`	No	always (default), auto or never.
`seed`	No	Repeat an earlier animation. One is chosen and reported if you leave it out.
`colors / palette`	No	As for generate_sprite; pixel mode only.

Classification	Cost	Side effects
Write	20–26 by model	Creates a job and spends its credits when it succeeds.

pixelate_image

Input	Required	Notes
`image_url / image_base64 / source_job_id`	Yes, one	Any still PNG or JPEG. Give exactly one of the URL, the base64 image or source_job_id. A URL must be HTTPS (up to 10 MB); base64 may be raw or a data: URL (up to 5 MB decoded). source_job_id is an earlier job's id, and keeps working after that job's output link has expired.
`colors / palette`	No	As for generate_sprite.

Classification	Cost	Side effects
Write	Free	Creates a job. No credits are spent.

remove_background

Input	Required	Notes
`image_url / image_base64 / source_job_id`	Yes, one	A PNG or WebP image or animation (not GIF). Give exactly one of the URL, the base64 image or source_job_id. A URL must be HTTPS (up to 10 MB); base64 may be raw or a data: URL (up to 5 MB decoded). source_job_id is an earlier job's id, and keeps working after that job's output link has expired.

Keeps a sprite sheet's layout. Works best on a finished animation.

Classification	Cost	Side effects
Write	2	Creates a job and spends its credits when it succeeds.

Results and job status

A write tool waits up to about 75 seconds for its job. Images usually finish in that time; animations can take a few minutes. If the job is still running, the tool returns its id and progress instead, and the agent calls get_job again in about 10 seconds. Jobs keep running whether or not anyone polls.

Every result has a text summary and the same facts as structuredContent. A finished image or animation is also attached inline when it is under 4 MB (animated WebP and GIF previews often show only the first frame in chat).

Field	Meaning
`job_id`	Use it with get_job, or as source_job_id in another tool.
`status`	queued or pending while it runs, then success, failure or cancelled.
`output_url`	Signed link to the file. Works for one hour (output_url_expires_at); get_job returns a fresh one.
`file_kept_until`	The output can be fetched for 24 hours after the job, then is no longer served.
`content_type, width, height`	The file's type and pixel size.
`kind, frames, frame_width`	image, animation or sprite_sheet; frame count for animations; frame width for sprite sheets.
`palette, seed`	The colors used, and the seed that repeats the result.
`credits_charged, credits_available, credits_reserved`	What this job cost and the balance afterwards.
`progress, error`	Progress while running; the reason when a job fails.

Outputs can be fetched for 24 hours after the job, and not after. Download anything worth keeping, and pass source_job_id rather than a saved link when chaining tools.

Errors

A tool error comes back as a normal tool result with isError: true and text in the form code: message. The message says what to change. A job that runs and then fails also has isError: true, with its status and the reason instead.

Code	When
`invalid_request`	A missing or conflicting input, an image the server checked itself and can't take (wrong format or size, or a URL it couldn't download), or an earlier job that can't be used as a source.
`image_fetch_failed`	The API could not download an image URL: it timed out, the host refused it, or it was unreachable. This applies to generate_sprite's reference image and remove_background's image.
`image_too_large`	The image is over the tool's limit: 5 MB for animate_sprite and a generate_sprite reference, 10 MB for remove_background.
`job_not_found`	get_job, or a source_job_id, names a job that doesn't exist or wasn't made by this connection.
`insufficient_credits`	This call costs more than the credits available right now. Credits held by running jobs come back when those jobs finish. You cannot buy credits through the server; the user manages credits on pixelengine.ai.
`job_expired`	The job's output is older than 24 hours and is no longer served.
`unauthorized`	Not a tool result: the server answers HTTP 401 with a WWW-Authenticate header when the token is missing, expired or revoked. The client should sign in again.
`internal_error`	Something failed on our side. Retrying later is safe for read tools; for write tools, check list_recent_jobs first so a job isn't made twice.

A job that fails or is cancelled is not charged; its result has status failure or cancelled and the reason.

Limits

Limit	Value
Image input	HTTPS URL up to 10 MB for pixelate_image and remove_background, 5 MB for animate_sprite and a generate_sprite reference; base64 up to 5 MB decoded.
Inline result	Attached when under 4 MB; larger files come as a link only.
Output links	1 hour each; a job's output can be fetched for 24 hours.
Rate limits	None per request today. Credits limit paid jobs, since each job reserves its cost while it runs. Planning high volume? Write to us first.

Data use

The server acts only for the signed-in user, and jobs belong to that user and the connected app. What we store and why is in the Privacy Policy and Terms. Users can opt out of AI training for their whole account (how). Jobs made through Cursor, Grok and Meta Muse connections are always opted out of training, because those apps' terms require it.

Support

Questions, problems or a result that looks wrong: hello@pixelengine.ai. The same capabilities are available as a plain HTTP API: API reference.