Connect ToonLab to your AI coding agent

The ToonLab MCP server gives any MCP-compatible tool — Claude Code, Claude, Cursor, Codex, and others — direct access to asset search, AI generation, stored characters, and your cloud library. It keeps anime-game style, provenance, sourcing policy, and custom-gap decisions explicit instead of silently generating replacements. Included with Pro and Team plans.

https://toonlab.io/mcp

Setup by client

Claude Code

claude mcp add --transport http toonlab https://toonlab.io/mcp

Then run /mcp inside Claude Code to authenticate — your browser opens the ToonLab authorization screen once.

Claude (claude.ai and desktop)

1. Open Settings → Connectors → Add custom connector.
2. Enter https://toonlab.io/mcp and confirm.
3. Sign in to ToonLab in the browser window and choose Authorize.

Cursor

Add the server to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "toonlab": {
      "url": "https://toonlab.io/mcp"
    }
  }
}

Everything else

Any client that supports remote MCP servers with OAuth works the same way: add https://toonlab.io/mcp as a remote server — most clients accept the JSON shape above — and approve access in the browser when prompted. Manage or revoke authorized clients any time in Settings → MCP.

{
  "mcpServers": {
    "toonlab-local": {
      "command": "npx",
      "args": ["-y", "@call-me-sensei/toonlab@latest", "--workspace", "/absolute/path/to/your-game/.toonlab"],
      "env": { "TOONLAB_LEGACY_WORKSPACE": "1" }
    }
  }
}

Tool reference

Protocol and result envelope

The endpoint implements remote Streamable HTTP MCP and OAuth 2.1. Tool arguments are JSON objects. Successful calls return the value in structuredContent plus a compact JSON text fallback in content[0].text. Validation, authorization, policy, quota, and missing-target failures return a tool result with isError: true; malformed JSON-RPC requests use normal JSON-RPC errors. Responses containing account data are sent with Cache-Control: private, no-store.

Lab management API

Start with list_live_labs, then call get_lab_features for the chosen Lab. This is the contract an agent should use when it needs to author a creation without making the user translate dozens of controls by hand.

get_lab_features response

{
  "lab": {
    "id": "rock-shader",
    "creationTypes": ["rock-shader-preset"],
    "management": { "creationCrud": ["create", "read", "update", "delete"] }
  },
  "capabilities": {
    "authoring": { "featureMutation": "set_feature", "structuralOperations": [] },
    "outputs": ["portable-preset", "runtime-style-bundle"],
    "preview": { "clientOwned": true, "persisted": false }
  },
  "featureCount": 68,
  "schema": { "material": { "tint": { "type": "color" } } },
  "documentContract": {
    "creationType": "rock-shader-preset",
    "discriminator": { "path": "schema", "value": "toonlab/rock-shader-preset" },
    "schemaVersion": 1,
    "versionPath": "version",
    "idPath": "id",
    "labelPath": "label",
    "featureRoot": "settings",
    "featureApplication": "direct",
    "docKey": { "path": "id", "requiredSeparately": false },
    "jsonSchema": {},
    "starterDocument": {}
  }
}

The response includes every field descriptor, a structural JSON Schema, source/output capabilities, and a populated schema-valid starterDocument. Prefercreate_lab_document for new documents and mutate_lab_creation for validated edits. featureRoot identifies where direct settings live. Tree recipes report compiled-authoring-state because their UI controls compile into recipeoptions. Rock projects have no internal id, so their document key must be supplied separately.

Rock source-mesh edits use compact base64-f32le-v1 float32 storage, with a portable-project budget of 200 operations and 10,000 vertex deltas. The editor restores the normal editable arrays on load. Adaptive meadow grass, camera, lighting, and viewport state remain preview-only. First-party Rock details include a ready labStart document that retains the selected released GLB and its Call Me Sensei material.

Creation CRUD API

doc_key is portable identity within a creation type. The returned creation UUID is the management identity for subsequent reads, edits, deletes, and Open in Lab. Supplying another account's UUID returns the same not-found result as an absent creation. Team visibility requires current team membership. A merge-patch null removes the addressed property; clients should preserve the discriminator and schema version.

The private Library is a first-class discovery source, not a list-only fallback. Human developers use the same name/type/tag filters on the Library page; coding agents uselist_my_creations. Tags are normalized lowercase slugs and persist across save, update, Lab sync, and later publication, where Gallery search uses them too.

