Connecting AI clients
Connect Claude Code, Cursor, Copilot, Codex, Gemini and other MCP clients to Unreal MCP through the ai-game.dev cloud endpoint or a local server.
This page explains how an AI client reaches your Unreal Editor, how sign-in works, and how to write the MCP config for each supported agent. If you only want the quickest path, the Configure button in the editor's AI agent section (see Getting started) does all of this for you.
Cloud or Custom: choose a connection mode
The Connection section of the AI Game Developer window has a Custom / Cloud switch. The same setting is UNREAL_MCP_CONNECTION_MODE (see Configuration).
| Cloud (default) | Custom | |
|---|---|---|
| Server | The hosted endpoint at ai-game.dev | A gamedev-mcp-server you run, usually on localhost |
| Sign-in | Your ai-game.dev account, device-code flow | Optional: none, a shared token, or OAuth |
| What runs locally | The editor and its bridge | The editor, its bridge and the local server |
| Good for | Most users, several machines, working across firewalls | Fully local setups, offline work, CI |
Cloud mode
In Cloud mode the bridge connects to ai-game.dev and your AI client connects to the same endpoint, https://ai-game.dev/mcp. The server routes the client's tool calls to your editor. See the MCP endpoint page for the endpoint itself.
Sign in with the device-code flow
You sign in once per machine. Any of these works, and they share one credential store (~/.ai-game-dev/credentials.json) with the app, the other engine plugins and the CLIs:
- In the editor: choose Cloud, click Authorize, open the verification page, enter the user code shown in the window and approve.
- In a terminal:
unreal-mcp-cli login. - In the AI Game Dev app: sign in as usual.
Warning: Revoke in the editor signs out the whole machine, not just this project. The editor asks for confirmation first, because every AI Game Dev tool that shares the credential (engine plugins, CLIs and the desktop app) is signed out.
How accounts, devices and tokens work is covered on the authentication page.
Project-pinned URLs
If your account has several editors connected, a client using the plain https://ai-game.dev/mcp URL may reach the wrong one. So the plugin and unreal-mcp-cli setup-mcp write a project-pinned URL by default:
https://ai-game.dev/mcp/p/<pin>The pin is derived from the project folder, so the client always routes to this project's editor. Use setup-mcp --no-pin to write the plain URL instead.
Project keys
When the machine is signed in, a Cloud config also carries a project key, an Authorization: Bearer agd_pk_… header bound to this project. With it, the agent needs no sign-in of its own. The key does not expire, can be revoked, and is cached in ~/.ai-game-dev/project-keys.json so every agent of the project reuses it.
setup-mcp --oauthwrites a URL-only config instead; the agent then runs its own OAuth sign-in.setup-mcp --regenerate-key, or the Regenerate key button in the editor's AI agent section, creates a new key, rewrites the configured agents with it and revokes the old one.- An explicit
--tokenwins over both.
If the machine is not signed in, the config is URL-only and the agent signs in itself.
Custom mode: a local server
In Custom mode the bridge connects to a server you control, normally the shared gamedev-mcp-server running on your machine. Each project gets a fixed local port in the range 20000 to 29999, derived from the project path, so the editor and the CLI agree on it without any config.
To run it from the editor:
- Switch the Connection section to Custom.
- In the MCP server card, choose the http transport and click Start. The editor downloads the pinned server release if it is missing, starts it and stops it when the editor exits. The Start button works only with Custom mode and the http transport.
- Choose an Authorization mode: none (local, anonymous), token (a shared secret; New generates one, hold Reveal to see it), or oauth.
To start it from a terminal instead, use unreal-mcp-cli open ./YourProject --start-server --connection-mode Custom, or set UNREAL_MCP_START_SERVER=true with unreal-mcp-cli configure.
Note: If you point a local server at the editor but the window still says Cloud, the bridge connects to ai-game.dev and your local server answers "No connected clients". Set Custom mode explicitly. Passing --host to unreal-mcp-cli open selects Custom automatically.
Write the client config with setup-mcp
unreal-mcp-cli setup-mcp <agent> writes an MCP config entry for one agent. It reads the project's saved connection settings, so open the project in the editor once first (or pass --url).
# Claude Code: writes .mcp.json in the project
unreal-mcp-cli setup-mcp claude-code --path ./YourProject
# Cursor, with the local server over stdio instead of http
unreal-mcp-cli setup-mcp cursor --path ./YourProject --transport stdio
# Print the snippet without writing anything
unreal-mcp-cli setup-mcp vscode-copilot --path ./YourProject --dry-run
# List every agent and its config path
unreal-mcp-cli setup-mcp --listWith --transport stdio the CLI downloads the pinned gamedev-mcp-server release into <project>/Intermediate/UnrealMCP/server/ and the agent starts that server itself.
Supported agents
| Agent | setup-mcp id | Config file |
|---|---|---|
| Claude Code | claude-code | .mcp.json (project) |
| Claude Desktop | claude-desktop | claude_desktop_config.json (user) |
| Cursor | cursor | .cursor/mcp.json (project) |
| Visual Studio Code (Copilot) | vscode-copilot | .vscode/mcp.json (project) |
| Visual Studio (Copilot) | vs-copilot | .vs/mcp.json (project) |
| Rider (Junie) | rider-junie | .junie/mcp/mcp.json (project) |
| GitHub Copilot CLI | github-copilot-cli | ~/.copilot/mcp-config.json (user) |
| Gemini | gemini | .gemini/settings.json (project) |
| Antigravity | antigravity | mcp_config.json under ~/.gemini/ (user) |
| Cline | cline | cline_mcp_settings.json in VS Code's global storage (user) |
| Open Code | open-code | opencode.json (project) |
| Codex | codex | .codex/config.toml (project) |
| Kilo Code | kilo-code | .kilocode/mcp.json (project) |
| Any other MCP client | custom | mcp.json (project) |
The editor's AI agent dropdown offers the same kind of one-click setup, plus Remove to delete the entry, Tutorial and Download / Docs links, and Generate skill files for agents that support skills.
Claude Code and Unreal Engine
Claude Code reads .mcp.json from the folder you start it in. So for Claude Code in Unreal:
- Run
unreal-mcp-cli setup-mcp claude-code --path ./YourProject(or Configure in the editor with Claude Code selected). - Start Claude Code from the project folder.
- Ask it to "list the actors in the current level" to confirm the Unreal tools are available.
Optionally, unreal-mcp-cli setup-skills --path ./YourProject writes a Claude Code skill (.claude/skills/unreal-mcp/SKILL.md) that tells Claude how to drive this project's MCP server.
Other clients
Ready-made config snippets for many clients, including ones not listed above, are on the MCP endpoint page. The ecosystem overview shows how the server, plugins and app work together.