The short answer
- Use the Unity CLI. Install it, run
unity pipeline install in your Unity 6 project, then run unity mcp configure claude-code (or cursor, codex). The CLI is free and doesn't need a Unity AI subscription. - If your agent can run shell commands (Claude Code, Codex and Cursor's agent can), Unity says its direct commands,
unity command and unity eval, are faster and use fewer tokens than MCP. Unity's agent plugin (official install for Claude Code and Codex) teaches the agent those commands plus Unity-authored skills. - Already using the MCP server from the AI Assistant package? That's the deprecated one. Move to
unity mcp; community MCP packages from GitHub aren't affected. - Whichever route you pick: commit first and read the diff. The agent edits your open project.
Only want help writing C#? You don't need MCP for that: open the project folder in Cursor or run Claude Code or OpenAI Codex in it, as in our AI tools for Unity guide. MCP is for the next step, letting the agent work in the running Editor: run tests, inspect the scene, change settings and check its own work.
What changed: the in-Editor MCP server is deprecated
Unity's AI Assistant package (com.unity.ai.assistant) shipped an MCP server that ran inside the Editor, and many early-2026 guides point at it. Its docs page now says: “Unity MCP server is deprecated. Use the Unity command-line interface (CLI) instead.” The replacement is the unity mcp command. It uses the same protocol, so your client connects the same way, but it's built into the unity binary and reaches the Editor through the Unity Pipeline package (com.unity.pipeline), which runs a local server in the Editor that only accepts connections from localhost.
| Your setup | Affected by the deprecation? |
|---|
| AI Assistant package with its MCP server turned on | Yes. Migrate to unity mcp |
| A community MCP package installed from GitHub | No |
unity mcp or unity command from the Unity CLI | No. This is the supported path |
If your project also uses the AI Assistant package, Unity says versions 2.13 and later fix a conflict between it and the CLI, so update it.
What you need
- Unity 6.0 LTS or later to drive a running Editor through the Pipeline package. The CLI itself can install and manage any Editor version.
- The Unity CLI on Windows 10 21H1+, macOS 14+, or Linux with glibc 2.34+ (Ubuntu 22.04+, RHEL 9). The Unity Hub now installs it automatically; you can also install it on its own.
- A Unity account sign-in (
unity auth login opens a browser) before installing the Pipeline package. - The Editor open with your project. With no Editor running, the MCP server starts but has no Editor tools to offer (see what we tested).
The CLI is labelled experimental in Unity's docs. The current beta channel releases are 1.0.0-beta.16 (November 3, 2026) and 1.0.0-beta.17 (November 5, 2026); our own MCP dry-run used 1.0.0-beta.15 (October 29, 2026). Expect changes before 1.0.
Set up the Unity CLI and Pipeline package
- Install the CLI. macOS or Linux:
curl -fsSL https://unity.com/install.sh | bash
Windows (PowerShell):irm https://unity.com/install.ps1 | iex
Check it with unity --version. On Linux it goes to ~/.local/bin/unity. On our Linux test machine on November 1, the plain install command failed with “Failed to fetch version manifest”, because the stable channel's latest.json returned 404. Setting the beta channel worked:curl -fsSL https://unity.com/install.sh | UNITY_CLI_CHANNEL=beta bash
The install script also offers to set up your coding agents; set UNITY_CLI_SKIP_SETUP=1 to skip that. - Open your project in the Unity Editor, then sign in from a terminal:
unity auth login. - Add the Pipeline package: run
unity pipeline install from the project folder, wait for the Editor to recompile, then check with unity pipeline list (look for “Pipeline: Installed”). - Confirm the CLI can reach the Editor:
unity status should list a ready Editor with its port, project path, version and process ID.
Connect Claude Code, Cursor or Codex
The CLI writes the client config for you. Run unity mcp configure --list to see every supported client and where its config lives (our run listed 17, including Claude Desktop, Claude Code, Cursor, VS Code, Copilot CLI, Windsurf, Cline, Codex, Kiro, Antigravity and Zed). Add --dry-run to see the entry before it's written.
Claude Code. Run:
unity mcp configure claude-code
In our dry run this called Claude Code's own command, registering the server at user scope (once per machine, not per project):
claude mcp add --scope user --transport stdio unity-editor-mcp unity mcp
Check it with claude mcp list or /mcp inside Claude Code. If you have several Unity projects open, pin one with --project-path.
Cursor. unity mcp configure cursor writes ~/.cursor/mcp.json; add --local for the project's own .cursor/mcp.json. The entry it wrote in our dry run (with the full path to your unity binary):
{
"mcpServers": {
"unity": {
"command": "/home/you/.local/bin/unity",
"args": ["mcp"]
}
}
}
Codex. unity mcp configure codex adds this to ~/.codex/config.toml:
[mcp_servers.unity]
command = "/home/you/.local/bin/unity"
args = ["mcp"]
It also relaxes Codex's sandbox network policy so the CLI can reach the Editor over localhost, which is why editing the file by hand without that change may leave Codex unable to connect. According to the CLI skill in Unity's agent plugin, the CLI refuses to edit a config.toml it can't safely parse rather than risk corrupting it.
MCP, direct commands or Unity's agent plugin?
| Route | How it works | Best for |
|---|
unity mcp | MCP server; tools come from the connected Editor | Clients that can't run shell commands, or models that don't build command lines reliably (Unity's own reasoning) |
unity command / unity eval | The agent runs CLI commands directly against the Editor | Agents with a terminal. Unity says it's faster and uses fewer tokens than MCP |
| Unity's agent plugin | Skills only, no MCP server; the skills run Unity CLI commands | Claude Code, Codex or Grok users who want Unity-specific know-how (Unity lists these three) |
The plugin lives at Unity-Technologies/unity-agent-plugin. Unity's Codex blog (September 16, 2026) listed 31 skills at launch; the repo had 33 skill directories when we checked on November 1 and again on November 5, 2026. Coverage includes URP post-processing, migrating from Built-in to URP, UI Toolkit/uGUI/IMGUI, sprite atlases, 2D pixel-perfect, AI navigation, localization, multiplayer services, web optimization, IAP/LevelPlay and the unity-cli skill itself. It is published by Unity Technologies under the Unity Companion License.
Claude Code
In Claude Code:
/plugin marketplace add Unity-Technologies/unity-agent-plugin
/plugin install unity@unity-agent-plugin
or run unity setup claude. Type /unity: to see the skills. Unity's own notes on the plugin are candid: for simple uGUI work it makes little difference, and on Sonnet 5 it mainly supplies correctness, because the model already builds most features but defaults to older approaches. You can use the plugin and MCP together; unity mcp configure claude-code warns you if a plugin already registers the same server.
OpenAI Codex (official plugin)
Unity's official Codex plugin uses the same marketplace. Per Unity's Codex plugin docs and Unity blog post (September 16, 2026; Unity for Games also highlighted it again in early November 2026):
codex plugin marketplace add Unity-Technologies/unity-agent-plugin
codex plugin add unity@unity-agent-plugin
- Verify: start a new Codex session, type
/unity: so the skills show in the slash menu, or run codex plugin list and confirm unity is installed and enabled. - Update / remove:
codex plugin marketplace upgrade unity-agent-plugin / codex plugin remove unity@unity-agent-plugin. - Needs Unity 6+. Unity also lists a one-click install from OpenAI's universal plugin directory (on.unity.com/OpenAIPlugin).
- Skills, not MCP. The plugin teaches Codex how Unity jobs are meant to be done; it does not replace
unity mcp configure codex. Use both when you want engine know-how and a live Editor connection.
We haven't installed the Codex plugin hands-on yet; the commands and skill counts above are from Unity's docs, blog and the public GitHub repo. The same plugin family also has install pages for Grok and Google Antigravity under Unity's “plugin for third-party agents” docs.
What we tested
We installed Unity CLI 1.0.0-beta.15 on a Linux machine with no Unity Editor and talked to unity mcp over raw MCP (JSON-RPC on stdio) on November 1, 2026:
- The server starts without an Editor and reports itself as
unity-mcp 1.0.0-beta.15. It offered exactly one tool, unity-cli-status, whose description says no Editor with a reachable Pipeline server was found and lists the three things to check: Editor running with the project open, Pipeline package installed, Pipeline server running. The Editor's own tools only appear once one is connected (the server announces tool-list changes). - With
--cli-tools it added six more, for seven in total: unity-status, unity-editors-list, unity-projects-list, unity-projects-info, unity-releases and unity-doctor. All were marked read-only and non-destructive in their MCP annotations, so clients that honour those hints can run them without extra prompts. - Config writing: the Cursor, Codex and Claude Code entries above are what
--dry-run printed. - Not tested: the Editor-side tools. We had no Unity 6 Editor running, so we can't list what a connected Editor exposes; run
unity list or unity command on your machine to see it.
New in Unity CLI 1.0.0-beta.15 (October 29, 2026)
- Long jobs over MCP: the server adds
job_start, job_status, job_wait and job_cancel, so an agent can start a build or test run and poll it instead of timing out. unity mcp --cli-tools exposes CLI commands as tools. - Project Auditor from the terminal:
unity projects audit --workflow upgrade|optimization|urp|coreclr --report on Unity 6+, which is a useful first job to hand an agent on an old project. - Offline docs cache (
unity docs cache add --api) so an agent can look up the Unity API without the web. - Safer Asset Store imports:
unity assets import --include --require-signed imports only matching files, and only from signed packages. - Unique MCP tool names such as
settings_player_get and script_eval, and more agent setup targets (unity setup qwen, unity setup copilot, unity setup all). - Breaking changes for scripts: JSON listings now use
items, total, nextPage and partial; unity projects new and unity list were removed. Re-check any scripts your agent wrote against earlier betas.
Keep Unity skills current: unity skill sync (beta.16+)
Unity skills (the packages Unity ships for Claude Code, Codex, Grok and other agents) are separate from MCP. MCP exposes live Editor tools; skills teach the agent how Unity jobs are meant to be done and often call the CLI. From 1.0.0-beta.16 (November 3, 2026), the CLI can install or refresh those skills without a prompt:
unity skill sync [client] installs or updates one AI client's Unity skills without prompting, and keeps any copy you edited. With no client it picks the agent that is running it. --hook prints a session-start hook document. An unchanged run downloads nothing.- Daily hint: when an AI agent runs
unity and its Unity skills are older than the CLI's pin, the CLI suggests unity skill sync <client> once a day. Set UNITY_NO_AGENT_HINTS to turn the hint off. - New setup targets:
unity setup vscode (installs VS Code skills and prints Chat: Install Plugin from Source) and unity setup opencode (skills plus ~/.config/opencode/plugins/unity.js, or under $XDG_CONFIG_HOME). unity skill install now supports Google Antigravity (antigravity) and Qwen Code (qwen). unity skill install --all installs into every agent client found on the machine (it does not start each agent's own CLI). - Skills vs MCP (beta.16 change):
unity setup all no longer registers the Unity MCP server for agents that can run shell commands. Those agents are expected to use the unity CLI directly; run unity mcp configure <client> if you still want MCP.
Related Editor/CLI improvements in the same beta.16 notes (also useful for agents): unity command editor dialog / unity command editor dialog answer <id> <button> (needs an Editor version that supports it); unity build --target can build through an already-open Editor; and object-level VCS helpers such as unity vcs summarize --objects and unity vcs guid.
Also in 1.0.0-beta.17 (November 5, 2026)
unity skill install, unity skill refresh and unity setup install the latest published Unity skills even on a machine that has never run the CLI before.- The
unity-cli skill now covers streamed command output and the Antigravity and Qwen skill clients; new-unity-project can upgrade a project to Unity 6000.7 or later with unity projects upgrade. unity skill refresh --format json (or ndjson) reports what happened for each tracked install (refreshed, up-to-date, pruned, skipped, conflict, …).- Security hardening on
unity projects close --force; plugin dependency installs; optional headless Linux Editor via unity install --headless.
We have not installed beta.16 or beta.17 on this box, and we have not run unity skill sync, VS Code/OpenCode setup, dialog commands, open-Editor builds or object-level VCS ourselves. Commands and behaviour above are from Unity's CLI release notes only.
Before Unity's CLI, most people used community packages, and Unity says those aren't affected by the deprecation. The three biggest on GitHub, all actively updated in late October 2026:
We didn't test these. They make sense if you're on an Editor older than Unity 6 (the Pipeline package needs 6.0+) or you rely on a tool they have that Unity's server doesn't. For a new Unity 6 project, Unity's own CLI is the safer default: it's first-party, free, and it's where Unity is putting its agent work.
New: IvanMurzak/Unity-MCP can import Asset Store packs you own (1.11.0, November 11, 2026)
Unity-MCP 1.11.0 (the plugin behind AI Game Developer) adds two Asset Store tools. assetstore-library searches the packs in your Unity account's My Assets (and the local Asset Store cache) and shows which are downloaded or already in the project; assetstore-add takes a product ID, imports the pack and returns the prefab, material and model paths it added. Per a MakeGameWithAI write-up of the developer's demo, you need to be signed in to your Unity account in the Editor, the result can warn about a render-pipeline mismatch (a URP pack in a Built-in project, for example), and Unity 6.6 may pause the import at a package-signature prompt that you have to answer yourself. It only imports packs you already own; it doesn't buy anything.
How to use it safely: commit first, ask the agent to list what it imported before it places anything in a scene, and check the render pipeline. If you import packages with Unity's own CLI instead, add --require-signed (see Safety below). The same release train (Unreal-MCP 0.31.0) gives Unreal a matching Fab family: fab-search, fab-library and fab-add. We haven't run either. Sources: the two GitHub release pages (read November 14, 2026) and the write-up above.
Safety: what the agent can touch
- Commit first and work on a branch. The agent changes scenes, assets and settings in your open project.
- Hide the riskiest tools if you don't need them. Unity's CLI skill shows how:
unity mcp --exclude-tools "exec,script.eval,script.eval_file,test.run", or allow only some with --tools. Put the flags in the args of your client config. - It stays local. Unity says the Pipeline server only accepts connections on localhost and the CLI drives a local Editor offline.
- Keep tool approval on in your client for anything that writes, at least until you trust the workflow.
- Asset Store packages: use
--require-signed when you let an agent import them.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|
The agent only sees unity-cli-status | No Editor reachable | Open the project, run unity pipeline install, then unity status |
| Install script: “Failed to fetch version manifest” | No stable release yet (our Nov 1 test) | Add UNITY_CLI_CHANNEL=beta |
| Two Editors open, wrong project | The CLI picked the other one | Pin it: unity mcp --project-path /path/to/project or configure ... --project-path |
| Codex can't reach the Editor | Sandbox blocks localhost | Use unity mcp configure codex so it updates the network policy |
| Claude Code: “already exists in user config” | It's registered at user scope already | Nothing to do; one entry serves every project |
| Conflicts with the AI Assistant package | Assistant older than 2.13 | Update the AI Assistant package |
What we didn't test
- A connected Unity 6 Editor, so the Editor-side tool list, the job tools and real agent sessions are as Unity documents them.
- Windows and macOS. We ran the CLI on Linux only.
- Unity's agent plugin (Claude Code or Codex) and the community servers in a real project. The Codex install commands and skill counts are from Unity's docs, blog and GitHub only.
- Unity CLI 1.0.0-beta.16 / beta.17 on this box, including
unity skill sync, unity setup vscode / opencode, Editor dialog commands, building through an open Editor, and object-level VCS diffs. Those sections cite Unity's release notes only.
Other engines: the same idea for Godot is in our Godot MCP setup guide (community servers), for Unreal Engine 5.8 and UEFN in Unreal MCP and UEFN MCP setup, and for Roblox in Roblox Studio MCP setup. All four side by side: game engine MCP servers compared.
Related: AI tools for Unity · text-to-3D for Unity and Godot · AI playtesting and QA · Claude Code vs Codex.
Building with agents? Get the VibeStack Weekly digest: new AI game-dev tools and workflows, every Monday.
Sources (MCP and Claude plugin checked November 1, 2026; Codex plugin re-checked November 5, 2026; CLI skill sync / beta.16–beta.17 release notes read November 5, 2026): Unity's docs Unity CLI as the replacement for the in-Editor MCP server, Use the Unity CLI, the Unity CLI reference, Unity Pipeline package and Unity's plugin for Claude Code, Unity's plugin for Codex, Unity's plugin for third-party agents and Unity's blog The Official Unity Plugin for Codex (September 16, 2026); the deprecation note on the AI Assistant package's MCP server page; Unity's Unity CLI release notes (1.0.0-beta.16 November 3, 2026; 1.0.0-beta.17 November 5, 2026); Unity's Unity CLI 1.0.0-beta.16 Discussions post (rediscovery only; November 2026) and Unity CLI 1.0.0-beta.15 Discussions post (October 29, 2026); the Unity-Technologies/unity-agent-plugin repository (33 skill directories on November 5, 2026); the GitHub pages of CoplayDev/unity-mcp, CoderGamester/mcp-unity and IvanMurzak/Unity-MCP; and the MCP docs for Claude Code, Cursor and Codex. The MCP test results are from our own run of Unity CLI 1.0.0-beta.15 on a Linux machine without a Unity Editor (November 1, 2026). We have not installed beta.16 or beta.17 on the box, and we have not run skill sync, VS Code/OpenCode setup, Editor dialog commands, open-Editor builds or object-level VCS diffs ourselves. VibeStack Weekly isn't affiliated with Unity, Anthropic, Anysphere, OpenAI or the community projects, and none of them pays us.
Get the Starter Stack ($12) Get the free weekly digest