Unity MCP: 10 Things You Can Do (And The Deprecation Nobody Mentions)

The pitch for Unity MCP sounds like marketing until you watch it work.

You type "create a cube at the origin and give it a Rigidbody" into Claude Code. The cube appears in your open Editor. Seconds, not minutes.

That is the whole idea. Model Context Protocol gives an AI agent a typed set of tools, and Unity MCP makes those tools reach into a live Editor session.

But there is a catch that most guides published this year have not caught up with. Unity shipped an official in-Editor MCP server, then deprecated it.

If you follow a tutorial from six months ago you will wire up a path Unity is actively moving off. So this covers what works, what moved, and ten things worth doing once it is connected.

What Is Unity MCP?

Unity MCP is an MCP server that exposes the Unity Editor as a set of callable tools. Your agent becomes the client.

Unity describes it plainly in its own docs: MCP "connects large language model (LLM)-based agents, such as Claude Code and Cursor, to the Unity Editor through standardized MCP tools."

New to the protocol itself? Start with what the Model Context Protocol is, then come back.

The architecture matters here because it explains every failure mode you will hit later.

AI client  (Claude Code, Cursor, Codex, Windsurf)
     |
     |  MCP over stdio
     v
Relay / server process  (local, on your machine)
     |
     |  IPC: named pipe on Windows, Unix socket on macOS + Linux
     v
Unity Editor  (bridge + registered tools)

Notice what is missing: a network hop. There is no hosted Unity MCP URL you paste into a client.

The Editor has to be open and running. Close Unity and every tool call fails. That is the single most common support question in every Unity MCP project.

Three Unity MCP Servers, One Deprecated

Search "Unity MCP" and you get three different things wearing the same name. They are not interchangeable.

The migration is not painful. Unity built the CLI replacement on the same protocol, so your agent does not know the difference.

The important detail is licensing. Unity states the CLI is free and separate from Unity AI, and installing it does not require a Unity AI subscription.

If you are on Unity 2022 or an older LTS, the official path is closed to you. Unity CLI needs 6.0 LTS to drive a running Editor. That is why MCP for Unity still has 13,000+ stars.

10 Things You Can Do With Unity MCP

Tool names below are from MCP for Unity v10, which publishes its catalog openly. The official surface covers the same ground under Unity's own naming, such as Unity_ManageScript.

1. Build scenes and GameObjects by describing them

This is the demo everyone leads with, and it is genuinely the fastest win.

manage_scene, manage_gameobject and find_gameobjects let the agent open scenes, spawn objects, set transforms and attach components.

Where it earns its keep is grey-boxing. "Lay out a 3-lane corridor 40 units long with cover blocks every 8 units" is tedious by hand and trivial for a tool loop.

2. Write and patch C# without leaving the chat

manage_script creates and reads scripts. script_apply_edits applies targeted edits instead of rewriting whole files.

That distinction is the difference between usable and infuriating. Whole-file rewrites blow away code the model never read.

Unity's official server exposes a Validation Level setting for its script tool, with basic, standard, comprehensive and strict options. MCP for Unity ships Roslyn validation for the same reason.

Turn validation up. A rejected edit costs you one retry. A silently broken script costs you a domain reload and a confused debugging session.

3. Close the compile-error loop automatically

Here is where Unity MCP stops being a party trick.

read_console returns Editor console output. refresh_unity forces a recompile.

Chain them and the agent gets a feedback loop. Write code, refresh, read the errors, fix, repeat — without you copy-pasting a stack trace.

An agent that cannot read your console is guessing. One that can is debugging.

4. Run Edit Mode and Play Mode tests

run_tests drives the Unity Test Runner and hands results back to the agent.

The Unity CLI covers this outside the Editor too, with unity test writing an NUnit report for CI.

Pair it with rule 3 and you get the full loop: change code, compile, run tests, read failures, iterate. That is the only setup I would trust for anything beyond prototyping.

5. Manage prefabs, materials, shaders and textures

Asset plumbing is where hours quietly disappear.

manage_prefabs, manage_material, manage_shader, manage_texture and manage_asset cover creating, editing and wiring those up.

Bulk operations are the real use case. "Set every material in Assets/Env to the URP Lit shader and point them at the matching normal map" is a script you now do not have to write.

6. Generate placeholder art, models and audio in-Editor

MCP for Unity v10 added generate_image, generate_model and generate_audio, plus import_model and import_model_file.

Treat this as prototyping, not production. Generated meshes are for blocking out a level, not shipping one.

Still, replacing forty grey capsules with something roughly shaped like the thing you mean is a real speedup during a game jam.

7. Wire physics, animation, VFX and UI

The tool surface goes deeper than most people expect.

• manage_physics — colliders, rigidbodies, layer collision settings
• manage_animation — clips and controller state
• manage_vfx — particle and VFX Graph systems
• manage_ui — canvases and UI hierarchies
• manage_probuilder — in-Editor geometry authoring
• manage_components — add, remove and configure any component

These are also the tools most worth disabling when you do not need them. Both servers support tool groups and per-tool toggles, and every unused tool is context you pay for on every request.

8. Profile performance and inspect graphics settings

manage_profiler and manage_graphics expose profiler data and render settings to the agent.

The honest framing: this is triage, not optimisation. An agent reading profiler output can tell you which frame spiked and which system owns it.

Deciding what to do about a 4ms culling cost is still your job.

9. Trigger builds and manage packages

manage_build, manage_packages and manage_editor handle build targets, Package Manager operations and Editor state.

The Unity CLI is stronger here because it works headlessly. unity build runs batch-mode builds with CI-friendly flags, and unity install manages Editor versions.

That is the reason Unity gave for the deprecation. The CLI can target runtime and the Editor; the in-Editor bridge could only ever talk to a window you had open.

10. Register your own tools — and use the escape hatches carefully

This is the one that changes how you use it long term.

Unity's server discovers tools at Editor startup. Decorate a static method and it becomes an MCP tool:

[McpTool("spawn_wave", "Spawn an enemy wave preset into the active scene")]
public static object SpawnWave(WaveParameters parameters)
{
    return new { success = true, spawned = parameters.Count };
}

Unity supports four registration styles: static methods with typed parameters, static methods taking JObject, class-based tools implementing IUnityMcpTool, and runtime registration via McpToolRegistry.RegisterTool.

A tool that encodes your team's conventions beats a generic one every time. The agent stops guessing at your prefab naming scheme because you handed it the rule.

MCP for Unity also ships blunter instruments: execute_menu_item, execute_custom_tool, batch_execute and execute_code.

How to Set Up Unity MCP

Option A: Unity CLI (official, Unity 6.0 LTS+)

Install the CLI, install the pipeline package, point your agent at it. Three commands.

# macOS / Linux
brew install --cask unity-cli
# Windows
winget install Unity.CLI

unity pipeline install
unity mcp configure claude      # or cursor, vscode, windsurf
unity mcp configure --list      # see every supported client

Use in-Editor AI assistant package 2.13 or later if you have it installed, otherwise it fights the CLI for the same connection.

Check it worked with unity status, which prints connected Editors with port, project path and process ID. unity list dumps every registered tool with its parameter schema.

Option B: MCP for Unity (community, 2021.3 LTS+)

Add the package by git URL in Package Manager, then let it configure your clients.

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.1.2

# or via OpenUPM
openupm add com.coplaydev.unity-mcp

Then Window → MCP for Unity → Configure All Detected Clients. It needs Python 3.10+ through uv.

Pin the version tag. Tracking #main on a tool that edits your source files is a choice you will regret exactly once.

Not sure your client config is even valid? Our guide to MCP config files covers the JSON shape for every major client, and the troubleshooting guide covers what to do when it silently fails.

Running more than one Unity project at once

By default the relay grabs the first Editor it finds. With two projects open, that is a coin flip.

Unity's relay takes --project-path or --instance-id, or the UNITY_PROJECT_PATH and UNITY_INSTANCE_ID environment variables. MCP for Unity has set_active_instance.

Unity MCP Security: What Actually Worries Me

Every Unity MCP path runs locally over stdio. That sounds safer than a remote server. It is not automatically safer.

A local stdio server runs as you, with your filesystem and your credentials. There is no sandbox, no scope, no revocable token.

We covered how that goes wrong in the MCP stdio RCE writeup. The short version: a compromised or malicious local server is game over.

Unity does build in a real control. Direct connections from external MCP clients require explicit approval in Project Settings, under Pending Connections.

Approve deliberately. Approved clients are remembered for future sessions, so a careless click persists.

There is one more setting worth knowing: Auto-approve in Batch Mode approves all incoming connections when Unity runs headless. Convenient for CI, dangerous on a shared build machine.

Where Unity MCP Falls Over

I would rather you hit these in this article than at 1am before a milestone.

• Domain reloads break everything mid-call. Recompiling C# tears down the Editor's app domain. A tool call in flight during that dies.
• The Editor must stay open. No open project means no tools. This is not a headless service.
• Undo coverage is uneven. Some operations land in the undo stack. Some do not. Commit before you let an agent loose.
• Large scenes flood context. Asking for a full hierarchy dump on a real production scene will bury your context window.
• Package conflicts are real. There is an open issue where com.unity.ai.assistant on Unity 6.5 livelocks the AssetDatabase so the Editor never opens — and it looks exactly like an MCP failure.

The version control point deserves emphasis. An agent with manage_script and manage_asset can touch dozens of files in one turn.

Work on a branch. Commit before each session. That is the entire mitigation and it takes ten seconds.

Should You Use Unity MCP?

Yes, for prototyping, tooling and test loops. The compile-fix-test cycle alone justifies the setup time.

Not yet as an unsupervised authoring pipeline. Review what it changes, the same as any pull request.

Pick the CLI if you are on Unity 6.0 LTS or later. Pick MCP for Unity if you are on an older LTS or want the wider tool surface today.

And if you are building your own MCP server alongside it — a build-farm server, an asset-pipeline server — test it in the browser first. Catching a broken tool schema before it reaches an agent saves a long debugging session. Our step-by-step testing guide walks through it.

Unity MCP FAQ

The Short Version

Unity MCP hands an AI agent real control over a live Editor: scenes, scripts, assets, the console, tests and builds.

The official in-Editor server is deprecated, and the Unity CLI is the replacement. On older LTS versions, the community MCP for Unity server is still the way in.

Wire up the console and test tools first. That feedback loop is what turns a demo into something you actually keep using.

Sources and Further Reading

• Unity — AI client integration with Unity (MCP)
• Unity — Unity CLI as the replacement for the in-Editor MCP server
• Unity — Unity CLI command reference
• Unity — Register custom MCP tools
• CoplayDev/unity-mcp — MCP for Unity (MIT)
• Model Context Protocol — official documentation