{
  "type": "rock-shader-preset",
  "doc_key": "harbor-cliffs",
  "label": "Harbor cliffs",
  "description": "Reusable cliffs for the harbor district",
  "tags": ["harbor", "cliff", "outdoor"],
  "document": { "...": "copy and edit documentContract.starterDocument" }
}

{
  "id": "8a6e6bf7-693a-4a4d-9da5-a7c64bc3c842",
  "patch": { "settings": { "material": { "tint": "#d9cba4" } } },
  "label": "Warm quay rock",
  "tags": ["harbor", "quay", "warm-stone"],
  "visibility": "private"
}

Hosted Lab synchronization

Every Lab in the table round-trips its named portable documents to the signed-in library. Browser drafts remain local and are not silently promoted into creations. Opening an owned, team-visible, unlisted, or public creation injects that exact document into its native Lab store before boot and selects it through the Lab's URL contract. Sky, Cloud, and Sky & Cloud intentionally share one sky-params library; their ownedPathsmetadata tells an agent which parameter groups each focused surface owns.

Validation, limits, and errors

• Creation documents are validated against their registered portable schema before save or replacement.
• The 256 KiB document limit is measured as UTF-8 bytes, so non-ASCII text consumes its actual encoded size.
• Deletion requires the literal boolean confirm: true.
• Generation requires policy approval, a recorded gap, sufficient entitlement/credits, and a UUID idempotency key.
• Use the pagination fields returned by search tools; do not assume the first page exhausts a catalog.
• Temporary generated-asset downloads expire. First-party public catalog artifact URLs are immutable.

How generation and credits work

A kind: "material" request uses Fal Patina. ToonLab stores and displays the generated preview, every variant, the requested base-color/normal/ roughness/metalness/height maps, and the JSON manifest as one material unit. Resolution presets run from 1K through 8K; custom map counts, variants, inference steps, prompt expansion, and upscaling determine the exact charged credits.

Provider selection is part of the contract. Pass model_provider: "meshy" for Meshy 7 or model_provider: "tripo" for Tripo. Meshy image-to-3D accepts PNG/JPEG input and multi-view accepts 2–4 images. A text request with Meshy first creates a concept image through the selected image_model, then returns a parent concept jobId and child model childJobId/jobIds to poll. Meshy does not support model segmentation; use Tripo for that operation. Ifmodel_provider is omitted, the current Pro compatibility default is Tripo, so agents that intend Meshy must never rely on omission.

1. Discover and validate first. Search the project library, ToonLab gallery, and only then policy-permitted external sources. The gallery tool covers community work plus every published ToonLab rock and tree; use source: "toonlab",catalog: "rock" or "tree", and the returnednextOffset to exhaust a catalog. Rock results expose dimensionsMetersplus family, profile, and taxonomy for selection before download. A strict denial cannot be bypassed by generation.
2. Record the gap. Call record_asset_gap and write its result to .toonlab/reports/style-asset-gaps.json and TOONLAB_ASSET_GAPS.md.
3. Check first. get_generation_capabilities returns your balance, enabled providers/models, supported operations, and the exact credit cost of every kind and resolution — agents should call it before spending.
4. Generate. generate_asset requires the approved policy, semantic domain, and recorded gap id, then spends exactly the quoted cost. Each call takes a fresh idempotency_key (a UUID), so a retried request returns the original job instead of spending twice.
5. Chain to 3D. Pass auto_chain: true on an image kind and an explicit model_provider to queue image→3D after the image is ready. For Meshy text mode, also choose image_model; both stages are visible and pollable. Combined costs are reserved up front and each failed step refunds itself.
6. Poll and save. get_generation_jobs returns progress and a suggested polling interval; when ready, download from the temporary URL or persist with save_generated_asset.

Shaders and procedural runtime

Call get_runtime_guide with shaders, procedural,rock, tree, texture, or style-bundles. The response names the public package entry points and gives runnable examples. The key contract is deliberate: generators own geometry, editable recipes, labels, baked channels, LOD, and collision; domain shaders own appearance. Labs are authoring examples rather than runtime dependencies.

Security

Access uses OAuth 2.1 with PKCE — your password is never shared with the client, tokens are scoped to the permissions shown on the authorization screen, and generation tools are flagged as consequential actions so well-behaved agents confirm before spending credits. Creation reads, edits, and deletes are ownership-scoped on the server; a creation UUID belonging to another account does not grant access. Revoke any client from Settings → MCP; revocation is immediate.

Next

The prompt cookbook shows how to put these tools to work — from the first "start a game" prompt to character-consistent art pipelines.