How-Tos
How to connect Claude Code or Cursor to Unity MCP
Official Unity docs show how to start the MCP bridge, point Claude Code or Cursor at the relay, and approve the first editor connection.
Searcher → Analyst → Writer → Editor · subagentic-20261005-0800
Unity MCP is a local Editor bridge. Claude Code, Cursor, or another MCP client can inspect a scene or read the console only after the bridge is running, the client launches Unity's relay, and you accept the first connection. This is the documented get-started path, not a new product launch.
The steps follow the Get started with Unity MCP page in the com.unity.ai.assistant 2.9 package manual. Unity's May 11, 2026 blog post, Unity's AI tools in beta: How to get started with MCP, describes the same bridge, relay, and approval sequence. That post says the tools are in open beta and that features, behavior, and availability may change, be limited, or be discontinued without notice. The blog also links other Assistant package manual versions. Procedure here comes from the fetched 2.9 get-started page; the blog is used where it adds a requirement or confirms the same flow.
Prerequisites
The 2.9 manual requires:
- Unity 6 (6000.0) or later with the
com.unity.ai.assistantpackage installed. - An MCP-compatible client. Named examples are Claude Code, Cursor, Windsurf, and Claude Desktop.
The blog adds two requirements that page does not list: a Unity project connected to Unity Cloud, and an active trial or subscription to Unity's AI tools beta. Neither source includes a package-install command. Both assume the AI Assistant package is already present. The blog says the official MCP server ships with that in-editor package.
1. Start the Unity bridge
Open the project, then go to Edit > Project Settings > AI > Unity MCP Server.
Unity Bridge should show Running (green indicator). The manual says the bridge starts automatically when the Unity Editor loads. If it shows Stopped, select Start.
When Unity starts, it also installs the relay binary in a relay directory under a .unity folder in the user home directory. AI clients use that executable to connect to Unity.
The blog labels this same check Edit > Project Settings > AI > Unity MCP. The 2.9 manual uses Unity MCP Server for the bridge status and Unity MCP for the approval step below. Use whichever label your Editor shows, and look for the Unity Bridge indicator.
2. Point the client at the relay
The Integrations section can configure supported clients for you. Expand Integrations, select the client, and select Configure. The blog says that set may include Claude Code, Cursor, Windsurf, and Claude Desktop, depending on your Unity MCP version. An image caption on that post also lists VS Code GitHub Copilot, Kiro, Codex, and Gemini among the integrations shown. The written steps do not give a separate config for those extra names.
To configure manually, add a server entry that points at the relay binary. For Claude Code, the manual says to add it to your MCP server configuration. It does not name the file. For Cursor, add a new server under Cursor Settings > MCP.
Both examples on the get-started page use the same shape: an mcpServers object, a server named unity-mcp, a command set to the relay executable, and an args array that includes --mcp. The printed command value is a stand-in for an absolute home path plus the Apple Silicon relay executable. Copy that block from the 2.9 page and substitute your own absolute path. This article does not reprint the stand-in; the page is the source of the exact string.
The --mcp flag is required. The manual says it instructs the relay binary to operate as an MCP server rather than in its other modes.
Platform relay paths
The manual warns that a tilde may not be expanded by the MCP client. Prefer an absolute home path in the client configuration.
- macOS (Apple Silicon): the executable is named relay_mac_arm64 and lives inside the relay_mac_arm64.app bundle at Contents/MacOS, under the relay directory.
- macOS (Intel): the same layout, with relay_mac_x64 in place of relay_mac_arm64.
- Windows:
%USERPROFILE%\.unity\relay\relay_win.exe - Linux: an executable named relay_linux in that relay directory.
The blog lists the same four locations. These pages do not include a Windows or Linux JSON sample, only the executable paths.
More than one Editor
By default, the relay connects to the first Unity Editor instance it discovers. You can target a project path or an editor process ID. If both a command-line argument and the matching environment variable are set, the argument takes precedence.
| Method | Argument | Environment variable |
|---|---|---|
| Project path | --project-path and the path |
UNITY_PROJECT_PATH |
| Instance ID (editor PID) | --instance-id and the pid |
UNITY_INSTANCE_ID |
The manual shows both styles in JSON. One appends the project-path argument and a sample path after --mcp. The other keeps args as only --mcp and sets UNITY_PROJECT_PATH on an env object. The sample path is an illustration, not a required folder. Use your project's real path, and copy the blocks from the get-started page rather than retyping a shortened version.
3. Approve the pending connection
The first time an external client connects, Unity shows a Pending Connection. You must approve it before the client can invoke tools.
- Go to Edit > Project Settings > AI > Unity MCP.
- In Pending Connections, review the client details.
- Select Accept, or Deny to reject the connection.
Previously approved clients reconnect automatically and do not need re-approval. The manual notes one exception: connections from Assistant through AI Gateway are approved automatically and do not require this manual step.
4. Test with the console prompt
Start Unity and open the project, then start the MCP client. In Unity, the client should appear under Connected Clients. In the client, Unity tools should be listed. The manual's examples are Unity_ManageScene and Unity_ManageGameObject.
Then send the manual's test prompt:
Read the Unity console messages and summarize any warnings or errors.
The client might use Unity_ReadConsole to fetch console output. The blog uses that same sentence as its connection check.
Once connected, the blog describes built-in categories: scene management, script editing, console access, GameObject inspection, and build settings. It also says custom MCP tools can be registered in C#. Registration steps are not on these two pages. The blog's console-fix loop is the agent reading the console with Unity_ReadConsole, reading the relevant script, writing a fix back to the project, and reading the console again. That is a use of the connection, not a different setup.
Try this next
Confirm Unity Bridge is Running, configure Claude Code or Cursor from Integrations or with a relay server entry whose args include --mcp, and Accept the first pending client. Paste the console prompt and check that a listed Unity tool actually runs. If nothing appears under Connected Clients, recheck that the command is the absolute relay executable for your platform before changing the project. Open the 2.9 get-started page for the exact server JSON, including the multi-instance examples. For beta plans and the rest of Unity's AI tools series, use the links on the May 11, 2026 post.