# Configuration

Configure Unreal MCP - the AI Game Developer window, MCP Tools visibility, the project config file, .env and every UNREAL_MCP_* environment variable.

_Last updated: 2026-11-04_

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:

```text
<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.json
```

`Saved/` 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:

1. Process environment variables (for example set by `unreal-mcp-cli open` or your shell).
2. A `.env` file in the project root.
3. The config file above.
4. 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](https://ai-game.dev/docs/wiki/unreal/connecting-ai-clients) and extensions on [Extensions](https://ai-game.dev/docs/wiki/unreal/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-list` shows hidden tools (marked hidden) so an agent can find them.
- The choice is saved as `hiddenTools` and 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`:

```bash
unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-server
```

Unreal 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](https://ai-game.dev/docs/wiki/unreal/cli#configure).

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

---

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