Configuration

MCP Client Configuration

The easiest way to configure UE-MCP is to run npx ue-mcp init — it detects your MCP clients and writes the config automatically.

Manual Configuration

{
  "mcpServers": {
    "ue-mcp": {
      "command": "npx",
      "args": ["ue-mcp", "C:/path/to/MyGame.uproject"]
    }
  }
}

Codex uses TOML instead:

[mcp_servers.ue-mcp]
command = "npx"
args = ["ue-mcp", "C:/path/to/MyGame.uproject"]
cwd = "C:/path/to"
enabled = true

Where to Put This

Without a Project Path

You can start the server without a .uproject argument. It will run in a limited mode — you can then use project(action="set_project", projectPath="...") at runtime to attach to a project.

Project Configuration (ue-mcp.yml)

Project config lives in ue-mcp.yml next to your .uproject, tracked in git so every collaborator shares the same surface. npx ue-mcp init scaffolds and maintains it.

ue-mcp:
  version: 1
  contentRoots: [/Game/, /MyPlugin/]
  disable: [gas]
  nativeTools: { enabled: true }
  http: { enabled: false }
  context: { strategy: full }
tasks: {}
flows: {}
plugins: []

The file is one layer in a deep-merged stack (user-global → project → env → local → env vars). For the full anatomy, the layer cascade, where each setting belongs, and every ue-mcp: key, see the dedicated ue-mcp.yml Reference. The behavioral deep-dives for two of its keys live below: Native Epic tools (nativeTools) and Context strategy (context).

Native Epic 5.8 tools

