Documentation

Claude Code setup

Let Claude Code discover, install, customize and validate the kit — with our MCP server or with only the installed files. Tested with Claude Code 2.1.283.

1. Prepare the project

Start from the quickstart starter (or any Vite + three.js project with the SDK installed). Export the registry and token in the shell you start Claude Code from:

Terminal

export AGENT_READY_ASSETS_REGISTRY=<registry origin>
export AGENT_READY_ASSETS_TOKEN=<API token from your account page>

What the placeholders in the commands mean

<registry origin> and <site origin>: the address of this website, scheme and host only (for example https:// followed by the host name in your address bar, no path). The website, the account service and the catalog registry share this one origin; the MCP server is at <registry origin>/mcp. The CLI accepts https only (plain http only for a local loopback registry).
<API token from your account page>: create one on your account page after signing in. It installs only what your account is entitled to; the free sampler needs no token.
Run npx agent-ready-assets … only inside the project where the SDK is installed: npx then runs the project's own CLI from node_modules/.bin. Outside such a project npx would look for a package of that name on the public npm registry, where we publish none — do not run it there (pnpm exec agent-ready-assets … never downloads anything).

2. Connect the MCP server (optional)

.mcp.json — no secret in the file (the token comes from AGENT_READY_ASSETS_TOKEN)

{
  "mcpServers": {
    "agent-ready-assets": {
      "type": "http",
      "url": "<registry origin>/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENT_READY_ASSETS_TOKEN}"
      }
    }
  }
}

Terminal

claude --mcp-config .mcp.json

Without MCP, start Claude Code as usual: the kit's README.md, kit.json, the manifests and npx agent-ready-assets inspect --capabilities --connectors carry the same facts.

3. Paste a prompt

These are the exact prompts of recorded runs that passed every graded check. Edit the task part freely; keep the rules (inspect first, do not invent, report what cannot be done).

With MCP: the prompt of a recorded run

You are working in a fresh Vite + TypeScript + Three.js project (pnpm; dependencies are already installed, including the
pre-release Agent-Ready Assets SDK 0.5.0 packages and the agent-ready-assets CLI). I have developer-preview access to the
"stylized-town" kit: the registry origin and my API token are already exported in this shell, as the website's setup
pages describe. The Agent-Ready Assets MCP server ("agent-ready-assets") is connected; use it together with the website.

The Agent-Ready Assets website runs on this machine at <site URL> and has all the documentation: start at
<site URL>/docs and follow its onboarding pages. Do not look for documentation anywhere else.

Task: build a small customized town from the "stylized-town" kit, version 0.4.0.
1. Install the kit into this project. Never write the token into any file.
2. Describe the town in a version-pinned scene file, src/scenes/town.scene.json, and render it with the SDK in
   src/main.ts:
   - a street block of road tiles with street furniture (lamps, benches and the like) snapped onto the sidewalks
     instead of hand-placed coordinates;
   - two houses that are variants of the same base house model — the same house asset for both — with different door, window and roof choices and different wall colours from the kit's swatches;
   - a cafe with its terrace;
   - the town hall with its flag.
   The town will grow to a few hundred buildings later, so keep it efficient to render.
3. Also give one of the houses a flat roof, and make the town hall three storeys tall.
4. Validate the installation and the town with the documented checks, up to a LOCALLY_VALIDATED browser verification,
   and make sure pnpm build succeeds.
I have no Blender or Blender MCP. If a requested edit exceeds what the kit allows, say exactly which changes cannot be
made and what documented alternatives exist. Work only inside this project directory. Finish with a short report: the
website pages you used, what you installed (with versions), what you customized and snapped, what could not be done
and why, and the validation results.

The town this run built uses 3 building models (stylized-town/cafe-01@0.1.0, stylized-town/house-01@0.2.0 ×2, stylized-town/townhall-01@0.1.0): different assets whose defaults differ, not variants of one model. For buildings that differ only by parts and colours, use variants of one base asset (for example stylized-town/house-01@0.2.0 twice).

Without MCP: the prompt of a recorded run

You are working in a fresh Vite + TypeScript + Three.js project (pnpm; dependencies are already installed, including the
pre-release Agent-Ready Assets SDK 0.5.0 packages and the agent-ready-assets CLI). I have developer-preview access to the
"stylized-town" kit: the registry origin and my API token are already exported in this shell, as the website's setup
pages describe. There is no MCP server available.

The Agent-Ready Assets website runs on this machine at <site URL> and has all the documentation: start at
<site URL>/docs and follow its onboarding pages. Do not look for documentation anywhere else.

Task: build a small customized town from the "stylized-town" kit, version 0.4.0.
1. Install the kit into this project. Never write the token into any file.
2. Describe the town in a version-pinned scene file, src/scenes/town.scene.json, and render it with the SDK in
   src/main.ts:
   - a street block of road tiles with street furniture (lamps, benches and the like) snapped onto the sidewalks
     instead of hand-placed coordinates;
   - two houses that are variants of the same base house model — the same house asset for both — with different door, window and roof choices and different wall colours from the kit's swatches;
   - a cafe with its terrace;
   - the town hall with its flag.
   The town will grow to a few hundred buildings later, so keep it efficient to render.
3. Also give one of the houses a flat roof, and make the town hall three storeys tall.
4. Validate the installation and the town with the documented checks, up to a LOCALLY_VALIDATED browser verification,
   and make sure pnpm build succeeds.
I have no Blender or Blender MCP. If a requested edit exceeds what the kit allows, say exactly which changes cannot be
made and what documented alternatives exist. Work only inside this project directory. Finish with a short report: the
website pages you used, what you installed (with versions), what you customized and snapped, what could not be done
and why, and the validation results.

Buildings that differ: say which pattern you want

“Two houses with different doors” can be met by two different assets whose defaults differ, or by two variants of one house. If you want variants of one model, say so; add a sentence like this to the task part of the prompt (the pattern):

Add to the task

Build the houses as variants of one base asset: use stylized-town/house-01@0.2.0 for every house and vary only its declared capabilities (front-door, window-style, roof, wall-color) between the instances. Use another asset only for another footprint or shape. Check every value with get_customization_capabilities or npx agent-ready-assets inspect stylized-town/house-01@0.2.0 --capabilities.

What a good run looks like

The agent inspects capabilities before writing, installs with kit add, writes a pinned scene.json, runs verify, scene validate and verify-project --browser chromium (LOCALLY_VALIDATED), and reports requests the kit cannot fulfil — such as a three-storey town hall — as not possible instead of faking them. See the agent-built town (that run used 3 building models, cafe-01, house-01, townhall-01, not variants of one model: for that, see variants of one base asset).

4. What Claude Code should use (SDK 0.5.1)

These SDK features are newer than the recorded runs above, whose prompts do not mention them; they are documented and tested in the SDK.

Large scenes: library.assembleScene(scene, { optimize: true }) (Three.js) or <OptimizedScene> with instanceId on each <Asset> (React Three Fiber). Same image, fewer draw calls; the Three.js and R3F entry files already do it.
Types: npx agent-ready-assets doctor prints where the declarations are (node_modules/@agent-ready-assets/runtime-three/dist/index.d.ts); read them instead of guessing an API.
Configs: npx agent-ready-assets customize stylized-town/house-01@0.2.0 --config my-config.json --dry-run validates a config and writes nothing; await town.customize(instanceId, values) re-customizes one instance of an assembled scene (customization).
Variants: several instances of one asset with different declared swap choices and swatches (variants of one base asset); another asset only for another footprint or shape. What is refused, and what to do instead: capabilities and limits.