Chapter 4 of 15 8 min beginner

Connect Claude Code

Config, transport, first run

Verified against a working setup on 2026-08-10

Claude Code and Claude Desktop are separate apps with separate config files. Setting one up does not set up the other — a surprisingly common source of "it worked yesterday".

Where the config lives

App	Config file	Note
`Claude Code`	`~/.claude.json`	Servers can be global or per-project.
`Claude Desktop (Win)`	`%APPDATA%\Claude\claude_desktop_config.json`	Restart the app fully after editing.
`Claude Desktop (macOS)`	`~/Library/Application Support/Claude/claude_desktop_config.json`	Same file, different home.
`Project-scoped`	`.mcp.json in the repo root`	Shared with your team via git.

The fastest route: the CLI

For Claude Code you do not have to edit JSON by hand. The CLI writes it for you and validates as it goes.

  
bash 
# Official relay
claude mcp add unity-mcp -- "%USERPROFILE%\.unity\relay\relay_win.exe" --mcp

# Community server
claude mcp add unityMCP -- uvx --from mcpforunityserver==10.0.0 mcp-for-unity --transport stdio

# Check what is registered
claude mcp list
 8 lines

Inside a running session, /mcp shows connected servers and their tools. It is the quickest way to see whether a config change actually took effect.

Editing the file directly

If you prefer editing by hand, this is the shape. Note that Claude Desktop nests everything under mcpServers.

  
json 
{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\you\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"],
      "env": {}
    }
  }
}
 9 lines

  
json 
{
  "mcpServers": {
    "unityMCP": {
      "type": "stdio",
      "command": "C:\\Users\\you\\.local\\bin\\uvx.exe",
      "args": [
        "--offline",
        "--from", "mcpforunityserver==10.0.0",
        "mcp-for-unity",
        "--transport", "stdio"
      ],
      "env": {}
    }
  }
}
 15 lines

  
json 
{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\you\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"],
      "env": {}
    }
  },
  "_disabled_unityMCP": {
    "comment": "Community server parked here so it is not running at the same time"
  }
}
 12 lines

Use an absolute path to the executable. A bare uvx depends on the PATH the app inherited at launch, which on Windows is often not the PATH you see in your terminal — the classic "works in my shell, not in the app" failure.

First run

1
Open your Unity project first
The Editor must be running. Both servers talk to a live Editor, not to files on disk.
2
Fully restart the client
Claude Desktop in particular needs a real quit, not just closing the window. MCP servers are launched at startup.
3
Check the tools appeared
Run /mcp in Claude Code, or look for the tools indicator in Desktop. You should see Unity tools listed.
4
Prove the Unity side
Ask for something only your project knows. A generic answer means the chain is broken.
text
Read my Unity console and tell me if there are any errors.
1 lines

Approving tool calls

By default you are asked before each tool runs. That is worth keeping while you learn what the model reaches for — watching which tools it picks teaches you more about MCP than any documentation.

Resist blanket-approving write tools early on. Reading the console is harmless; ManageScene and script edits change your project. Safety and git hygiene covers what to allow and when.

What to take away

Claude Code and Claude Desktop have separate config files.
claude mcp add is faster and safer than editing JSON by hand.
Use absolute executable paths; app PATH differs from terminal PATH.
Restart the client fully — servers launch at startup.
Confirm with a project-specific question, not a green tick.