# 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.

_Last updated: 2026-11-04_

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](https://ai-game.dev/docs/wiki/unity/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](https://ai-game.dev/docs/auth).

**Note**

You do not need an account to try the plugin. Switch the connection to **Custom** to run a local MCP server on your machine instead. See [Configuration](https://ai-game.dev/docs/wiki/unity/configuration#connection-modes).

## 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:

```bash
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](https://ai-game.dev/docs/wiki/unity/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:

```text
Explain my scene hierarchy.
```

```text
Create 3 spheres stacked on top of each other, then save the scene.
```

```text
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:

```text
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:

```text
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](https://ai-game.dev/docs/wiki/unity/configuration#tools-prompts-resources).

The [Unity best practices](https://ai-game.dev/docs/best-practices/unity) page has more prompting advice.

## Next steps

- [Tools and RQL](https://ai-game.dev/docs/wiki/unity/tools-and-rql): everything the agent can do.
- [Extensions](https://ai-game.dev/docs/wiki/unity/extensions): add Animation, Cinemachine, ProBuilder, Tilemap and other packs.
- [Custom tools](https://ai-game.dev/docs/wiki/unity/custom-tools): expose your own C# methods to the agent.
- Stuck? See [Troubleshooting](https://ai-game.dev/docs/wiki/unity/troubleshooting).

---

Source (HTML): https://ai-game.dev/docs/wiki/unity/getting-started