# VoxelDraft MCP

VoxelDraft exposes a free remote Model Context Protocol (MCP) endpoint for AI-assisted voxel modeling.

**Endpoint:** `https://voxeldraft.com/api/mcp`

Use VoxelDraft MCP when an AI assistant needs to create or edit a voxel model, preview the result as an image or interactive 3D scene, save it to a private VoxelDraft account, or export an optimized OBJ/MTL asset.

Creating, editing, inspecting, rendering, and exporting models require no VoxelDraft account or API key. Account access is optional and is requested through OAuth only when a user asks to save, list, or load private cloud projects.

## Why it is token-efficient

An AI model does not need to emit one verbose JSON object per voxel, generate Three.js/OpenGL rendering code, or hand-build an OBJ mesh.

Instead, VoxelDraft accepts a compact instruction stream such as:

```json
{
  "name": "Small house",
  "palette": ["#b45309", "#dc2626", "#60a5fa"],
  "commands": [
    ["box", 4, 0, 4, 19, 7, 19, 0, true],
    ["roof", "x", 3, 8, 3, 20, 13, 20, 1],
    ["points", 2, [[8, 3, 4], [15, 3, 4]]]
  ]
}
```

VoxelDraft expands those commands into voxels internally. Complex exact silhouettes can use run-length encoded voxel spans (`runs`), while repeated and symmetric parts use `repeat` and `mirror`.

The returned model handle remains an instruction-level representation. Later MCP calls pass that handle back instead of resending the expanded voxel array.

## Tools

### `create_voxel_model`

Creates a model from a compact command stream and returns:

- an opaque model handle
- voxel count, bounds, and color statistics
- an editable VoxelDraft URL
- a WebGL render URL

### `edit_voxel_model`

Appends modeling commands to an existing handle. This makes iterative AI editing cheap because the model does not need to reproduce the entire scene.

### `inspect_voxel_model`

Returns model statistics without dumping the complete voxel set into the LLM context.

### `render_voxel_model`

Returns an interactive browser render URL backed by VoxelDraft's existing Three.js / React Three Fiber renderer.

By default it also attempts to return a 512×512 PNG directly as MCP image content. The preview is rendered by Cloudflare Browser Run from the existing VoxelDraft WebGL viewer and cached in R2 by model hash, so repeated renders of the same model do not launch another browser session. Set `includeImage` to `false` when only URLs are needed, or choose `imageSize: 256` for a smaller preview.

If image rendering is temporarily unavailable or not configured, the tool still succeeds and returns the interactive WebGL and editor URLs.

### `export_voxel_model`

Returns direct export URLs.

For OBJ export, VoxelDraft performs mesh generation itself:

- fully hidden internal faces are omitted
- vertices are shared between visible faces
- materials are grouped by voxel color
- OBJ and MTL are generated separately for normal game/3D workflows

A model therefore does not have to spend tokens producing thousands of `v`, `vn`, and `f` lines itself.

### `save_voxel_model`

Optional authenticated tool. Saves a compact MCP model to the user's private VoxelDraft Cloud Projects. OAuth is requested only when this tool is used. Passing `projectId` updates an existing project owned by the user.

Required OAuth scope: `voxeldraft:projects:write`.

### `list_voxel_projects`

Optional authenticated tool. Lists the user's private cloud-project summaries without returning all voxel data.

Required OAuth scope: `voxeldraft:projects:read`.

### `load_voxel_project`

Optional authenticated tool. Loads a private VoxelDraft project and converts its voxel data back into a compact MCP model handle using run-length encoded spans, so the complete raw voxel array does not have to enter model context.

Required OAuth scope: `voxeldraft:projects:read`.

## Compact command grammar

Coordinates are integer voxel positions from `0` to `63`. Colors can be `#RRGGBB` strings or zero-based indices into the optional `palette`.

```text
["box", x1,y1,z1, x2,y2,z2, color, hollow?]
["ellipsoid", cx,cy,cz, rx,ry,rz, color, hollow?]
["cylinder", "x"|"y"|"z", x,y,z, radius,height, color, hollow?]
["line", x1,y1,z1, x2,y2,z2, color]
["roof", "x"|"z", x1,y1,z1, x2,y2,z2, color]
["runs", "x"|"y"|"z", color, [[x,y,z,length], ...]]
["points", color, [[x,y,z], ...]]
["erase", x1,y1,z1, x2,y2,z2]
["recolor", fromColor, toColor]
["copy", x1,y1,z1, x2,y2,z2, dx,dy,dz]
["repeat", x1,y1,z1, x2,y2,z2, dx,dy,dz,count]
["mirror", "x"|"y"|"z", plane, x1,y1,z1, x2,y2,z2]
```

Recommended strategy:

1. Use `box`, `roof`, `ellipsoid`, and `cylinder` for bulk geometry.
2. Use `runs` for irregular exact forms such as hair, foliage, clothing, trim, and silhouettes.
3. Use `repeat` for windows, columns, fences, wheels, and other repeated structures.
4. Use `mirror` for characters, vehicles, architecture, and other symmetric forms.
5. Use `points` only for sparse details.

`runs` is the exact/freeform escape hatch: it can represent arbitrary voxel geometry without repeating a color and object keys for every single voxel.

## Rendering

MCP-generated models can be opened directly in the existing VoxelDraft read-only viewer:

```text
https://voxeldraft.com/en/embed/?m=<MODEL_HANDLE>
```

The same handle can be opened as a normal editable project:

```text
https://voxeldraft.com/en/edit/?m=<MODEL_HANDLE>
```

The model is expanded locally in the browser and rendered through VoxelDraft's normal WebGL pipeline. MCP image previews reuse that viewer through Browser Run rather than implementing a second 3D rasterizer inside the Pages Function.

## Account linking and privacy

VoxelDraft's public modeling tools are anonymous. Private project access uses standards-based OAuth discovery through:

```text
https://voxeldraft.com/.well-known/oauth-protected-resource
```

OAuth clients receive only the scopes approved for them. Cloud projects remain associated with the existing VoxelDraft account and are stored in the same private Cloud Projects system used by the web editor.

## Exports

`export_voxel_model` currently exposes:

- optimized OBJ + MTL
- compact VoxelDraft JSON

The MCP response returns download URLs instead of inserting large asset contents into the AI conversation.

## Discovery

VoxelDraft publishes `server.json` metadata for the official MCP Registry under `io.github.huruki-geo/voxeldraft`. The remote Streamable HTTP endpoint is the same public endpoint shown above.

Useful discovery phrases include: AI voxel model generator, voxel modeling MCP server, AI 3D voxel tool, MCP OBJ exporter, and browser-based AI voxel editor.

## Protocol compatibility

The endpoint is stateless for anonymous modeling and supports the current MCP `2026-07-28` lifecycle as well as legacy initialize-based Streamable HTTP clients. OAuth is only introduced when protected account tools are called.