Generate 2D game assets from Windsurf
Windsurf reads workspace rules from .windsurf/rules — and the cross-tool AGENTS.md at your repo root — so the setup is one file and one env var.
Point Windsurf at the MCP server.
40 tools over one endpoint — list, read, export, curate frames, generate. Same key, same guardrails as the REST API, and paid tools preview their cost before they run.
{
"mcpServers": {
"spriteship": {
"url": "https://spriteship.com/mcp",
"headers": {
"Authorization": "Bearer ${env:SPRITESHIP_API_KEY}"
}
}
}
}Windsurf reads MCP servers from its MCP settings JSON (editable from Settings → MCP, or the mcp_config.json it writes). The {url, headers} shape above is the standard streamable-HTTP server entry.
# 1. Point your agent's shell at your key export SPRITESHIP_API_KEY="ss_live_..." # 2. Confirm it works curl -sS -H "Authorization: Bearer $SPRITESHIP_API_KEY" \ https://spriteship.com/api/v1/me # 3. Teach the agent the API — the skill ships an AGENTS.md cat <spriteship-skill>/AGENTS.md >> AGENTS.md
Add the skill too.
MCP gives Windsurf the tools. The skill gives it the recipes — how to sync into a project tree, how to re-sync only what changed, and the protocol it must follow before spending a credit. They compose.
# The skill ships an AGENTS.md — drop it in as a workspace rule: mkdir -p .windsurf/rules cp <spriteship-skill>/AGENTS.md .windsurf/rules/spriteship.md # Cascade will now use the SpriteShip API when you ask for art.
Windsurf reads rules from .windsurf/rules (the older .windsurfrules at the repo root still works), and also picks up AGENTS.md. Any of the three is fine — pick whichever your team already uses. <spriteship-skill> is the SpriteShip agent skill — getting the skill →
Built for how Windsurf works.
Cascade handles the multi-step sync
Pulling a character is list → resolve id → export → unzip → place → record lock file. That is a chain, and a flow-style agent runs it end to end instead of stopping after the first call.
Long jobs are pollable, not blocking
Generation returns a job id immediately. The agent polls /api/v1/jobs/:id and keeps working, so a two-minute video pass never wedges the session.
Errors are typed
Every failure carries a machine-readable code — INSUFFICIENT_CREDITS, ENTITY_BUSY, RATE_LIMITED — so the agent can branch on the reason instead of parsing English out of a message.
One ask, start to finish.
"make a parallax forest background for the side-scroller and drop it in"
- 01Reads the project game type so the background matches the perspective
- 02Previews the cost with dryRun and waits for your go-ahead
- 03Generates the layered background, polling the job to completion
- 04Downloads each parallax layer and wires the scroll factors in your scene
The full loop, once.
Every agent runs the same shape — resolve, preview the cost, confirm, generate, poll, write the files, wire the code.
you › the knight needs a dodge-roll animation, then wire it into the player state machine
agent › GET /api/v1/characters?name=knight
→ chr_8fq2… · contentVersion 4a1c… · 6 animations
agent › POST /api/v1/characters/chr_8fq2…/generate-pose { dryRun: true }
→ 400 credits · balance 1,500 → 1,100
you › go ahead
agent › POST /api/v1/characters/chr_8fq2…/generate-pose
Idempotency-Key: 7c1f-…
→ job_2b9e… queued
agent › GET /api/v1/jobs/job_2b9e… → running
agent › GET /api/v1/jobs/job_2b9e… → done · 400 credits charged
agent › GET /api/v1/characters/chr_8fq2…/export?engine=phaser&format=json
→ wrote assets/spriteship/knight/spritesheet.png
wrote assets/spriteship/knight/atlas.json
wrote spriteship.lock.json (contentVersion 91be…)
agent › edited src/player/PlayerStateMachine.ts
+ case 'dodge': this.play('dodge_roll'); break;
done — dodge_roll is registered and playable. 400 credits spent.Handing an agent a budget, safely.
An agent that can spend money needs more than an API key. Every one of these is enforced server-side — not a convention the agent is trusted to follow.
Scoped keys
Four scopes, granted separately: assets:read, account:read, assets:write, credits:spend. A read-only key physically cannot spend money.
Per-key spend caps
Every key carries a daily credit ceiling — 5,000 by default, 50,000 maximum. Accounting is gross, so refunds restore your balance but never hand the key back headroom.
Over MCP, paid tools preview by default
Every paid MCP tool defaults to a dry run: it returns the exact credit cost and your resulting balance, and executes nothing. The agent has to deliberately re-call with dryRun:false to spend. Accidental spend is not a thing it can stumble into.
Idempotency keys
Paid writes require an Idempotency-Key header. A retried request replays the original job pointer instead of starting — and paying for — a second generation.
Busy-entity guard
A write against an entity that already has a job running answers ENTITY_BUSY rather than racing it, so two agents (or one confused agent) cannot corrupt the same character.
Re-sync signals
Every read carries contentVersion or updatedAt. The agent diffs those against its lock file and re-downloads only what actually changed after you edited something in the dashboard.
Presigned binaries
Every sheet, atlas, zip and preview URL is presigned and expiring. Nothing in an API response is a permanent public link.
Kill switch
Revoking a key cancels its in-flight jobs and refunds their unfinished charges. Leaked keys found by GitHub secret scanning are revoked automatically and you get an email.
Output an agent can actually use.
A folder of PNGs makes an agent guess. Every SpriteShip export explains itself, so the agent wires it up instead of improvising.
Self-describing bundles
Every export zip carries a manifest (tizo-export.json), a JSON Schema of its own shape, a README, a runnable preview and a SKILL.md — so an agent can consume the output without you explaining the format.
Native engine files
Phaser atlases, Godot 4 .tres resources, Unity sliced sprites with stable GUIDs, GameMaker sprite strips and Tiled tilesets. Not a folder of PNGs the agent has to guess at.
Collision, not bounding boxes
Authored collision bodies and ground footprints ride through the API and into every export, so the agent builds the real collider instead of defaulting to the sprite rectangle.
Mount points
Per-frame anchor points for weapons, hands and heads travel with the animation, so the agent can parent a projectile spawn to the right pixel on the right frame.
Windsurf, specifically.
Does this work with the free tier?
Yes. New accounts start with 1,500 credits and no card. Reading, listing, exporting and re-syncing existing assets are all free forever — only generation spends credits.
What stops a runaway agent draining my balance?
Three independent limits: the key needs the credits:spend scope at all, it has a daily credit cap (5,000 by default), and there are hard ceilings on paid attempts and concurrent jobs per key. You also get an email the first time a key spends anything.
Related
Claude Code gets the richest integration of any agent — a packaged skill with its own slash commands, not just an instruction file.
Cursor reads project rules from .cursor/rules — drop the SpriteShip rule there and Composer can fetch art the same way it fetches a package.
Cline reads .clinerules, runs in your editor with your terminal, and asks before acting — which lines up exactly with how paid generation is designed to work.
Point Windsurf
at your art.
1,500 free credits, no card. Reading and re-syncing never cost anything.
Start free — 1,500 credits