Set up Mosaic

Mosaic connects your Unity Editor to Claude, so you can build course material and drive the Editor by describing what you want. Setting up takes about twenty minutes, most of it Unity downloading itself. The course pipeline stays on the Mosaic service: your machine gets a small connector, and the Mosaic packages inside each Unity project.

Before you start, you need three things:

Unity Hub — unity.com/download. It asks you to create a free Unity account and activate a personal licence; both are free and take a couple of minutes.
A Unity Editor, version 6000.3 or newer — in Hub: Installs, Install Editor. Any 6000.3 or 6000.4 release works.
Git — git-scm.com, accept every default. Unity uses it to fetch the Mosaic Bridge package. Check with git --version. On Windows, if that says "not recognised", close the window and open a new one: Windows only notices new programs in new windows. On macOS the same command may offer to install Apple's command line tools, which is a two-minute download and the right thing to accept.
A Unity project — in Hub: New project, any template. Or open one you already have. Mosaic connects to a project, so there has to be one.

Your access code. One code identifies you to Mosaic: it authorises the Editor connection, the package downloads and your Claude client. If you do not have one, request access at mosaicxr.ai, or ask whoever set up your Mosaic service. Treat it like a password, and tell whoever issued it if it leaks so it can be replaced; it is stored on this machine in connector.json beside the connector.

Once for this machine

Windows portableone file, nothing to install

Save it
Save the file somewhere you can find, for example your Downloads folder. Run the commands below from that folder, using .\mosaic-connector.exe exactly as written.
Configure it
Opening PowerShell in the right folder: open that folder in File Explorer, click the address bar, type powershell, and press Enter. Windows may warn that it protected your PC when you first run the file: click More info, then Run anyway.

Then:
```
.\mosaic-connector.exe setup
```
Service address: wss://cloud.mosaicxr.ai/tunnel · Access code: the one you were given. It then lists the Unity projects it can see and offers to set up the ones you choose: it adds the Mosaic Bridge package and, if your access code includes them, Mosaic Pro Core and Mosaic Pro Education from the Mosaic package registry. A project that has never been opened in Unity Hub will not appear; add it by path instead:
```
.\mosaic-connector.exe add C:\Users\you\Projects\MyGame
```
Connect your Claude
You need one of Claude's clients. Claude Code is a free-standing tool, installed from claude.com/claude-code; claude.ai supports custom connectors on its paid plans. Either works.

Claude Code (the --scope user matters: without it the connection exists only in the folder you happen to be in):
```
claude mcp add --scope user --transport http mosaic https://cloud.mosaicxr.ai/mcp --header "Authorization: Bearer YOUR-ACCESS-CODE"
```
claude.ai: Settings, Connectors, Add custom connector, and paste https://cloud.mosaicxr.ai/mcp. Claude opens the Mosaic sign-in page; paste the same access code there.

Once for each Unity project

Open the project in Unity
Unity fetches and imports the Mosaic Bridge package. Wait for the Console to settle; a Mosaic menu appears when it is done.

Every session

Start the connector, and leave it running
Open the Unity project, then in a PowerShell window:
```
.\mosaic-connector.exe run
```
It prints connector ready with your Unity version. Keep this window open while you work; closing it disconnects Claude from the Editor.

Then ask your Claude: is my Unity Editor connected?

Once for this machine

macOS installermacOS 12 or newer

Install it
Open the downloaded package. If macOS refuses because the developer is not identified, open System Settings, Privacy & Security, scroll down, and choose Open Anyway. On older macOS the equivalent is right-clicking the file and choosing Open.
Configure it
Opening Terminal in the right folder: open Terminal, type cd followed by a space, drag the folder onto the window, and press Enter. If a Terminal window was already open before you installed, open a new one, or it will not find the command.

Then:
```
mosaic-connector setup
```
Service address: wss://cloud.mosaicxr.ai/tunnel · Access code: the one you were given. It then lists the Unity projects it can see and offers to set up the ones you choose: it adds the Mosaic Bridge package and, if your access code includes them, Mosaic Pro Core and Mosaic Pro Education from the Mosaic package registry. A project that has never been opened in Unity Hub will not appear; add it by path instead:
```
mosaic-connector add ~/Projects/Unity/MyGame
```
Connect your Claude
You need one of Claude's clients. Claude Code is a free-standing tool, installed from claude.com/claude-code; claude.ai supports custom connectors on its paid plans. Either works.

Claude Code (the --scope user matters: without it the connection exists only in the folder you happen to be in):
```
claude mcp add --scope user --transport http mosaic https://cloud.mosaicxr.ai/mcp --header "Authorization: Bearer YOUR-ACCESS-CODE"
```
claude.ai: Settings, Connectors, Add custom connector, and paste https://cloud.mosaicxr.ai/mcp. Claude opens the Mosaic sign-in page; paste the same access code there.

Once for each Unity project

Open the project in Unity
Unity fetches and imports the Mosaic Bridge package. Wait for the Console to settle; a Mosaic menu appears when it is done.

Every session

Start the connector, and leave it running
Open the Unity project, then in Terminal:
```
mosaic-connector run
```
It prints connector ready with your Unity version. Keep this window open while you work; closing it disconnects Claude from the Editor.

Then ask your Claude: is my Unity Editor connected?

Your first five minutes

Ask your Claude these, in order. The last one is the moment it becomes real.

is my Unity Editor connected?
list my courses
run the gates on one of them
create a cube called Hello in my Unity Editor

When something goes wrong

What you see	What to do
`git --version` is not recognised	Install Git, then open a new terminal window.
"Windows protected your PC"	Click More info, then Run anyway. The file is new, not unsafe.
macOS: "unidentified developer"	System Settings, Privacy & Security, scroll down, Open Anyway.
My Unity project is not in the list	It has never been opened in Unity Hub. Type its full path at the same prompt.
Unity cannot resolve the Mosaic packages	Git is missing, the machine cannot reach the network, or your access code does not include Pro. Fix that and reopen the project.
Claude says the Editor is not connected	The connector window is closed. Start it again and leave it open.
Claude has no Mosaic tools	The `claude mcp add` command was run without `--scope user`. Run it again with the flag.
Two Mosaic servers in Claude, one broken	This page's setup and the one-machine setup are both configured. Remove the one you are not using.

Working entirely on one machine? If Unity and Claude run on the same computer and you do not need courses, gates or Mosaic Pro, there is a simpler setup that skips the connector and the access code: install Node 18 or newer, then run

claude mcp add --scope user mosaic-bridge-local -- npx -y @mosaicxr-ai/mcp-server --project-path "C:\Users\you\Projects\MyGame"

. That is a different arrangement from the one on this page, and the two should not both be configured: you would get two Mosaic servers in Claude and only one would work.

Why the project step is separate. Unity keeps its dependencies inside each project, so the Bridge package is added per project, while the connector is installed once for the machine.