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.

Updated November 4, 2026 View as Markdown

This page takes you from an installed plugin to your first AI-driven change in the Unreal Editor. It assumes you have finished 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 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:

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.

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:

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.

Step 5: your first real prompts

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

Spawn three cubes in a row and a point light above them.
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.
Take a screenshot of the viewport and tell me what you see.
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.

Next steps

  • See everything the agent can do on Tools.
  • Add Niagara, PCG, Enhanced Input and more with Extensions.
  • Fine-tune visibility, timeouts and logging on Configuration.
  • Drive the editor from scripts with the CLI reference.