MCP Integration

How to talk to the Spriteoven MCP server, what the 14 tools do, and the operational guarantees (auth, rate limits, RLS, billing).

This document covers two audiences: integrators wiring an IDE (Claude Code, Cursor, Cline, Zed, Continue) to Spriteoven, and provider maintainers extending the server's tool surface. The split is signposted inline.

Wave 5b shipped the MCP server live; MCP-F1 and MCP-F2 grew it to 14 tools over a single Streamable HTTP endpoint, Bearer auth via Supabase JWT. The /mcp page on spriteoven.com auto-prefills the install one-liner once you're signed in — that's the canonical entry point. This doc is the textual back-up + reference for operators.

🔑 The 14 are not a list somebody typed here. They are three blocks that server/index.js composes in the augment of mcpHandler, and each block owns its own names:

block	source of truth	count
historical (Wave 5b)	listMcpToolNames() — server/lib/mcp-server.js	3
read-only (MCP-F1)	READ_TOOL_NAMES — server/mcp/index.js	5
write (MCP-F2)	WRITE_TOOL_NAMES — server/mcp/writeRegister.js	6

tests/053-deudafina.mjs §E1 imports those three and fails if this document's count or any tool name drifts from them. Add a tool and forget this page, and the suite says so — which is the only reason the number above can be trusted.

TL;DR — install (integrator)

Sign in to Spriteoven, then visit /mcp. Click Copy next to the claude mcp add ... block. Paste in your terminal. Restart Claude Code.

# example (the real Bearer is auto-prefilled by /mcp)
claude mcp add spriteoven https://spriteoven.com/mcp \
  --transport http \
  -H 'Authorization: Bearer <YOUR_SUPABASE_JWT>'

For Cursor / Cline / Zed / Continue, click ▾ Other clients on /mcp and copy the JSON config block — same Bearer header, same URL, just the IDE-native config shape.

The Bearer is your Supabase session JWT. It expires per Supabase TTL (default 1 hour). Re-load /mcp after re-login to get a fresh one-liner.

The tool surface — 14 tools in three blocks

Block 1 — the historical 3 (Wave 5b)

Block 2 — read-only (MCP-F1)

