Configuration

Every setting the plugin and the server read, with its default.

Tip

Most setups touch a single setting: Enable Native MCP Server for the HTTP route, or UE_PROJECT_PATH for the stdio route. Everything else has a working default.

🧩 Plugin settings In the editor, under Edit › Project Settings › Plugins › MCP Automation Bridge. Saved per project in Config/DefaultGame.ini.

🟩 Environment variables For the stdio server only, set in your MCP client's env block or a .env file.

🚪 MCP_NATIVE_PORT An environment variable for the editor process that overrides the native HTTP port.

On this page · Native MCP · Connection · Security · ini file · Environment variables · Timeouts

Plugin settings

Most connection and security settings are read when the listeners start, so restart the editor after changing them.

📸 The settings page in Unreal Editor 5.8

_{The label and value columns are shown closer together than in the editor. This project has Require Capability Token switched off; it is on by default.}

Native MCP

Setting	ini key	Default	Meaning
Enable Native MCP Server	bEnableNativeMCP	False	Serve MCP over Streamable HTTP at /mcp
Native MCP Port	NativeMCPPort	3000	Must differ from the WebSocket ports. MCP_NATIVE_PORT overrides it at startup.
Load All Tools on Start	bLoadAllToolsOnStart	True	When off, only the core internal tools start enabled; configure can enable the rest.
Server Instructions	NativeMCPInstructions	empty	Text appended to the instructions native clients receive at initialize. Good for project conventions.

Connection (WebSocket bridge)

Setting	ini key	Default	Meaning
Always Listen	bAlwaysListen	True	Start the WebSocket listener with the editor. The stdio route needs it.
Listen Host	ListenHost	127.0.0.1	Bind address for the WebSocket listener and the native HTTP server. Anything but loopback also needs Allow Non Loopback.
Listen Ports	ListenPorts	8090,8091	Comma-separated WebSocket ports. The stdio server dials the first one.
Multi Listen	bMultiListen	True	Open a listener on every port in Listen Ports, not only the first
Heartbeat Timeout Seconds	HeartbeatTimeoutSeconds	10	Drop a WebSocket client that sends no heartbeat for this long. 0 disables the check.
Auto Reconnect Delay	AutoReconnectDelay	5 s	Wait between attempts to bring a failed listener back
Ticker Interval Seconds	TickerIntervalSeconds	0.1	How often the plugin drains its request queue on the game thread
Listen Backlog · Accept Sleep Seconds	ListenBacklog · AcceptSleepSeconds	10 · 0.01	Socket tuning. Leave alone.

Security settings

Setting	ini key	Default	Meaning
Require Capability Token	bRequireCapabilityToken	True	Both routes refuse clients without the token. See 🔐 Security.
Capability Token	CapabilityToken	empty	Your own token. When empty, the plugin generates one in Saved/MCP/capability-token.
Scoped Capability Tokens	ScopedCapabilityTokens	none	Extra tokens with narrower scopes, paths, projects and quotas. See 🔐 Security.
Allow Non Loopback	bAllowNonLoopback	False	Let Listen Host be a LAN address. The native server also refuses to bind off-loopback unless Require Capability Token is on.
Enable TLS · TLS Certificate Path · TLS Private Key Path	bEnableTls · TlsCertificatePath · TlsPrivateKeyPath	off	wss:// for the WebSocket listener, from PEM files. Pair it with MCP_AUTOMATION_USE_TLS=true on the stdio server.
Max Messages Per Minute	MaxMessagesPerMinute	0 (off)	Disconnect a WebSocket client that sends more messages than this per minute
Max Automation Requests Per Minute	MaxAutomationRequestsPerMinute	0 (off)	The same, counting automation requests only
Max Client Requests Per Minute	MaxClientRequestsPerMinute	600	Native HTTP: requests per session per minute, all methods. 0 disables.
Max Client Tool Calls Per Minute	MaxClientToolCallsPerMinute	120	Native HTTP: tool calls per session per minute. 0 disables.

Movie Render Queue and Take Recorder limits

These cap what an automated render or recording may ask for. Raise them only if your renders legitimately need more.

Limit	Default
Resolution	8192 px per side, 33,554,432 px per frame
Length and rate	10,000 frames, 240 fps, 1,000 handle frames per side
Anti-aliasing	64 samples; 256 spatial × temporal
Jobs	8 enabled, 32 in the queue
Render deadline	1 hour, then up to 30 s to cancel
Take Recorder	64 sources per request

Console variables, executor classes, burn-in classes and Take Recorder source classes must also be on their allowlists (under the same Security category).

Editing the ini directly

The same settings in Config/DefaultGame.ini:

