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-level config lives under the ue-mcp: block at the top of ue-mcp.yml, next to your .uproject. The file is meant to be tracked in git so every collaborator sees the same project surface. npx ue-mcp init creates and maintains it for you, but hand-editing is fine — there's nothing in it the server treats as opaque machine state.

ue-mcp:
  version: 1
  contentRoots:
    - /Game/
    - /MyPlugin/
  disable:
    - gas
    - networking
  http:
    enabled: false

tasks: {}
flows: {}
plugins: []

On first load after upgrade, the server detects either legacy file and migrates the contents (project fields → ue-mcp.yml, machine state → ~/.ue-mcp/state.json) automatically, then deletes the legacy file. You don't need to do anything.

ue-mcp: block options

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.

Bridge Connection

The C++ plugin listens on ws://localhost:9877 (currently hardcoded). 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: