How to connect coding agents to the Unity MCP server

Unity MCP connects an external coding agent to a running Unity Editor through the Model Context Protocol. The agent does not open the Editor by itself. It starts a relay binary that Unity installs when the Editor loads, and it cannot call tools until you approve that client. This walkthrough follows the Get started with Unity MCP page for the com.unity.ai.assistant package in the 2.9 docs. Unity's May 11, 2026 post, Unity's AI tools in beta: How to get started with MCP, describes the same connection and links Assistant documentation for other package versions. Use the 2.9 page for the bridge check, client setup, first-connection approval, and the console test. Treat the blog as a beta overview, not as the procedure.

Prerequisites

The 2.9 manual lists two requirements:

Unity 6 (6000.0) or later, with the com.unity.ai.assistant package installed.
An MCP-compatible AI client. Named examples are Claude Code, Cursor, Windsurf, and Claude Desktop.

The May blog also lists a project connected to Unity Cloud and an active trial or subscription to Unity's AI tools beta. Its introduction names Github Copilot, and the walkthrough later names VS Code Copilot, among agents you can connect. Those items are not in the 2.9 prerequisites, so they are not steps in this setup. The blog says the AI tools are in open beta and that features, behavior, and availability may change, be limited, or be discontinued without notice. If the manual in your Editor does not match this 2.9 page, follow the manual for the package you installed.

Confirm the bridge is running

Open the Unity project that has the AI Assistant package installed. Go to Edit > Project Settings > AI > Unity MCP Server.

Check that Unity Bridge shows Running (green indicator). The bridge starts automatically when the Unity Editor loads. If the page shows Stopped, select Start.

When Unity starts, it also installs the relay binary in the user home directory, in a relay folder under .unity. AI clients use that executable to connect to Unity.

Configure the client

The Integrations section on the Unity MCP settings page can configure supported clients automatically. Expand Integrations, select your client, and select Configure. The May blog says supported clients may include Claude Code, Cursor, Windsurf, and Claude Desktop, depending on your Unity MCP version.

To configure a client manually, add a server entry that launches the relay. The 2.9 page gives a JSON entry named unity-mcp for Claude Code, and the same entry for Cursor under Cursor Settings > MCP. Copy that block from the manual rather than retyping it. In the basic sample, the command field is the Apple Silicon macOS relay, and args contains only the --mcp flag.

The --mcp flag is required. The manual says it instructs the relay binary to operate as an MCP server, as opposed to its other modes. The same page warns that a leading tilde may not be expanded by the MCP client, which is why the Claude Code and Cursor samples use an absolute home directory in the command field.

Use the executable named in the manual's platform table. Each one lives in the relay folder the Editor installs:

macOS on Apple Silicon: relay_mac_arm64, inside the relay_mac_arm64.app bundle.
macOS on Intel: relay_mac_x64, inside the relay_mac_x64.app bundle.
Windows: relay_win.exe, with the user-profile variable at the front of the path.
Linux: relay_linux.

The finished JSON on the 2.9 page shows only the Apple Silicon command. That page does not include a completed JSON sample for Windows, Linux, Intel macOS, Windsurf, or Claude Desktop. If your client is not in the auto-configure list, the blog says to add a server entry pointing at the relay and to pass the mcp flag.

Target one Editor when several are open

By default, the relay connects to the first Unity Editor instance it discovers. If several Editors are open, you can target a project path or an editor process ID. A command-line argument or an environment variable can carry that target. If both are set, the command-line argument takes precedence.

The manual's table maps a project path to a project-path argument and to UNITY_PROJECT_PATH. It maps instance ID (editor PID) to an instance-id argument and to UNITY_INSTANCE_ID. The page then shows two JSON examples, both on the Apple Silicon relay command. One adds the project-path argument after the --mcp flag. The other keeps only --mcp in args and sets UNITY_PROJECT_PATH in an env object. Both examples use a sample project path, so substitute the path of the project you want to attach to. The manual names the instance-id argument and UNITY_INSTANCE_ID but does not show a completed JSON example for a process ID.

Approve the first connection

When an external MCP client connects for the first time, Unity shows a Pending Connection message. You must approve it before the client can invoke tools.

Go to Edit > Project Settings > AI > Unity MCP.
In the Pending Connections section, review the client details.
Select Accept to approve or Deny to reject the connection.

The menu name is easy to miss. The 2.9 manual uses Unity MCP Server for the bridge check and Unity MCP for approval. The May blog uses Unity MCP when it tells you to check the bridge. Follow the labels in the package manual you have open.

Previously approved clients reconnect automatically and do not need re-approval. Connections from Assistant through AI Gateway are approved automatically and do not require this manual approval.

Test with the console

Start Unity and open your project.
Start your MCP client.
Confirm the client appears under Connected Clients on the Unity MCP settings page, and that the client lists Unity MCP tools. The manual's examples are Unity_ManageScene and Unity_ManageGameObject.

Then run this prompt from the manual:

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

The client might use the Unity_ReadConsole tool to fetch Unity's console output. That prompt is the documented smoke test.

The May blog describes scene management, script editing, console access, GameObject inspection, and build settings, and it says custom MCP tools can be registered in C#. It also describes a console-error loop that starts with Unity_ReadConsole. The 2.9 get-started page does not list those categories or that loop. Do not treat the blog's sample instructions as the tool contract for this page. The get-started page does link onward to an MCP overview, custom tool registration, and bridge troubleshooting.

What to do next

Accept the client under Pending Connections, send the console prompt, and confirm the client is listed under Connected Clients. Copy the Claude Code or Cursor server entry from the 2.9 get-started page instead of assembling a relay command by hand. If Unity Bridge stays Stopped, or the client never appears, use the troubleshooting page linked from that same manual rather than the May 11, 2026 blog.