Getting started

Connect your first AI agent to the Unity Editor with Unity MCP, check the connection and try your first prompts in Claude Code, Cursor or Copilot.

Updated November 4, 2026 View as Markdown

This page takes you from an installed plugin to an AI agent that changes your Unity scene. It uses the default Cloud connection through ai-game.dev and Claude Code as the example agent; the steps are the same for any other client. If the plugin is not installed yet, start with Installation.

Step 1: open the AI Game Developer window

Open your project in Unity and choose Window > AI Game Developer — MCP (Ctrl+Alt+A, or Cmd+Option+A on macOS). The window's tab is titled Game Developer. You can also click the AI button in the Scene View toolbar.

The window shows the connection as a timeline from top to bottom: Unity, then MCP server, then AI agent. Each point has a status circle. Your goal is to make all three green.

Step 2: sign in (Cloud mode)

The Connection switch at the top has two options, Custom and Cloud. A fresh install uses Cloud.

  1. Click Authorize next to the Cloud Token field.
  2. Your browser opens the ai-game.dev device sign-in page. The window shows a short code ("Code: … — Authorize in browser"). Check that the browser shows the same code and approve it.
  3. The field changes to "Signed in via account", and the Unity status becomes Connected.

The sign-in is stored for the whole machine in ~/.ai-game-dev/credentials.json. If you already signed in with unity-mcp-cli login or the AI Game Dev app, the Editor picks that credential up and you can skip this step. More detail is in Authentication.

Step 3: configure your AI agent

  1. In the AI agent section, pick your client from the dropdown, for example Claude Code.
  2. Under Model Context Protocol (MCP), click Configure. The plugin writes the client's MCP config file (for Claude Code, .mcp.json in the project root) with a URL pinned to this project.
  3. Under Skills, turn on Auto-generate or click Generate. This writes skill files the agent reads to learn how to use Unity MCP and RQL (for Claude Code, into .claude/skills). Agents that support skills work noticeably better with them.
  4. Start your AI client from the project folder, or restart it if it was already running, so it loads the new config.

The same can be done from a terminal:

unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-skills claude-code ./MyUnityProject

setup-skills needs the Editor to be open and connected. Other clients and manual setup are covered in Connecting AI clients.

Step 4: check the connection

  • In the window, the Unity status reads Connected and the AI agent point shows your client as configured.
  • In your AI client, list the MCP servers or tools. In Claude Code, run /mcp; you should see ai-game-developer with tools such as rql-query, rql-mutate, rql-schema, script-execute, screenshot-isolated, tests-run and unity-tool-list.
  • If your client was connected before Unity was ready, reconnect it so it lists the tools again.

From a terminal, unity-mcp-cli status ./MyUnityProject shows whether Unity is running and whether the configured server is reachable.

Step 5: your first prompts

Start with a request that reads the scene, then one that changes it:

Explain my scene hierarchy.
Create 3 spheres stacked on top of each other, then save the scene.
Create a metallic golden material and assign it to a new sphere.

Watch the Hierarchy: objects appear as the agent works. Behind the scenes the agent sends RQL, for example a mutation like this:

editor | call CreateGameObject({name: "Ground", primitive: "Plane"})

Every RQL change is recorded as one Undo step, so Ctrl+Z (Cmd+Z) reverts it like a manual edit.

A longer example that exercises several tools:

Create a new scene called Playground. Add a plane scaled to 10, 1, 10 and a capsule
named Player at 0, 1, 0 with a Rigidbody. Write a PlayerController script that moves
the Player with WASD, attach it, and take a screenshot of the Player.

More ideas to try:

  • "Read the Console and tell me if there are any errors."
  • "Run all EditMode tests and summarize the failures."
  • "List every Rigidbody in the open scenes with its mass."
  • "Start the profiler, record a few seconds of Play mode and report the frame time."

Tips for better results

  • Be specific about names, positions and file paths. The more precise the request, the fewer corrections.
  • Pick a strong model in your client; tool-heavy work benefits from it.
  • In VS Code with Copilot, switch the chat to Agent mode, or tools are not called.
  • Keep the agent's tool list short. Hidden tools still run when called by name, and fewer visible tools leave more context for reasoning. See Configuration.

The Unity best practices page has more prompting advice.

Next steps