# VoxelShaper MCP

> Free headless voxel MCP for AI agents: build voxel models in isolated sessions, add Box3D physics joints and export colored 3MF files for 3D printing. No signup, no paid tier. MCP never publishes to the Hub.

Transport: streamable-http. Open endpoint `/mcp/free` needs no key. The keyed endpoint `/mcp` uses the free public community key: `X-VS-MCP-Key: NftAhWkodYOOYdzLSDuLwthzjjd5JGO0tqp9tO_-pLk` (alternate: `Authorization: Bearer NftAhWkodYOOYdzLSDuLwthzjjd5JGO0tqp9tO_-pLk`).

```
curl -sS -H 'X-VS-MCP-Key: NftAhWkodYOOYdzLSDuLwthzjjd5JGO0tqp9tO_-pLk' https://api.voxelshaper.com/mcp/health
```

Coordinates: Z-up. Ground / print bed = XY, height = +Z. x = right, y = depth/forward, z = up. Y is NOT height. Floor plate: z=0. A standing figure grows in +z.

Tools: new_session (isolated session, returns session_id), get_session / end_session, place_block / set_voxels / delete_block / edit_block / color_block, list_blocks / get_bounds / clear, load_project_json / dump_project_json, set_physics_joint / list_physics_joints / delete_physics_joint / clear_physics, export_3mf (short-lived 3MF download URL), make_model. `publish_model` on `/mcp` only creates a private, short-lived view link; it never creates a Hub card. Public Hub publishing is done on hub.voxelshaper.com by a signed-in user.

Minimal session: 1. GET the descriptor. 2. POST the MCP endpoint (or POST /mcp/new_session on the keyed JSON API). 3. set_voxels, then export_3mf. 4. end_session.

## Connect now

- [Open MCP endpoint](https://api.voxelshaper.com/mcp/free): POST, streamable-http, no key, sandboxed (rate limits, 20k voxels, idle expiry)
- [Keyed MCP endpoint](https://api.voxelshaper.com/mcp): POST, streamable-http, free community key in `X-VS-MCP-Key`
- [MCP descriptor](https://api.voxelshaper.com/.well-known/mcp.json): Live machine descriptor with tools and limits
- [Hub MCP descriptor](https://hub.voxelshaper.com/.well-known/mcp.json): Same descriptor mirrored on the Hub
- [Health](https://api.voxelshaper.com/mcp/health): Liveness check
- [Tools list](https://api.voxelshaper.com/mcp/tools): JSON list of tools

## Docs

- [MCP guide for humans](https://hub.voxelshaper.com/mcp.html): Connect, coordinates, tools
- [Hub](https://hub.voxelshaper.com/): Community voxel models with 3MF/STL downloads

## Optional

- [Editor](https://voxelshaper.com/): Browser voxel editor
- [robots.txt](https://hub.voxelshaper.com/robots.txt): Crawl rules
- [ai.txt](https://hub.voxelshaper.com/ai.txt): AI usage notes