Five tools that never spend a credit. READ_TOOL_NAMES, in the fixed order tools/list returns them (the spec asks for determinism so clients can cache and the model's prompt-cache does not churn):

Block 3 — write (MCP-F2)

Six tools, of which 4 generate_* — one per family that publishes a declarative price function. WRITE_TOOL_NAMES:

🔑 The consent pattern: a generate_* called without confirm_token spends nothing — it returns the exact price, the balance before and after, and a token signed over the parameters. The agent is meant to show that price to its user and only then call again with the same parameters plus the token. The quote lives 300 s.

personajes and mapas have no generate_*, and the reason is measured: their endpoints bill per generation inside the worker and publish no declarative price function, so no exact quote can be given before enqueuing — and this surface's whole consent pattern rests on the price being exact. list_generators carries that reason where the agent can read it.

The remaining tools from the spike are deferred to Ciclo 8 backlog (create_version, bulk_generate, batch_status, export_unity, export_aseprite, palette_swap, tilemap_export, animate_sprite). Promotion gate: ≥30 unique MCP installs in 4 weeks post-launch (per spike §6.3). See EVIDENCE/cycle7/wave5/track-r/SPIKE-MCP-SERVER.md.

Auth model

• Bearer token = your Supabase access token. Same JWT the web UI uses. Verified server-side by requireAuth (server/lib/authMiddleware.js) via supabase.auth.getUser(jwt).
• No separate API key surface. This deliberately avoids the PixelLab pattern where users have to find a "create API token" button in a separate dashboard (5-step UX gap, see spike §4.1).
• Rotation = re-login to Spriteoven UI. The new JWT replaces the old one in localStorage; /mcp re-renders with the fresh install one-liner.
• RLS is the source of truth for cross-user isolation. All tool database queries run under the caller's user JWT (RLS-scoped), so get_library cannot return another user's assets and save_to_library on a foreign asset surfaces as ASSET_NOT_FOUND (RLS hides the row).

Rate limits

The MCP endpoint has its own bucket (makeMcpRateLimiter in server/lib/mcp-server.js):

• 60 requests / minute / user (keyed by req.user.id, fallback IP).
• Independent of the AI gen bucket — agent-driven loops can't accidentally starve UI users.
• 429 response is JSON-RPC shaped: {"jsonrpc":"2.0","error":{"code":-32004,"message":"rate_limited","data":{"bucket":"mcp","limit":60,"window_ms":60000}},"id":null}.
• Disabled in tests via RATE_LIMIT_DISABLED=1 (same convention as server/lib/hardening.js).

Billing

generate_sprite runs through the same generation path as the REST /api/sprite-lab/<provider> endpoints. Credits and the WOW 8-gen lifecycle apply identically — the MCP surface does not bypass billing. Specifically:

• Provider API keys live in server env only (BYOK retired 2026-05-19).
• Credits decrement under the user's req.user.id, regardless of whether the call came from the web UI or MCP.
• generate_sprite returns PAYMENT_REQUIRED (mapped to MCP isError) when the caller has 0 credits AND 0 wow remaining.
• WOW gen cap (FREE_WOW_GEN_CAP = 8) is per-user, not per-surface.

get_library and save_to_library are read/write only (no AI gen) and are not billed beyond the per-request rate-limit budget.

Endpoint reference

GET /api/mcp/info (auth required)

Returns the live install payload the /mcp UI prefills. Echoes back the caller's Bearer in the rendered install_command so the user can copy-paste a single line.

{
  "status": "live",
  "wave": "5b",
  "server_url": "https://spriteoven.com/mcp",
  "transport": "http",
  "bearer_token": "<echoed Supabase JWT>",
  "install_command": "claude mcp add spriteoven https://spriteoven.com/mcp --transport http -H 'Authorization: Bearer <JWT>'",
  "clients_supported": ["Claude Code", "Cursor", "Continue", "Cline", "Zed"],
  "tools": ["generate_sprite", "get_library", "save_to_library",
            "list_folders", "list_assets", "get_asset", "list_styles", "get_credits",
            "generate_fx", "generate_deco", "generate_uikit", "generate_item_set",
            "get_job", "export_asset"],
  "rate_limit": { "max": 60, "window_ms": 60000, "scope": "per-user" },
  "notes": "Bearer token = your Supabase session JWT. Re-login to refresh."
}

server_url is computed from SOV_PUBLIC_URL env (preferred) → request origin (x-forwarded-proto + x-forwarded-host honored) → http://localhost:PORT fallback.

POST /mcp (auth required, MCP Streamable HTTP)

Stateless transport (sessionIdGenerator: undefined) per MCP spec 2025-03-26. Each request:

1. requireAuth → vetted Supabase JWT → req.user.
2. mcpRateLimiter → 60/min/user bucket.
3. mcpHandler → builds per-request McpServer + StreamableHTTPServerTransport, wires the historical 3 with a deps bag (sb = RLS-scoped Supabase client; storage = same; generate = provider dispatch; uploadPng = spriteoven-assets bucket put; recordEvent = recordSingleEvent to mcp_tool_invoked / mcp_tool_failed), then its augment hook adds the 5 read-only (registerReadOnlyTools) and the 6 write (registerWriteTools) — in that order, deliberately, so an already-installed client never sees tools/list reshuffled.
4. Transport calls handleRequest(req, res, req.body) — Express's express.json() parsed the body upstream.

GET/DELETE/PATCH on /mcp are not wired. The HTML wrapper at GET /mcp is registered separately near the static-page block.

Provider-side notes (extending the surface)

• Tool implementations live in server/lib/mcp-tools.js as pure DI functions (no SDK coupling). The MCP wrapping happens in server/lib/mcp-server.js. Adding a tool is: write the pure function, register it in buildMcpServer, add the test in test-mcp-tools.js + test-mcp-server.js.
• Each tool wrapper is responsible for shaping the content[] array. Use image blocks for binary outputs (base64), text for human-friendly summaries, structuredContent for machine-readable returns. Errors surface as { isError: true, content: [{type:"text", text:"[CODE] ..."}] } so the calling agent gets a usable message instead of a 500.
• The assets table requires project_id. For MCP-generated sprites we lazy-create a per-user MCP Sprites project (idempotent; ensureMcpProject in mcp-tools.js). Don't insert assets without a project — RLS will reject them.
• Storage uploads to spriteoven-assets follow the path pattern {user_id}/{project_id}/{asset_id}/v1.png — that's the only shape the bucket policies allow (see docs/SUPABASE-SETUP.md). Failures are best-effort: the asset row still inserts, with storage_path:null.

Telemetry events (Track O /api/events table)

Aggregate via getAdminMetrics (/api/admin/metrics) per Track O O.4 spec. Promotion gate (≥30 installs / 4 weeks) reads mcp_install_clicked distinct user count.

Tests

The base npm test (33 tests) is unchanged — MCP suites are dedicated runners following the scripts/cycle7/test-wave5-*.mjs convention.

Operational notes — prompt caching OpenAI

Spriteoven chain-edit reusa la misma reference image entre llamadas. OpenAI aplica image-input caching automático (75% discount $8 → $2 /M tokens) cuando los bytes de la reference son idénticos. Para hit cache hit consistente:

• NO modifiques metadata bytes de la reference entre calls del mismo chain.
• Mantenelos en memoria (Buffer) sin re-serializar a PNG con metadata variable.
• Esperable savings: ~3-5% del costo per-sheet en LPC chain-edit 4-direction.

Text-input caching NO aplica a Spriteoven porque los prompts (~150-200 tokens) están por debajo del threshold mínimo OpenAI (1024 tokens). NO recomendable inflar prompts solo para hit threshold (ROI < 1% costo total).

Referencia técnica: EVIDENCE/cycle7/research/gpt-image-2-pricing-deep-dive.md (commit d04e42c).