{
  "name": "voxelshaper-mcp",
  "version": "1.6.0",
  "description": "Free headless VoxelShaper MCP for AI agents: isolated voxel sessions, Box3D physics joints/motors/limits, and ephemeral 3MF download. MCP never publishes to the Hub; public Hub publishing is done on hub.voxelshaper.com by a signed-in user. No paid tier.",
  "pricing": "free",
  "cost": 0,
  "free": true,
  "license": "free-public-use",
  "homepage": "https://hub.voxelshaper.com",
  "documentation": "https://hub.voxelshaper.com/mcp.html",
  "llms_txt": "https://hub.voxelshaper.com/llms.txt",
  "coordinates": {
    "system": "right-handed",
    "up": "z",
    "ground": "xy",
    "x": "right",
    "y": "depth / forward",
    "z": "height / up",
    "note": "Z-up like MagicaVoxel and 3MF print space. Y is NOT height (not Three.js Y-up). Floor / print bed = constant z (usually z=0). Physics seeds, anchors and axes use the same Z-up coordinates. The browser editor remaps them to Y-up on handoff."
  },
  "transport": {
    "type": "streamable-http",
    "url": "https://api.voxelshaper.com/mcp",
    "local_url": "http://127.0.0.1:3100/mcp"
  },
  "free_endpoint": {
    "url": "https://api.voxelshaper.com/mcp/free",
    "transport": "streamable-http",
    "auth": "none",
    "tools": [
      "new_session",
      "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",
      "make_model"
    ],
    "excluded": [
      "publish_model"
    ],
    "publishes": false,
    "sends_mail": false,
    "writes_accounts": false,
    "limits": {
      "requests_per_min_per_ip": 60,
      "heavy_tools": [
        "export_3mf",
        "make_model"
      ],
      "heavy_per_min_per_ip": 6,
      "heavy_per_hour_per_ip": 60,
      "heavy_per_min_global": 10,
      "max_sandboxes": 24,
      "max_sandboxes_per_ip": 4,
      "sandbox_idle_expiry_ms": 600000,
      "max_voxels": 20000,
      "max_joints": 64,
      "max_body_bytes": 1048576,
      "download_ttl": "single-use, ~5 min"
    },
    "note": "Open sandbox for agents: no account, no key. In-RAM sandboxes expire after idle time; 3MF downloads are single-use. Nothing is published to the Hub."
  },
  "json_control": {
    "base_url": "https://api.voxelshaper.com",
    "health": "https://api.voxelshaper.com/mcp/health",
    "tools": "https://api.voxelshaper.com/mcp/tools",
    "note": "JSON tool routes are also available on the MCP process (proxied under /mcp/* when nginx is configured). publish_model returns a private, expiring share link (not a Hub card)."
  },
  "auth": {
    "type": "api_key_header",
    "required": true,
    "header": "X-VS-MCP-Key",
    "alternate": "Authorization: Bearer <key>",
    "free": true,
    "public": true,
    "pricing": "free",
    "note": "Free for all AIs. No paid tier. Send X-VS-MCP-Key with the public community key from https://api.voxelshaper.com/.well-known/mcp.json (auth.public_key). No key at all: use free_endpoint (https://api.voxelshaper.com/mcp/free).",
    "how_to_get_key": "GET https://api.voxelshaper.com/.well-known/mcp.json → auth.public_key (free shared key)."
  },
  "tools": [
    {
      "name": "new_session",
      "description": "Create an isolated headless voxel session (returns session_id)"
    },
    {
      "name": "get_session",
      "description": "Inspect a session by session_id"
    },
    {
      "name": "end_session",
      "description": "Permanently delete a session and free RAM"
    },
    {
      "name": "place_block",
      "description": "Place/replace a voxel at x,y,z with #RRGGBB. Z-up: z is height, y is depth, floor at z=0."
    },
    {
      "name": "set_voxels",
      "description": "Bulk place/replace many voxels [{x,y,z,color}]. Same Z-up axes as place_block; no remap."
    },
    {
      "name": "delete_block",
      "description": "Remove a voxel"
    },
    {
      "name": "edit_block",
      "description": "Move a voxel (from_* → to_*), optional recolor"
    },
    {
      "name": "color_block",
      "description": "Recolor an existing voxel"
    },
    {
      "name": "list_blocks",
      "description": "Paginated voxel list"
    },
    {
      "name": "get_bounds",
      "description": "Axis-aligned bounds of voxels (min.z is the floor if the model sits on the ground)"
    },
    {
      "name": "clear",
      "description": "Empty session voxels and physics joints (keep session until end_session)"
    },
    {
      "name": "load_project_json",
      "description": "Import VoxelShaper project_json including optional physicsV1 joints"
    },
    {
      "name": "dump_project_json",
      "description": "Export VoxelShaper project_json including physicsV1"
    },
    {
      "name": "set_physics_joint",
      "description": "Create/update a Box3D hinge, slider, or fixed joint with limits and optional motor (MCP coordinates are Z-up)"
    },
    {
      "name": "list_physics_joints",
      "description": "List Box3D joints in the current session"
    },
    {
      "name": "delete_physics_joint",
      "description": "Delete one Box3D physics joint by id"
    },
    {
      "name": "clear_physics",
      "description": "Remove all physics joints while keeping voxels"
    },
    {
      "name": "export_3mf",
      "description": "On-the-fly colored 3MF → short-lived GET download URL (RAM token, ~5 min, single-use; include_base64 opt-in). 3MF is Z-up, same as stored voxels."
    },
    {
      "name": "publish_model",
      "description": "Private share link (noindex, expires after 7 days). Never a Hub card: public Hub publishing is done on hub.voxelshaper.com by a signed-in user."
    },
    {
      "name": "make_model",
      "description": "Request → CAD 3MF download. Never published to the Hub."
    }
  ],
  "links": {
    "hub": "https://hub.voxelshaper.com",
    "editor": "https://voxelshaper.com",
    "api": "https://api.voxelshaper.com",
    "well_known": "https://hub.voxelshaper.com/.well-known/mcp.json",
    "api_well_known": "https://api.voxelshaper.com/.well-known/mcp.json",
    "human_docs": "https://hub.voxelshaper.com/mcp.html",
    "source_readme": "https://github.com/ChristianHohlfeld/api.voxelshaper.com/blob/main/mcp/README.md"
  }
}