# Getting started

Connect Unreal MCP for the first time, sign in to ai-game.dev, hook up your AI client and run your first AI prompts in the Unreal Editor.

_Last updated: 2026-11-04_

This page takes you from an installed plugin to your first AI-driven change in the Unreal Editor. It assumes you have finished [Installation](https://ai-game.dev/docs/wiki/unreal/installation).

## Step 1: open the AI Game Developer window

1. Open your project in the Unreal Editor (from the app with **Open Editor**, with `unreal-mcp-cli open ./YourProject`, or as you normally do).
2. Open the **Tools** menu and choose **AI Game Developer**.

The window is the home of the plugin. From top to bottom it shows the log level, a button to open the log folder and the plugin version; the **Connection** section; the **AI agent** section; the **Extensions** section; and links for help and bug reports.

## Step 2: connect to the server

The **Connection** section has a **Custom / Cloud** switch. **Cloud** is the default and the right choice for most people: it uses the hosted server at ai-game.dev, so there is nothing to run locally.

1. Make sure **Cloud** is selected.
2. Click **Authorize**. The window shows a verification link and a short user code.
3. Open the link (or use **Open verification page**), sign in to ai-game.dev, enter the code and approve.
4. The window reports **Authorized — signed in to AI Game Dev.**

If you already signed in with `unreal-mcp-cli login` or the AI Game Dev app on this machine, the editor can reuse that sign-in. After the first approval, later editor launches reconnect without any clicks.

Watch the status line. **Unreal: Connected** with a green dot means the plugin, the bridge and the server are linked. **Unreal: Connecting…** is normal for a few seconds while the bridge starts.

**Note:** Want to keep everything on your own machine? Choose **Custom** instead and run a local `gamedev-mcp-server`. [Connecting AI clients](https://ai-game.dev/docs/wiki/unreal/connecting-ai-clients#custom) explains how.

## Step 3: connect your AI client

The **AI agent** section configures AI clients for you.

1. Pick your agent from the dropdown, for example Claude Code, Cursor, Visual Studio Code (Copilot), Codex or Gemini.
2. Click **Configure**. The plugin writes an Unreal MCP entry into that agent's MCP config file.
3. Restart or reload the agent if it was already running, so it picks up the new server.

From a terminal you can do the same with the CLI. For Claude Code:

```bash
unreal-mcp-cli setup-mcp claude-code --path ./YourProject
```

This writes `.mcp.json` in the project folder. Run `unreal-mcp-cli setup-mcp --list` to see every supported agent and where its config lives. All options are on [Connecting AI clients](https://ai-game.dev/docs/wiki/unreal/connecting-ai-clients).

When the agent connects, it appears in the **AI agents** row of the Connection section.

## Step 4: check the connection

Ask your agent a question that only the editor can answer:

```text
List the actors in the current level with their class names.
```

The agent should call `rql-query` and answer with the real actors of your open level. If it says it has no Unreal tools, the client did not load the MCP server; see [Troubleshooting](https://ai-game.dev/docs/wiki/unreal/troubleshooting#agent-no-tools).

## Step 5: your first real prompts

Start small and concrete. A few prompts that show different tool families:

```text
Spawn three cubes in a row and a point light above them.
```

```text
Create a new Actor Blueprint called BP_Coin with a static mesh component
using the engine sphere, compile it, and place three of them in the level.
```

```text
Take a screenshot of the viewport and tell me what you see.
```

```text
Create a C++ actor class called AHealthPickup with a float Heal property,
then compile the project and fix any errors.
```

Every editor change made through RQL is one undo step, so **Ctrl+Z** in the editor reverts it. Compile tools return structured error lists, so "compile it and fix any errors" is a good follow-up prompt.

**Tip:** Screenshot tools need a real, GPU-backed editor. They return an error when the editor runs with `-nullrhi`.

## Good habits for AI in Unreal Editor

- **Name things.** "Change the intensity of the light labeled KeyLight" works better than "change the light".
- **Ask it to look first.** "Show me the components of BP\_Door before you change it" gives the agent the facts it needs.
- **Let it verify.** Ask for a screenshot or a compile after a change.
- **Save your work.** Ask the agent to save the level, or save in the editor, before larger changes.
- **Keep sessions focused.** One task per conversation keeps the agent's context small and accurate.

More advice lives in the [Unreal best practices](https://ai-game.dev/docs/best-practices/unreal).

## Next steps

- See everything the agent can do on [Tools](https://ai-game.dev/docs/wiki/unreal/tools).
- Add Niagara, PCG, Enhanced Input and more with [Extensions](https://ai-game.dev/docs/wiki/unreal/extensions).
- Fine-tune visibility, timeouts and logging on [Configuration](https://ai-game.dev/docs/wiki/unreal/configuration).
- Drive the editor from scripts with the [CLI reference](https://ai-game.dev/docs/wiki/unreal/cli).

---

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