Unreal Engine 5.8 ships an experimental AI Toolset Registry (the plugin behind Unreal's own MCP server). ue-mcp reaches that registry in-process and surfaces every official toolset as first-class actions inside the matching ue-mcp category - Epic's GAS tools appear in gas, Niagara in niagara, and so on - so an agent discovers them in context. Toolsets with no natural home are reachable through the epic gateway (status / list_toolsets / describe_toolset / call_tool).

• On by default. npx ue-mcp init includes a "Native Unreal tools (Epic 5.8)" page where you enable the feature and optionally exclude specific categories. The choice is written to nativeTools in ue-mcp.yml.
• Requires UE 5.8+ with the ToolsetRegistry plugin (and the toolset plugins you want) enabled in your project. On older engines or when the plugin is absent, enrichment is skipped and epic(status) reports available: false.
• Deterministic surface. The catalog is sourced from the live editor when connected, falling back to a per-project cache and then a snapshot baked into the ue-mcp package, so the wrapped tools appear even on a cold first start and match the generated tool reference (both are built from the same snapshot). The 🧩 badge in the tool reference marks every wrapped official tool.

To turn it off entirely, set nativeTools.enabled: false (the epic gateway stays available). To keep it on but drop a noisy domain, add that category to nativeTools.exclude.

The feedback approval mode (interactive / auto-approve / defer) is intentionally not in ue-mcp.yml — it varies per developer and per machine, so it lives in ~/.ue-mcp/state.json and is managed with npx ue-mcp feedback mode ... or the UE_MCP_FEEDBACK_MODE env var. See Feedback → modes.

User-machine state (~/.ue-mcp/)

Machine-specific state that ue-mcp commands write but you wouldn't hand-edit lives under ~/.ue-mcp/:

These files never need to be in your project tree or in version control.

Plugins

The plugins: array in ue-mcp.yml declares npm packages that inject new actions into existing built-in categories. The full author contract lives in Plugins; this is the consumer view.

plugins:
  - name: pie-studio
  - name: some-other-plugin
    version: "0.2.x"        # optional - npm semver range

At server start, ue-mcp resolves each entry against the project's node_modules/, validates the plugin manifest, and merges its injected actions into the host category tools. Stay-on-disk facts:

• The package must already be installed under [project]/node_modules/. Use ue-mcp plugin install [name] to add an entry and run npm install --save in one step.
• Plugins are loaded only when the server boots — edit the array and restart your MCP client (/mcp in Claude Code).
• A plugin that fails validation is skipped with a loud warning. Other plugins keep loading; the host tools are never partially mutated.
• Use the plugins tool to introspect the loaded set:
  • plugins(action="list") — name, version, prefix, status, injected count, host UE plugin presence.
  • plugins(action="describe", name="[package]") — full detail including injected actions, knowledge files, and flows.

Order matters: earlier entries win on inter-plugin action-name collisions. A plugin action can never overwrite a built-in.

Host UE plugin dependencies

A plugin can declare uePluginDependency: [PluginName] in its ue-mcp.plugin.yml. The MCP server checks the project's .uproject for Plugins[].Name == "[PluginName]" and exposes the result as uePluginPresent in plugins(action="list"). The npm side loads regardless — the flag is a signal that the host UE plugin needs to be enabled before the injected actions will actually run.

For example, a plugin that declares uePluginDependency: SomePlugin will report uePluginPresent: false until SomePlugin is added to [Project].uproject's Plugins array and the C++ modules are built.

Context strategy (full, lean, micro)

Everything the server injects at session start - the initialize instructions plus the whole tools/list payload (names, descriptions, and parameter schemas) - is the "context tax". Three strategies trade that seed cost against how many discovery round-trips an agent makes. Measure the tax on your own project with npm run context-tax (set ANTHROPIC_API_KEY for exact token counts).

• full is best when the agent should see the entire surface up front and you are not token-constrained.
• lean keeps action names visible (so the model can often call directly, and unknown actions are still rejected up front) while dropping the prose. A solid middle ground.
• micro mirrors the native MCP toolset gateway (list_toolsets / describe_toolset / call_tool): the agent calls tools(action="list_categories"), then tools(action="describe", category="blueprint"), then tools(action="call", category="blueprint", method="create", args=( ... )). Smallest possible seed, most discovery traffic.

Set the strategy with the standalone command (writes ue-mcp.yml for you):

npx ue-mcp context full      # every action inline (default)
npx ue-mcp context lean      # names visible, descriptions on demand
npx ue-mcp context micro     # one gateway tool fronts everything
npx ue-mcp context           # show the current strategy

npx ue-mcp init also has a Context strategy page. Or edit ue-mcp.yml directly:

ue-mcp:
  context:
    strategy: micro

Or per session, without editing the file: UE_MCP_CONTEXT_STRATEGY=micro (the env var wins over the config value). Anything other than lean or micro resolves to full. Restart your MCP client (/mcp in Claude Code) after changing the strategy.

Bridge Connection

The C++ plugin listens on a per-project WebSocket port derived from a hash of the project root path (in the IANA ephemeral range 49152-65535). Deriving the port from the path means two checkouts of the same project - or several unrelated projects - on one machine each get a stable, launch-order-independent port, so their MCP clients never collide on a single fixed number. The Node client and the C++ bridge compute the identical value independently, and the bridge also publishes the actual bound port to [project]/Saved/UE_MCP_Bridge/port.json as the authoritative source (if the port is already taken, the bridge probes upward and the lockfile records where it really landed). The legacy fixed port 9877 remains the fallback when no project root is known. Pin an explicit port with UE_MCP_PORT or bridge.port in ue-mcp.yml. The MCP server auto-connects on startup and reconnects every 15 seconds if the connection drops.

Connection States

Check the current state with project(action="get_status").

Plugin Deployment

On first run with a project path, the server automatically:

1. Copies plugin/ue_mcp_bridge/ → [Project]/Plugins/UE_MCP_Bridge/
2. Adds UE_MCP_Bridge to the .uproject plugins list
3. Enables PythonScriptPlugin if not already enabled (needed for execute_python escape hatch)

The plugin is editor-only and has no runtime footprint.

Plugin Dependencies

The C++ bridge plugin enables these UE plugins (adding them to .uproject if missing):

• PythonScriptPlugin — for editor(action="execute_python")
• EnhancedInput — for input action/mapping creation
• GameplayAbilities — for GAS tools
• Niagara — for VFX tools
• PCG — for procedural generation tools

CLI Subcommands

npx ue-mcp exposes a few utility subcommands beyond the default MCP server entry:

Editor Lifecycle

The server can manage the editor process: