Getting started

1. Install

Take the build for your system from the download page and run it. On Windows that is the installer or the portable build; on macOS, the Apple Silicon or the Intel disk image.

Neither build is code-signed yet, so the first launch needs one confirmation — More info → Run anyway on Windows, right-click → Open on macOS. After that the app starts like any other.

There is no account and no sign-up. The starter pack — furniture, panoramas, materials, all CC0 — is inside the app, so you can build the first scene with the network switched off.

2. Connect an agent

Start Cuberta. When the built-in server is up, the window title reads MCP listening on 7345.

Press Copy connect command in the top-right corner. For Claude Code the clipboard gets a line like this — paste it into a terminal:

claude mcp add --transport http cuberta http://127.0.0.1:7345/mcp \
  --header "Authorization: Bearer <token>" --scope user

Then start your agent in any folder. --scope user is what makes the server available everywhere rather than in the one directory you happened to be in.

Any other MCP client connects the same way: the URL http://127.0.0.1:7345/mcp over Streamable HTTP, and the header Authorization: Bearer <token>. The token is generated on first launch and lives in your own config file — %APPDATA%\Cuberta\config.json on Windows, ~/Library/Application Support/Cuberta/config.json on macOS.

The server listens on localhost only, and the token is never printed on screen: the window ends up in screenshots and recordings, so the button puts it on your clipboard instead.

3. Your first brief

The agent learns the editor from the tool descriptions and from five guides it can read on its own. Pointing it at the right guide first is the single biggest improvement you can make to a brief:

• “Read cuberta://guide/scenes, then build a cosy living room 6×4 m with a sofa, a coffee table and warm evening light. Show me a frame when it is done.”
• “Read cuberta://guide/world first. Build a small town: a street grid with a ring road, cottages with pitched roofs, street lamps and trees along the sidewalks, sunset light. Then audit it with the scene linter and show me frames from street level and from above.”
• “Load the reference images from the board and reproduce the street in the photo as closely as you can; invent whatever is not visible.”

Ask for a frame at the end of each step. It is the fastest way to catch a misunderstanding while it is still cheap to fix.

4. While it builds

You are not locked out while the agent works. Everything you do goes through the same commands it uses, so the two of you share one undo history and one timeline.

• Click any object — the agent is told a human selected it.
• W / E / R move, rotate and scale with the gizmo; hold Ctrl to snap.
• Right mouse button + WASD flies the camera.
• Draw zones to say where to build and where not to.
• Drop a texture from the material browser onto an object to reassign it.
• The timeline at the bottom rolls the scene back to any earlier step; Ctrl+Z undoes the last one, whoever made it.
• F1 lists every shortcut.

5. Save and export

File → Save writes a project folder: scene.json next to meshes/ (baked geometry), renders/ (frames the agent took) and refs/ (your reference board). File → Open project… picks the scene.json of such a folder.

File → Export to GLB… writes one .glb with every texture embedded. File → Export to FBX… writes a binary FBX the same way, with axes and units already set for Unity, Unreal, Maya and Blender. Export runs in its own process, so the window stays responsive on a heavy scene.

Before exporting a large location, it is worth asking the agent to bake, merge and split it into tiles — the tools for that are part of the same set, and the result streams much better in an engine.

6. When something is off

The title bar does not say “MCP listening”. Another program may hold port 7345. Close it and restart Cuberta.

The agent does not see the tools. Check that the connect command was pasted with --scope user, and that your client was restarted after it. In Claude Code, claude mcp list shows whether Cuberta is registered and reachable.

Everything is white or the viewport is empty. The viewport needs WebGL 2. Updating the graphics driver fixes this in nearly every case.

An import came in at the wrong size. Models are normalised to metres with the pivot at the base, so a mismatch usually means the source file declares different units — ask the agent to rescale it, or set the size explicitly in the brief.

Still stuck? Write to us with your system, the app version and what you were doing.