Unity MCP Complete Guide: Connecting Claude Code, Codex, Gemini, and Cursor to Unity Editor -

Unity AI Mastery Series
Part 1 — Unity AI Assistant Complete Guide: Ask, Plan & Agent Modes
Part 2 — Unity MCP Complete Guide: Connecting Claude Code·Codex·Gemini·Cursor to Unity Editor (this article)
Part 3 — Custom MCP Tools: Giving AI Direct Control of Unity with the [McpTool] Attribute (coming soon)

Opening a Unity project folder in Claude Code or Codex can feel like a real connection — and to be fair, reading and editing C# scripts in that state is perfectly possible. But that’s file system access, not a “conversation” with Unity Editor.

The real conversation between AI and Unity Editor happens through Unity MCP (Model Context Protocol) Server. “List the components on the objects in the current scene,” “find the cause of the errors in the console and fix them” — these requests can’t be answered just by reading files on disk. They require operating the running Unity Editor itself. Unity MCP exposes Unity Editor as an MCP server, letting external AI clients like Claude Code and Codex directly query and manipulate the editor’s internal state. It works safely with Unity AI Assistant 2.7 (Unity 6.0.66f2 or later). That said, Unity AI Assistant is currently in beta. Known issues exist, and behavior may change with each update. Treat it as an exploration tool for now, rather than something to drop straight into a production workflow.

TL;DR
– Reading a Unity project folder and operating Unity Editor are different things. Unity MCP enables the latter — it exposes Unity Editor itself as an MCP server, letting AI directly query and control the running editor state.
– The relay binary (~/.unity/relay/) handles MCP protocol ↔ IPC conversion, with platform-specific paths.
– Claude Code setup: add the relay’s absolute path to the MCP config file → manually approve in Unity.
– AI Gateway lets you run Claude Code directly inside Unity Editor with no separate approval step.
– Unity AI Assistant is currently in beta. Known bugs exist and behavior may change per update; treat it as an exploration tool rather than a production workflow.

Table of Contents
– What Is Unity MCP?
– Two Types of MCP: Completely Opposite Directions
– Architecture: Bridge · Relay · IPC Three Layers
– Claude Code Connection Setup
– Cursor Connection Setup
– AI Gateway: Running Claude Code Inside Unity
– Troubleshooting

What Is Unity MCP?

Unity MCP is a system that exposes Unity Editor itself as an MCP server, allowing external AI clients like Claude Code and Codex to directly manipulate scenes, assets, and scripts inside Unity Editor. MCP (Model Context Protocol) is the standard communication protocol between AI clients and servers; Unity plays the role of a server that conforms to this protocol.

This is the opposite direction from “using a Git MCP server inside Unity AI Assistant.” The two are easy to mix up, so let’s clarify them before going further.

Two Types of MCP: Completely Opposite Directions

Unity AI Assistant includes two MCP features that share a similar name but work in completely different ways.

	MCP Client (Assistant MCP Extensions)	Unity MCP Server
Direction	Assistant → External MCP Server	External AI Client → Unity Editor
Unity’s Role	MCP Client	MCP Server
Settings Location	Edit > Project Settings > AI > Assistant MCP Extensions	Edit > Project Settings > AI > Unity MCP Server
Typical Use Case	Controlling Blender from Assistant	Controlling Unity scene objects from Claude Code

This post covers the right column: Unity MCP Server (referred to as Unity MCP). Claude Code or Codex treats Unity as a “Tools Server” and calls the tools it needs to issue commands to Unity Editor.

Architecture: Bridge · Relay · IPC Three Layers

Understanding how AI clients and Unity MCP Server connect and communicate makes both usage and troubleshooting significantly easier.

Relay Layer: stdio ↔ IPC Conversion

AI clients communicate with tool servers via stdio (Standard Input/Output), as per the MCP standard. But the MCP bridge inside Unity Editor uses IPC (Inter-Process Communication). Since these two protocols can’t connect directly, a translator is needed in between.

The Relay binary (~/.unity/relay/) fills this role. The AI client launches the relay process as a child process and sends MCP messages via stdio. The relay converts these to IPC format and forwards them to Unity Editor’s MCP bridge. When Unity starts for the first time, ServerInstaller automatically installs the platform-appropriate relay binary under ~/.unity/relay/.

IPC Layer: Platform-Specific Local Sockets

When Unity Editor starts, the MCP bridge automatically opens a local IPC channel and waits for the relay to connect. The IPC implementation differs by platform:

Platform	IPC Method
Windows	Named Pipe
macOS / Linux	Unix Domain Socket

Since IPC is communication between processes on the same machine, no network configuration is needed. The relay binary and Unity Editor must be running on the same machine.

The connection sequence (Windows)

① Unity Editor starts — The MCP bridge opens a Named Pipe and writes connection info to ~/.unity/mcp/connections/.

# ~/.unity/mcp/connections/bridge-9beba166-74996.json
{
  "connection_type": "named_pipe",
  "connection_path": "\\\\.\\pipe\\unity-mcp-9beba166-74996",
  "project_path": "D:\\Unity\\Projects\\MyGame",
  "editor_pid": 74996
}

② AI client launches relay as a child process — Claude Code starts relay_win.exe at the path specified in the MCP config file’s command field and establishes a stdio channel.

③ Relay reads the bridge file and connects to the Named Pipe — The relay scans ~/.unity/mcp/connections/bridge-*.json and attempts a Named Pipe connection to the connection_path (\\.\pipe\unity-mcp-9beba166-74996). When Unity Editor accepts this connection request, the IPC channel is established.

④ AI client ↔ Unity Editor communication begins — Claude Code sends tools/list to the relay via stdio; the relay converts it to IPC and forwards it to the Unity MCP bridge. When the bridge returns the registered tool list, Claude Code is fully connected to Unity Editor.

Bridge Layer: McpToolRegistry

The MCP bridge inside Unity Editor operates around McpToolRegistry. When the package is installed, built-in tools like Unity_ReadConsole and get_components are automatically registered. Custom methods declared with the [McpTool] attribute are registered in the same registry and exposed to AI clients. When AI calls a tool, the bridge finds the target tool in the registry, executes the Unity Editor API, and sends the result back via IPC → relay → MCP.

Connection Approval
– Direct External MCP Client — On first connection, manual approval is required in Project Settings > AI > Unity MCP > Pending Connections. Approved clients reconnect automatically in subsequent sessions.
– AI Gateway — Connects automatically without manual approval.

Tool Discovery and Call Flow

As soon as the AI client connects to the relay, it sends a tools/list request. This request travels through relay → IPC → Unity MCP bridge → McpToolRegistry and returns a list of all registered tools’ names, descriptions, and input schemas. The AI client holds this list as context.

When a user request comes in, the LLM reads each tool’s description field and semantically matches the most appropriate tool. It’s the LLM’s reasoning — not an algorithm — that selects the tool. Once selected, a tools/call request is sent to the relay and processed in order: IPC → bridge → target tool method execution → result returned.

The description field is the routing key. The more concretely you write the description in the [McpTool] attribute, the more likely the LLM will select that tool in the right situation.

Claude Code Connection Setup

Step 1: Verify Package Installation

com.unity.ai.assistant must be installed in Package Manager. Unity AI Assistant works on Unity 6.0.60f1 and later, but that version has a bug where valid packages are incorrectly shown as having invalid signatures. Using Unity 6.0.66f2 or later is recommended. If you plan to use Generators (asset creation tools), Unity 6.3 (6000.3) or later is required, and for the same reason, 6.3.5f2 or later is recommended.

Step 2: Start the Unity MCP Server

Go to Edit > Project Settings > AI > Unity MCP Server. If Status shows Running, you’re ready. If it shows Stopped, click the Start button.

Step 3: Edit the Claude Code Config File

Add the MCP server configuration to one of two files, depending on scope. Create the file if it doesn’t exist.

Scope	File Location	Notes
Project	Project root / `.mcp.json`	Can be git-committed, shared with team; add to .gitignore for personal use
Current user	`~/.claude.json`	Applies to all projects for the current account

The ~/.claude.json path differs by OS:

OS	Path
Windows	`C:\Users\YourName\.claude.json`
macOS	`/Users/YourName/.claude.json`
Linux	`/home/YourName/.claude.json`

