Skip to content

Connect an AI Coding Agent to the Unity Editor Without Losing Control

Set up Unity's agent plugin and Unity MCP for Claude Code or Codex with version control, approved clients, read-only first tasks and reviewable scene diffs.

Published

8 min read

Unity's plugin adds Unity-written skills that steer a coding agent such as Claude Code or Codex toward current Unity practice, while Unity MCP lets an agent you approve act inside the open Editor on scenes, assets, scripts and the console. Put the project under version control, start with a read-only task, and allow scene and prefab edits only once you can review each change as a diff.

Both come up when you look for a Unity AI agent setup, but they change different things: a skill changes what the agent knows, and an Editor connection changes what it can do, including saving a scene you never asked it to touch.

The running example is a Unity 6 project with a main menu, one level scene and an enemy prefab with two variants. A null reference error appears whenever the level loads.

/01

What is the difference between Unity's plugin and Unity MCP?

Unity describes its plugin as a set of Unity skills for Claude Code, Codex, Grok and Google Antigravity, covering feature sets such as 2D and tilemaps, UI Toolkit, localization and multiplayer. It is not an Asset Store or Package Manager install; you add it through the agent's own plugin system, and it works with Unity 6.0 or later.

Unity's Claude Code guide is modest about the effect: little difference for simple uGUI work, and, for the model Unity tested, mainly correctness, because that model builds most Unity features without the plugin but defaults to older approaches. The guide also says the plugin ships only skills, not an MCP server. Skills that run Editor commands use the Unity CLI, which needs its own setup and an open Editor.

Unity MCP belongs to the AI Assistant package. The Editor acts as the MCP server: a bridge starts with the Editor, and a relay that your AI client launches exposes tools for scene management, asset operations, script editing and console access. Several clients can connect to one Editor at once.

Unity prints these plugin install commands for the two agents this guide covers:

text
# Claude Code, inside a session started with: claude
/plugin marketplace add Unity-Technologies/unity-agent-plugin
/plugin install unity@unity-agent-plugin

# Codex
codex plugin marketplace add Unity-Technologies/unity-agent-plugin
codex plugin add unity@unity-agent-plugin

/02

Prerequisites: version control, text assets and the right Editor

Commit before connecting anything, and start each session from a clean working tree, so every pending change after a task is the agent's.

Unity's Editor settings, under Edit > Project Settings > Editor, default the Asset Serialization Mode to Force Text, which the manual says helps version control merges. Commit .meta files beside their assets: Unity's metadata page says each holds the asset's unique ID and import settings and must stay with its asset.

Unity MCP needs Unity 6 (6000.0) or later with the com.unity.ai.assistant package. The relay connects to the first Editor instance it finds, so with two projects open, target one with its --project-path option or the UNITY_PROJECT_PATH variable. For client configuration, follow Unity's current setup page, which lists relay paths per operating system.

  • A commit you can return to, and a clean working tree.
  • Force Text serialization and visible meta files, both Unity defaults, with .meta files committed beside their assets.
  • A short written task that names the scenes, prefabs and scripts that may change.

/03

Approve each client and enable only the tools you need

Unity's controls are on the Unity MCP page under Edit > Project Settings > AI, not the MCP Client page, which configures servers for Unity's own Assistant. A new external client appears as a pending connection and cannot invoke tools until you select Accept; deny anything you do not recognize. Approved clients reconnect automatically, so review the Connected Clients and Other Connections lists now and then.

Two exceptions matter. Assistant connections through AI Gateway are approved automatically, and the Auto-approve in Batch Mode setting accepts every client while Unity runs in batch mode. Enable it only where unattended connections are intended.

The same page lists the tools, each with an enable or disable control, and Unity's pages do not state the defaults. For the first sessions, keep console and inspection tools and disable script editing and other tools that write; a tool that manages scenes or GameObjects may both read and change them. The Validation Level for Unity_ManageScript offers basic, standard, comprehensive and strict without describing them, so choose deliberately.

Then add a second layer in the client. Claude Code evaluates permission rules as deny, then ask, then allow, and names an MCP tool as mcp__, the server name, two underscores and the tool name: with the server registered as unity, denying mcp__unity__Unity_ManageScript blocks the script tool, but check the exact names your client shows. OpenAI's documentation gives each Codex server enabled_tools and disabled_tools lists and a default_tools_approval_mode whose writes value prompts for tools not marked read-only.

Two cautions apply. Unity's setup page names Claude Code, Cursor, Windsurf and Claude Desktop, not Codex, so verify a Codex connection yourself. And the MCP specification says clients must treat tool annotations as untrusted unless they come from trusted servers, so a read-only label does not replace checking.

/04

Give the agent a read-only first task

Unity's setup page tests a new connection with a prompt that reads the console and summarizes warnings and errors, possibly through the Unity_ReadConsole tool. Start real work the same way. Enter Play Mode, load the level so the error appears, then ask for a diagnosis that changes nothing.

A good report names the GameObject, component and serialized field, quotes the message and stack trace, and separates what it read from what it guesses. Afterwards, run git status. If a read-only task changed anything, find out which call did it before you continue.

text
Read-only task. Do not create, modify, save or delete anything.
1. Read the Unity console and list each error and warning with its count.
2. For the null reference raised when the level loads, inspect the scene and
   name the GameObject, component and serialized field involved.
3. Propose a fix in words and list every file it would change. Then stop.

/05

Set a checkpoint before every edit

Make the first edit one small change with a named scope. Commit, hand the agent its own plan, and list the files it may touch: here, the enemy prefab variant and one script. Ask it to stop if the fix needs more. One task per commit keeps each change reversible.

The Editor also holds unsaved state: a clean git status does not prove the open scene is unchanged, and an unexpected save can write more than you asked for. Ask the agent to report every save, and keep one writing agent per Editor. Unity MCP accepts several clients, but two agents editing one scene produce a diff nobody can attribute.

/06

Review scene, prefab and .meta changes as text

Start with the list of changed files. You expect the prefab variant and one script; a changed menu scene, ProjectSettings file or new package needs an explanation.

Unity's prefab serialization page explains what a scene diff shows. A prefab instance records its differences from the source prefab in an m_Modifications list; each entry has a target pointing into the source prefab by fileID and guid, a propertyPath, and a value or objectReference. An instance override affects one placement, while a change in the .prefab file reaches every instance and variant that inherits it without overriding that property.

Treat .meta changes as the highest risk. Unity says that when an asset loses its .meta file, references to it break and Unity generates a new one as if the asset were new: materials lose textures, and objects keep an unassigned script component. For branch merges, use Unity's Smart Merge tool, UnityYAMLMerge, which handles scene, prefab and .meta files semantically.

  • Files outside the agreed scope, including ProjectSettings and package manifests.
  • A .meta file deleted, regenerated or carrying a new guid for an asset that already existed.
  • Overrides added to many instances where one prefab change was intended, or the reverse.
bash
git status --short
git diff --stat
git diff -- '*.unity' '*.prefab' '*.meta'

/07

Verify in Play Mode and in a build

A clean console is where verification starts. Enter Play Mode through the normal route, from the main menu into the level, and exercise both enemy variants. Opening the level scene directly can hide problems with initialization order.

Then build and run. Editor-only code, scenes missing from the build and stripped code can all pass in Play Mode and fail in a player. Unity's log files page lists each platform's Player log location, and Web builds write to the browser's JavaScript console. Have the agent compare the Player log with the Editor console, and record the platform and build you tested.

/08

What not to delegate to an Editor agent yet

Some failures appear late or far from the change that caused them. Keep these tasks under direct control until the read, edit and review loop has worked for you several times.

Anthropic's Claude Code documentation also says to verify you trust each server, because servers that fetch external content can expose you to prompt injection. Text in imported packages and third-party logs is data, not instructions.

  • Moving, renaming or deleting many assets, where a lost .meta file breaks references quietly.
  • Unity version, package or render pipeline upgrades that rewrite many files at once.
  • Player settings, signing and store credentials.
  • Unattended runs: Unity notes the agent may ask clarifying questions that block pipelines, and batch-mode auto-approval removes the human check.
  • Anything you cannot verify by playing the game or running a test.

/09

Community Unity MCP bridges

Community projects also connect MCP clients to the Editor. MCP for Unity (CoplayDev/unity-mcp, MIT license) says it is not affiliated with Unity Technologies and lists Unity 2021.3 LTS through 6.x, with a Python requirement. Unity-MCP by Ivan Murzak (Apache-2.0) also describes running inside a compiled game. These are examples, not a ranking; read each current README before installing.

The same rules apply to any bridge. The Unity agents and skills in AI Games Kit are written procedures, such as a project audit, a dependency trace or a move plan that preserves GUIDs; they do not connect to the Editor themselves.

Keep this in mind

Key takeaways

  • Unity's plugin shapes what an agent knows; Unity MCP shapes what it can do in the Editor.
  • Commit to a clean tree and keep Force Text serialization and .meta files versioned before connecting.
  • Accept only clients you recognize, disable unneeded write tools, and add deny rules in the client too.
  • Start with a read-only task, then review scene, prefab and .meta diffs for scope and changed IDs.
  • Verify every fix through the normal Play Mode route and in a real build with its Player log.

Sources & further reading

Consult the source documentation for the version and platform you are working with.