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. Once it is set up, the docs walk through building a course — from a project you already have, or from nothing.

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.
A Unity project — in Hub: New project, any template (3D URP is a good default). Or one you already have. Mosaic connects to a project, so there has to be one. You do not need to open it yet.

Nothing else. Git is not required: every Mosaic package comes from the Mosaic registry as a normal Unity package.

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. It is personal: one code, one person, on up to two of their own machines. A third machine is refused with a message naming the first two, and only one Unity Editor can be connected with it at a time. The code is also tied to your Unity ID: the Editor has to be signed in to Unity as the account the code was issued to, or it cannot be driven (the course tools still work).

Once for this machine

No Windows download published yet. Ask for the file directly.

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 Mosaic Bridge, Mosaic Pro Core and Mosaic Pro Education to the project from the Mosaic registry. A project that has never been opened in Unity Hub will not appear; add it by path instead, now or any time later:
```
.\mosaic-connector.exe add C:\Users\you\Projects\MyGame
```
If you would rather answer everything at once (or are scripting the install), the whole of setup fits on one line:
```
.\mosaic-connector.exe setup --url wss://cloud.mosaicxr.ai/tunnel --token YOUR-ACCESS-CODE --project 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 the three Mosaic packages from the registry and imports them. The first open takes a few minutes; wait for the Console to settle. Package Manager will show Signature: Missing, Scoped Registry and a Pre-release badge on them — all three are normal for a third-party pre-release package and are not errors.

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. If Unity is restarted, the connector reconnects on its own.

Then ask your Claude: is my Unity Editor connected?

Upgrading

Run add again
When a newer Mosaic package is published, close Unity and run the same command you used to add the project. It rewrites the versions and says what moved; Unity picks them up on the next open:
```
.\mosaic-connector.exe add C:\Users\you\Projects\MyGame
```
To see which connector build you have: .\mosaic-connector.exe version. A newer connector is a fresh download from this page.

Once for this machine

No macOS download published yet. Ask for the file directly.

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 Mosaic Bridge, Mosaic Pro Core and Mosaic Pro Education to the project from the Mosaic registry. A project that has never been opened in Unity Hub will not appear; add it by path instead, now or any time later:
```
mosaic-connector add ~/Projects/Unity/MyGame
```
If you would rather answer everything at once (or are scripting the install), the whole of setup fits on one line:
```
mosaic-connector setup --url wss://cloud.mosaicxr.ai/tunnel --token YOUR-ACCESS-CODE --project ~/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 the three Mosaic packages from the registry and imports them. The first open takes a few minutes; wait for the Console to settle. Package Manager will show Signature: Missing, Scoped Registry and a Pre-release badge on them — all three are normal for a third-party pre-release package and are not errors.

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. If Unity is restarted, the connector reconnects on its own.

Then ask your Claude: is my Unity Editor connected?

Upgrading

Run add again
When a newer Mosaic package is published, close Unity and run the same command you used to add the project. It rewrites the versions and says what moved; Unity picks them up on the next open:
```
mosaic-connector add ~/Projects/Unity/MyGame
```
To see which connector build you have: mosaic-connector version. A newer connector is a fresh download from this page.

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
create a cube called Hello in my Unity Editor
take a screenshot of the whole Editor

Then the docs: building a course from the project you have, or from nothing, step by step.

When something goes wrong

What you see	What to do
"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	The machine cannot reach `https://cloud.mosaicxr.ai`, or the access code has been replaced. Run `mosaic-connector setup` again with the current code, then reopen the project.
Package Manager lists Mosaic Pro, but Claude has no education tools	Unity trusted a stale `packages-lock.json` over an empty cache. Close Unity, delete `Library\PackageCache\com.mosaic.` and* `Packages\packages-lock.json`, reopen. Asking Claude is my Unity Editor connected? reports this state and the same fix.
Windows: "EPERM: operation not permitted, rename …PackageCache\.tmp-…"	Unity unpacks a package into a temporary folder and renames it into place; Windows refuses the rename if the virus scanner, or a previous Unity process still closing, is holding a file inside. Click Retry. If it repeats: close Unity, wait ten seconds, delete `Library\PackageCache\.tmp-*`, reopen. To stop it recurring, exclude the project's `Library` folder from Windows Defender real-time scanning (Windows Security, Virus & threat protection, Exclusions) — Unity's own recommendation for every project.
Package Manager shows "Signature: Missing" or "Pre-release"	Normal for a third-party pre-release package. Not an error.
Claude says the Editor is not connected	Either the connector window is closed (start it and leave it open) or Unity is still importing (wait for the Console to settle). The connector reconnects on its own; you never need to restart it for Unity.
A Pro tool says "Mosaic Pro has no licence on this machine"	The licence is a file the connector writes when it connects. Start the connector (`mosaic-connector run`), wait a few seconds, try again. In Unity, Mosaic › Pro Licence shows what it holds. An old connector (before 0.11) never writes it: download again from this page.
"The access code for … expired on …"	The code is right; its date has passed. Leave the connector running: it checks every ten minutes and connects by itself once the code is extended on the service. Nothing to reinstall or retype.
Which connector build do I have?	`mosaic-connector version`. If it does not recognise the command, it is an old build: download again from this page.
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.
Sharing your screen while checking the setup	`claude mcp get mosaic` prints your access code in full, in the clear. Blank the window before you share it, and redact the `Authorization` line before pasting the output anywhere. If it has been seen, ask for a replacement code.

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 Mosaic packages are added per project, while the connector is installed once for the machine. Several projects on one machine are fine; courses file their screenshots under their own name inside each project.

Next: How to use Mosaic — building a course from a project you already have, or from nothing.