[/Script/McpAutomationBridge.McpAutomationBridgeSettings]
bEnableNativeMCP=True
NativeMCPPort=3000
ListenPorts=8090,8091
NativeMCPInstructions=Gameplay Blueprints live under /Game/Core. Widgets are named WBP_*.

Caution

Close the editor before editing the file by hand, or it may write its own values back over yours.

Environment variables (stdio server)

Set these in the client's env block. None is required, but without UE_PROJECT_PATH the server can't find the token or the project's port.

Variable	Default	Meaning
UE_PROJECT_PATH	unset	Project folder or .uproject file. Used to read Saved/MCP/capability-token and the project's Listen Ports.
MCP_AUTOMATION_HOST	127.0.0.1	Editor host. A non-loopback address also needs MCP_AUTOMATION_ALLOW_NON_LOOPBACK=true.
MCP_AUTOMATION_PORT	the project's first Listen Ports entry, else 8090	Editor WebSocket port
MCP_AUTOMATION_CAPABILITY_TOKEN	read from the token file	Token to present. Takes precedence over the file.
LOG_LEVEL	info	debug, info, warn or error. Logs go to stderr.
MCP_ADDITIONAL_PATH_PREFIXES	empty	Extra content roots to allow, comma-separated, e.g. /MyPluginContent/,/ProjectAnimation/. Needed for plugins with their own content mount points.

Advanced variables

Variable	Default	Meaning
MCP_AUTOMATION_ALLOW_NON_LOOPBACK	false	Permit a LAN host. See 🔐 Security.
MCP_AUTOMATION_USE_TLS	false	Connect with wss:// (the plugin must have Enable TLS on)
MCP_CONNECTION_TIMEOUT_MS	5000	Connect and handshake timeout
MCP_REQUEST_TIMEOUT_MS	per capability	One timeout for every request, overriding the per-capability budgets
MCP_AUTOMATION_MAX_MESSAGES_PER_MINUTE	600	Disconnect if the editor sends more messages than this per minute
MCP_AUTOMATION_BRIDGE_ENABLED	true	false never connects to the editor: search and describe still work, execute doesn't
MCP_AUTOMATION_WS_PROTOCOLS	mcp-automation	Extra WebSocket subprotocols to offer, comma-separated
MCP_ENV_FILE	unset	Load this .env file instead of searching for one
MOCK_UNREAL_CONNECTION	false	Testing only: pretend an editor is connected

Aliases, still accepted: MCP_AUTOMATION_WS_HOST and MCP_AUTOMATION_CLIENT_HOST for the host; MCP_AUTOMATION_WS_PORT and MCP_AUTOMATION_CLIENT_PORT for the port; UNREAL_CONNECTION_TIMEOUT for the connection timeout; MCP_AUTOMATION_REQUEST_TIMEOUT_MS for the request timeout; LOGLEVEL for the log level.

.env files

The server loads one .env file at startup, and never overrides a variable that is already set. It looks at, in order:

1. the file named by MCP_ENV_FILE (nothing else is tried when this is set);
2. .env in the package root (the repository folder, for a clone);
3. .env in the current working directory.

MCP_NATIVE_PORT

Set in the environment that starts the editor, it replaces Native MCP Port for that run without editing the project's config. This is how two editors run side by side. An invalid value is ignored, with a warning in the Output Log. Example: 🔌 Connecting Clients.

Timeouts

What	Limit
Connecting to the editor (stdio)	MCP_CONNECTION_TIMEOUT_MS, 5 s
One call, stdio route	A budget from the capability's declared cost: 15 s for cheap reads, 2 minutes for unclassified actions, longer for heavy jobs. Progress reports from the editor extend it, 30 s at a time.
One call, native route	5 minutes. A Movie Render Queue render can wait up to its render deadline.
Ceiling	Either route stops waiting after 5 minutes for a single call, except native renders
Per call (stdio)	options.timeoutMs (1 to 600,000 ms) replaces the capability's budget for that call, still under the ceiling
Every call (stdio)	MCP_REQUEST_TIMEOUT_MS pins every call to one value, still under the ceiling
Your client	Clients have their own limit per tool call. In Claude Code it is MCP_TOOL_TIMEOUT.

Important

When a client or the server stops waiting, the editor keeps working on the request. Read the state again (with inspect or get_summary, for example) before retrying, or retry with the same idempotencyKey so the work can't run twice.

An editor that stops ticking for more than 15 seconds, usually because a modal dialog is open, answers EDITOR_BLOCKED straight away instead of queueing requests behind the dialog.

---

← 📚 Resources and Prompts  ·  🏠 Home  ·  🔐 Security →