Configuration
Configure Unreal MCP - the AI Game Developer window, MCP Tools visibility, the project config file, .env and every UNREAL_MCP_* environment variable.
This page lists every setting Unreal MCP has today and where to change it. Most people only touch the connection mode and the AI agent setup; the rest is for tuning, automation and CI.
Where settings live
Unreal MCP has no Project Settings page for the editor connection. Everything is in the AI Game Developer window (Tools menu), and it is saved per project to:
<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.jsonSaved/ is ignored by version control in every Unreal project template, so tokens in this file do not end up in your repository by default.
Settings are read in this order, highest priority first:
- Process environment variables (for example set by
unreal-mcp-cli openor your shell). - A
.envfile in the project root. - The config file above.
- Built-in defaults.
Values that come from the environment or .env override the file for that session but are never written back to it.
The AI Game Developer window
| Section | What you can do |
|---|---|
| Header | Pick the Log Level (Trace, Debug, Info, Warning, Error, Exception, None), open the project's log folder with Open log file, see the plugin Version |
| Connection | Switch Custom / Cloud; in Cloud mode Authorize, Cancel or Revoke; in Custom mode set the Server URL; Connect / Disconnect / Stop; see the status of Unreal, the MCP server and connected AI agents, and the IPC bridge port |
| MCP server (Custom mode) | Start / Stop the local gamedev-mcp-server, choose the Transport (http or stdio) and the Authorization mode (none, token, oauth), generate a token with New |
| AI agent | Pick an agent, then Configure, Reconfigure or Remove its MCP entry; open its Tutorial or Download / Docs; Generate skill files; Regenerate key for the project key |
| Extensions | See installed and available extensions, Refresh catalog, Install or Update, enable or disable an extension live, Compile (Live Coding) |
| Footer | Help / Talk (Discord), Bug Report (GitHub), GitHub Star, and Restart bridge |
Connection details are on Connecting AI clients and extensions on Extensions.
The MCP Tools window: per-tool visibility
Open Tools then MCP Tools. The window lists every registered tool with its title, family and description, a Visible checkbox per tool, and a summary such as "27 / 27 tools visible".
- Visible decides whether a tool is listed to AI agents in
tools/list. Hiding tools you do not need keeps the agent's tool list short and saves tokens. - It is not access control. A hidden tool still runs when a client calls it by name, and
unreal-tool-listshows hidden tools (marked hidden) so an agent can find them. - The choice is saved as
hiddenToolsand survives editor restarts and extension reloads.
To stop a tool from being served at all, use the UNREAL_MCP_TOOLS whitelist below.
Other windows
The Tools menu also has MCP Prompts and MCP Resources windows. In the current release they show an empty-state message; prompts and resources registered by the plugin or extensions still work for AI clients. A Serialization Check window serializes a selected actor or object to JSON so you can inspect what the tools see.
Environment variables
The plugin reads these UNREAL_MCP_* variables from the process environment or the project's .env file:
| Variable | Purpose |
|---|---|
UNREAL_MCP_CONNECTION_MODE | Cloud (default) or Custom |
UNREAL_MCP_HOST | Server URL in Custom mode, for example http://localhost:<port> |
UNREAL_MCP_CLOUD_URL | Cloud base URL; defaults to ai-game.dev |
UNREAL_MCP_TOKEN | Auth token. A secret: never commit it |
UNREAL_MCP_AUTH_OPTION | Custom-mode auth: none, token or oauth (the older value required is read as token) |
UNREAL_MCP_KEEP_CONNECTED | Restore the connection automatically on launch (default true) |
UNREAL_MCP_TOOLS | Whitelist of tools to serve; empty means no filter |
UNREAL_MCP_START_SERVER | true: the editor starts the local server itself (Custom mode, http only) and stops it on exit |
UNREAL_MCP_TRANSPORT | http or stdio |
UNREAL_MCP_LOG_LEVEL | Log verbosity |
UNREAL_MCP_TOOL_TIMEOUT | Maximum time for one tool call, in milliseconds; default 300000 (5 minutes) |
UNREAL_MCP_BRIDGE_PATH | Path to a bridge binary; a developer override that wins over the bundled one |
UNREAL_MCP_SERVER_PATH | Path to a local gamedev-mcp-server; read by unreal-mcp-cli, skips its server download |
Tip: Raise UNREAL_MCP_TOOL_TIMEOUT if long python-execute scripts or big asset imports time out. A tool call that times out before the editor starts it is skipped, not run later.
Write .env with the CLI
unreal-mcp-cli configure writes these values into <project>/.env and adds .env to the project's .gitignore:
unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-serverUnreal project templates ship without a .gitignore, so the command creates one if needed. Pass --no-gitignore to leave it alone. All flags are on the CLI reference.
Warning: Never commit .env. It can contain UNREAL_MCP_TOKEN.
Credentials and keys on disk
| File | Contents |
|---|---|
~/.ai-game-dev/credentials.json | The machine-wide ai-game.dev sign-in, shared with the app, plugins and CLIs |
~/.ai-game-dev/project-keys.json | Cached project keys used in Cloud MCP configs |
<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json | The plugin's per-project settings |
<project>/.env | Optional overrides, never committed |
Ports
- The local MCP server uses a fixed per-project port between 20000 and 29999, computed from the project path. The CLI computes the same number, so no config is needed.
- The plugin and its bridge talk over a loopback port between 30000 and 39999 (the next free one on a collision). The window shows it as "IPC bridge port".
You never need to open these ports to the network; both are local.