Since the relay path is an absolute path that differs per machine, each team member needs to update it to their own path if .mcp.json is committed to git. If you’re using Unity MCP for personal work only, add .mcp.json to .gitignore to avoid breaking other team members’ setups. Alternatively, edit Claude Code’s global config file ~/.claude.json instead. Add the following to whichever file you choose:

Windows:

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"]
    }
  }
}

macOS (Apple Silicon):

{
  "mcpServers": {
    "unity-mcp": {
      "command": "/Users/YourName/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64",
      "args": ["--mcp"]
    }
  }
}

The ~ tilde shorthand may not be expanded by the client, so always use absolute paths. This is the most common cause of setup failures — if Unity MCP Server isn’t working after configuration, the path is the first thing to check.

Platform-Specific Relay Paths

Platform	Relay Executable Path
Windows	`%USERPROFILE%\.unity\relay\relay_win.exe`
macOS (Apple Silicon)	`~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64`
macOS (Intel)	`~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64`
Linux	`~/.unity/relay/relay_linux`

Step 4: Approve the Connection

When Claude Code starts, a New MCP Connection approval window appears in Unity Editor, and the connection request shows up in Project Settings > AI > Unity MCP Server > Pending Connections. Click Accept. Approved clients reconnect automatically in subsequent sessions.

Step 5: Test the Connection

Enter the following prompt in Claude Code to verify that tool calls work correctly:

Read the Unity console messages and summarize any warnings or errors.

If Claude Code and Unity MCP Server are successfully connected, the Unity_ReadConsole tool will be called, bringing Unity console output into the Claude Code CLI.

Cursor Connection Setup

Cursor uses the same MCP config structure as Claude Code. Add the relay binary path in the same format to Cursor’s MCP config file.

{
  "mcpServers": {
    "unity-mcp": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp"]
    }
  }
}

Cursor CLI 2026.02.13 or later is required.

Targeting a Specific Unity Instance

When multiple Unity projects are open simultaneously, use the --project-path argument to target the desired instance.

{
  "mcpServers": {
    "unity": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp", "--project-path", "D:\\MyUnityProject"]
    }
  }
}

Method	Argument	Environment Variable
Project path	`--project-path <path>`	`UNITY_PROJECT_PATH`
Editor PID	`--instance-id <pid>`	`UNITY_INSTANCE_ID`

AI Gateway: Running Claude Code Inside Unity

If you’d rather use Claude Code or Codex directly inside the Unity Assistant window — without running a separate AI client — use AI Gateway. AI Gateway is accessed through the agent selector (K component) and lets you run third-party coding agents from inside Unity Editor.

Connecting via AI Gateway is automatically approved, unlike direct MCP connections. There’s no separate Pending Connections approval step.

Agent	Environment Variable	Version
Claude Code	`ANTHROPIC_API_KEY`	2.1.45 or later
Cursor CLI	—	2026.02.13 or later
Gemini CLI	`GEMINI_API_KEY`	Unity bundled version (not selectable)
Codex CLI	—	Unity bundled version (not selectable)

Claude Code and Cursor must be installed with a specific version. Gemini CLI and Codex CLI use Unity’s bundled version, so version selection is not available.

Claude Code · Cursor Setup

Go to Unity > Settings > Preferences > AI > Gateway
Select the agent from the Agent Type list
If the agent is not installed, use the banner link to install it
Expand Environment Variables and click Add Variable
Claude Code requires ANTHROPIC_API_KEY; Cursor works with installation alone

Gemini CLI Setup

Go to Unity > Settings > Preferences > AI > Gateway
Select Gemini CLI from the Agent Type list
Expand Environment Variables and click Add Variable
Enter variable name GEMINI_API_KEY with your Google AI API key as the value

No separate installation is needed since Gemini CLI uses Unity’s bundled version.

Codex CLI Setup

Codex CLI also uses Unity’s bundled version. Select Codex CLI from the Agent Type list and it’s ready to use without any additional installation.

AI Gateway is a fast entry point for integrating agents inside Unity Editor. Direct MCP connection is an approach that keeps your existing Claude Code or Cursor environment intact while adding only Unity tools.

Troubleshooting

Bridge Won’t Start (Stopped Status)

Symptoms: Project Settings > AI > Unity MCP Server shows Stopped; client can’t connect.

Check in order:
1. Check for compile errors in Unity Console. The bridge won’t start if there are compile errors.
2. Verify that com.unity.ai.assistant is installed in Package Manager.
3. Click the Start button directly in Project Settings > AI > Unity MCP Server.
4. If the above steps don’t resolve it, restart Unity Editor.

Relay Binary Not Found

Symptoms: The file doesn’t exist at the command path specified in the client config.

Cause: The ServerInstaller failed to complete binary installation when Unity Editor started.

Resolution steps:
1. Restart Unity Editor (the installer will re-run).
2. Check for the binary directly in Packages/com.unity.ai.assistant/RelayApp~/.
3. Check Unity Console for any installation-related warnings.
4. Use the Locate Server button in Project Settings > AI > Unity MCP to manually specify the path.

Tools Not Discovered

If a custom tool registered with the [McpTool] attribute isn’t showing up in the client, run through this checklist:

Checklist:
– Verify there are no compile errors in Unity Console.
– Check that the tool method is public static and has the [McpTool] attribute.
– Check that the tool is enabled in Project Settings > AI > Unity MCP > Tools section.
– Enabling Show Debug Logs lets you trace the tool discovery process in the console.

Multiple Unity Editor Instances Running

Symptoms: You run a command, but the response comes from a different project’s Unity Editor.

Cause — the relay’s editor discovery mechanism: When Unity Editor starts, it creates a connection file in ~/.unity/mcp/connections/.

~/.unity/mcp/connections/
  bridge-7ba777b2-65156.json   ← Project A (pid 65156)
  bridge-9beba166-74996.json   ← Project B (pid 74996)
  bridge-cf5129b7-83800.json   ← Project C (pid 83800)

Each file contains the named pipe path, project path, and editor PID.

{
  "connection_type": "named_pipe",
  "connection_path": "\\\\.\\pipe\\unity-mcp-9beba166-74996",
  "project_path": "D:\\Unity\\Projects\\MyGame",
  "editor_pid": 74996
}

The relay scans bridge-*.json files in alphabetical order by filename and connects to the Named Pipe of whichever file comes first. That means alphabetical UUID order in the filename — not launch order — determines which editor gets the connection. Since UUIDs are fixed per project, predicting which one connects first isn’t straightforward.

Solution: Explicitly specify the target editor via relay binary arguments or environment variables.

Method	Command-Line Argument	Environment Variable
Project path	`--project-path <path>`	`UNITY_PROJECT_PATH`
Editor PID	`--instance-id <pid>`	`UNITY_INSTANCE_ID`

The PID can be found in the editor_pid field of ~/.unity/mcp/connections/bridge-*.json, or from the trailing number in the filename itself. Command-line arguments take priority over environment variables. In a multi-editor environment, the recommended approach is to keep a separate MCP config file per project and use --project-path to pin each one.

.mcp.json example (using --project-path):

{
  "mcpServers": {
    "unity": {
      "command": "C:\\Users\\YourName\\.unity\\relay\\relay_win.exe",
      "args": ["--mcp", "--project-path", "D:\\MyUnityProject"]
    }
  }
}

Enabling Debug Logs

During troubleshooting, check Show Debug Logs in Project Settings > AI > Unity MCP Server. Connection attempts, tool discovery, command execution traces, and error information will be output to Unity Console.

Wrapping Up

This post is Part 2 of the Unity AI Mastery Series. Part 1 covered how to use Unity AI Assistant inside the editor (Ask, Plan & Agent modes), and this Part 2 covered how to connect external AI clients like Claude Code and Codex through Unity MCP, which the same package provides.

Claude Code reading Unity scenes directly, checking console errors in real time, and manipulating assets — this level of integration would have required wiring together several separate plugins before Unity AI, and even then it wouldn’t have been this clean.

The setup comes down to a single relay binary path. Since this is still beta, behavior can shift with each version update, so it’s worth keeping an eye on the official release notes.

If you’re interested in writing custom MCP tools (using the [McpTool] attribute) or automating workflows through the Skills system, that will be covered in the next post.

Unity MCP Complete Guide: Connecting Claude Code, Codex, Gemini, and Cursor to Unity Editor