uefn-agent-bridge MCP server
Commit Nov 13, 2026Provides a local HTTP bridge to control Unreal Editor for Fortnite via Python API, Verse, and Epic's creator toolsets for AI agents and CI/CD.
Also known as Valid/uefn-agent-bridge
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is uefn-agent-bridge MCP?
uefn-agent-bridge provides a local HTTP bridge to control Unreal Editor for Fortnite via Python API, Verse, and Epic's creator toolsets for AI agents and CI/CD.
Summary generated from the project's README
About uefn-agent-bridge MCP server
Automating Unreal Editor for Fortnite from external AI agents or CI/CD pipelines is what uefn-agent-bridge enables. It provides a local HTTP and JSON endpoint that connects to the editor's embedded Python API and Epic's creator toolsets. This allows developers to control the editor from any programming language using a loopback connection, bypassing the limitations and potential slowdowns of the standard MCP implementation.
The bridge operates by prioritizing local execution through the Python API and the Toolset Registry before falling back to MCP. It manages editor state by running one command at a time to prevent duplicate entities or sessions, and it includes specialized handling for long-running tasks like Verse builds or session starts with extended deadlines. Users can monitor editor health through a status command that reports if the editor is busy, stalled, or processing a specific command.
To use this, you must enable Python Editor Scripting and UEFN MCP Toolsets in your project settings. Once configured, you run the bridge via the editor's Python execution tool. It works locally on your machine and requires no external accounts, though it does require the editor to be running to process commands.
What you can do with it
- 1Manage scene actors and assetsAn AI agent can spawn, move, duplicate, or delete actors and manage asset imports and renames.
- 2Automate Verse developmentDevelopers can use the bridge to read, write, search, and build Verse files automatically.
- 3Control play sessions and deploymentsYou can instruct an agent to launch play sessions, start matches, or push changes to the editor.
- 4Configure Creative devices and propertiesThe bridge allows for placing Creative devices and setting their properties or event bindings.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevalid/uefn-agent-bridge is public and reachablegithub.com/valid/uefn-agent-bridge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/valid/uefn-agent-bridge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubUEFN Agent Bridge: control Unreal Editor for Fortnite from AI agents, scripts and CI
Formerly uefn-python-bridge; old links and clones redirect here.
Give your AI agent all of UEFN, not half of it. Epic's MCP is slow, reaches only the Fortnite tools Epic exposes, and by Epic's own notes can stall the editor; UEFN's Python reaches the whole editor, but only from inside it. UEFN Agent Bridge puts both behind one fast local endpoint your agent can call from outside the editor, running Epic's tools in-process instead of over MCP, with the safety rails unattended work needs. Free and open source; join us on Discord.
It is a plain HTTP + JSON server with no dependencies beyond UEFN's embedded Python, so it works from any language. A stdlib-only Python client is included.
What you get that MCP or Python alone don't
- Both halves, one endpoint. The full UEFN Python API plus Epic's Verse, session, device and Scene Graph tools, with friendly names for all 42 UEFN-specific tools plus the widget tools a UMG screen needs, and generic access to every approved creator toolset.
- Faster calls. Commands run as embedded Python on the editor thread and Epic's tools run in-process through the Toolset Registry, skipping MCP's HTTP and discovery overhead. MCP is only the last resort.
- No silent duplicates. One editor command runs at a time, and a call that timed out after it may have started is reported as
outcome_unknownand never replayed on another route, so you check the editor before retrying instead of stacking a second device, entity or session. - Knows when the editor is stuck.
statusanswers instantly, even mid-build, with the running command, the queue and the time since the editor last ticked, so a modal dialog or a hang looks different from a slow build. Add"if_busy": "reject"to fail fast instead of queueing. - Deadlines that fit UEFN. Session start, push and Verse build get up to 10 minutes by default, so long operations stop reporting false timeouts.
- Results instead of log-diving. Every call returns its result to the caller and names the route that handled it; Python that raises fails with its traceback and output; deletes list what they could not delete.
- Keeps running in the background. At start the bridge switches off UEFN's "Use Less CPU when in Background" throttle where the editor allows it (
fix_throttleswitches it off again), so automation does not stall when the editor is not focused. - Undoable edits. Direct actor edits run inside editor transactions, and
batch.execturns many edits into one undo step. - Stays current. The bridge checks for a newer release at startup, and
bridge.updateinstalls it after verifying every file, keeping a backup. Automatic installs are opt-in. - Any language, local only. Plain HTTP + JSON with a stdlib Python client; loopback only, with cross-origin web pages rejected.
What you can automate
| Task | Commands |
|---|---|
| Spawn, move, duplicate, delete and inspect actors | actors.spawn, actors.transform, actors.duplicate, actors.delete, actors.list, actors.properties |
| Find, import, rename and save assets | assets.search, assets.import_task, assets.rename, assets.save |
| Place Creative devices and wire events | devices.place, devices.set_property, devices.add_event_binding, devices.list_classic_options, devices.get_classic_option_values, devices.set_classic_option |
Edit Verse device @editable properties on placed devices |
verse.find_device, verse.get_properties, verse.set_property |
| Read, write, search and build Verse | verse.read_file, verse.write_file, verse.grep, verse.build |
| Launch a play session, start a match, push changes | session.start, session.start_game, session.push_changes, session.status |
| Scene Graph entities and components | entities.create, entities.add_component, entities.set_component_property |
| Material instances, viewport camera, level save | materials.create_instance, viewport.set_camera, level.save |
| Anything else in the editor | exec (run Python), batch.exec (several commands in one undo step), toolsets.call |
Quick Start
Paste this into an AI coding agent:
Clone https://github.com/Valid/uefn-agent-bridge and help me set it up with my UEFN project.
The included RULES.md explains the routing contract and working UEFN Python patterns.
Manual Setup
1. Enable embedded Python
In UEFN Project Settings, enable Python Editor Scripting. This is the only requirement for the existing direct Python commands.
2. Enable Epic's creator toolsets
For the Toolset Registry and MCP capabilities, enable UEFN MCP Toolsets in Project Settings. Apply any restart requested by UEFN.
3. Enable the official MCP server
In Editor Preferences, open General > Model Context Protocol and enable Auto Start Server.
The default endpoint is:
http://127.0.0.1:8000/mcp
The bridge accepts only a loopback MCP endpoint. To use a different loopback port or path, either set UEFN_MCP_URL in UEFN's process environment before running the bridge or configure it at runtime:
{
"command": "mcp.configure",
"params": {"url": "http://127.0.0.1:8123/mcp"}
}
You can also manage Epic's server from the UEFN console with ModelContextProtocol.StartServer [port], ModelContextProtocol.StopServer, and ModelContextProtocol.RefreshTools.
4. Run the bridge
In UEFN, choose Tools > Execute Python Script and select bridge/server.py.
The Output Log should include:
[Bridge 12:34:56] Bridge v0.8.0 listening on http://127.0.0.1:9210
[Bridge 12:34:56] 92 commands registered
The bridge checks ports 9210 through 9220 and uses the first available port.
If it selects a port other than 9210, pass the logged port to
UEFNBridge(port=...) or use that port in raw HTTP requests.
How Routing Works: Python First, Toolsets Next, MCP Last
Every request follows a deterministic route:
| Priority | Response route |
Used for |
|---|---|---|
| 1 | python |
Existing bridge commands for actors, assets, levels, materials, viewport control, and placed Verse-device inspection |
| 2 | toolset_registry |
Epic creator-exposed toolsets called directly inside UEFN, without MCP transport overhead |
| 3 | mcp |
Official loopback UEFN MCP when the requested capability or local registry is unavailable before dispatch |
Named direct commands never detour through MCP. The 71 friendly aliases and toolsets.* commands try the local Toolset Registry first. The mcp.* commands explicitly bypass local routing for diagnostics or compatibility testing.
Fallback is mutation-safe. Once a Toolset Registry or MCP call may have started, a timeout, disconnect, malformed response, or unknown result is returned with "outcome_unknown": true and is not replayed through another route. This prevents duplicate entities, devices, file writes, sessions, or event bindings.
Why hybrid
UEFN's Python API is fast and broad for normal editor automation, but some Fortnite-specific operations are not available through unreal.*. Epic's creator toolsets add Verse-file, play-session, device, and Scene Graph entity capabilities. Calling those toolsets through the in-process registry avoids the fixed HTTP and discovery cost of MCP whenever possible.
Epic currently lists editor slowdowns and hangs during MCP calls as a known issue. Keeping MCP as the final route makes the common path responsive while retaining the capabilities that only Epic's toolsets expose.
Official references:
Sending Commands
Every command is a POST to http://127.0.0.1:9210 with a JSON body:
Requests must use Content-Type: application/json and are limited to 16 MiB.
Browser requests with a non-loopback Origin are rejected, and both bundled
clients bypass environment HTTP proxies for their loopback connections.
{"command": "actors.list"}
{
"command": "actors.spawn",
"params": {
"actor_class": "PointLight",
"location": [0, 0, 200]
}
}
{
"command": "session.status",
"timeout_s": 120
}
The complete response envelope includes the route that actually handled the request:
{
"ok": true,
"route": "toolset_registry",
"result": {}
}
An MCP fallback also includes fallback_reason. Failures whose side effect cannot be determined include outcome_unknown.
Busy, Stalled, and Deadlines
The bridge serves one editor command at a time; other requests wait their turn. status and GET / never wait, and both report what the bridge is doing:
"activity": {
"editor_command": {"command": "verse.build", "state": "waiting_on_tool", "seconds": 41.2},
"dispatch_turn": {"command": "verse.build", "seconds": 41.3},
"waiting": 1,
"editor_tick_age_s": 0.03
}
editor_commandis the command running on the editor thread (stateisrunning,waiting_on_toolwhile a native tool works, oroutlived_callerwhile a native tool keeps working after its caller timed out), anddispatch_turnis the request being served.waitingcounts the requests queued behind it.editor_tick_age_sis the time since the editor last ran the bridge's tick. It grows while the editor's game thread is blocked. A large value witheditor_commandset means a bridge command is slow; witheditor_commandempty, something outside the bridge holds the editor, such as a modal dialog.- Add
"if_busy": "reject"to a request to fail fast instead of queueing. A busy bridge answers HTTP 409 withbusy(the sameactivityobject) and starts nothing. Busy includes editor work whose own caller already timed out. The Python client raisesBridgeBusy. - Without
timeout_s, a request's deadline is 30 seconds, except for tools that routinely take longer:session.start,session.push_changesandverse.buildget 600 seconds,session.stopandsession.start_game180, andsession.stop_game120. The same applies totoolsets.callandmcp.callnaming those tools. The Python client waits at least as long. - While an
execruns,editor_commandalso carriesexec:quiet_s(seconds since its last sign of work),budget_sandeditor_calls.
Late Results and Jobs
A command that outlives its deadline keeps running in the editor, and its result is kept instead of dropped, so you never have to repeat an import or spawn to learn whether it happened:
- A 504 deadline answer carries
job_id. A native tool that outlives its caller (a push, start or build still working) answers withjob_idtoo. - Send
job.resultwith{"job_id": "...", "wait_s": 60}for its state:running(with the currentactivity),done(responseis the full reply the caller would have had),not_started(it was still queued and never ran) orunknown(the bridge stopped, or a native tool went silent).wait_s(up to 60) waits for a running job to end.job.resultanswers at once even while the editor is busy, and withoutjob_idit lists the kept jobs. - Name a job yourself by adding
"job_id"(letters, digits,_ . : -, up to 64) to any request. Its result is then kept however you stop waiting, which helps a caller that gives up before the bridge's own deadline. The Python client sends it withtrack_as=. - Results are kept for an hour after a job ends, at most 50 jobs and 1 MB per result; a bridge reload clears them.
Python Client
from bridge.client import UEFNBridge
ue = UEFNBridge()
print(ue.status())
# Existing capability: direct embedded Python.
actors = ue.actors()
print(ue.last_route) # python
# UEFN-specific capability: local registry first, MCP only on a safe miss.
session = ue.run("session.status", timeout_s=120)
print(ue.last_route) # toolset_registry or mcp
# Generic approved tool lookup and call.
toolsets = ue.toolsets()
schema = ue.describe_toolset("ValkyrieFortniteToolset.SessionToolset")
status = ue.call_tool(
"ValkyrieFortniteToolset.SessionToolset",
"GetSessionStatus",
)
# Force MCP only when diagnosing the official transport.
mcp_status = ue.run("mcp.status", timeout_s=120)
UEFNBridge.run() returns only the result. Use UEFNBridge.request() when you need the complete envelope, or inspect ue.last_response and ue.last_route after a call. UEFNBridge.planned_route(command) explains the initial route without contacting UEFN. A failed command raises BridgeError; its envelope holds the complete failure response (for example an exec traceback with stdout). Pass if_busy="reject" to run() or request() to get BridgeBusy instead of waiting behind another command.
curl
curl -s -X POST http://127.0.0.1:9210 \
-H "Content-Type: application/json" \
-d '{"command":"actors.list"}' | python -m json.tool
curl -s -X POST http://127.0.0.1:9210 \
-H "Content-Type: application/json" \
-d '{"command":"session.status","timeout_s":120}' | python -m json.tool
JavaScript or TypeScript
const response = await fetch("http://127.0.0.1:9210", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ command: "actors.list" })
});
const envelope = await response.json();
console.log(envelope.route, envelope.result);
Direct Python Commands
These commands always use the embedded-Python route.
Actors
| Command | What it does | Key params |
|---|---|---|
actors.list |
List level actors | class_filter |
actors.selected |
List selected actors | None |
actors.spawn |
Spawn from a class or asset | actor_class or asset_path, location, rotation, label |
actors.duplicate |
Clone an actor | source, location, rotation, label |
actors.delete |
Delete actors; reports each target it could not delete under failed |
targets |
actors.transform |
Set location, rotation, or scale | target, location, rotation, scale |
actors.properties |
Read named editable properties | target, properties |
actors.set_property |
Set an editor property | target, property_name, value |
actors.set_color |
Create and apply a persistent solid-color material | target, color |
Locations and scales are [x, y, z]. Rotations are [pitch, yaw, roll] in degrees, or an object such as {"pitch": 0, "yaw": 90, "roll": 0} (the shape responses return), for actors.spawn, actors.duplicate, actors.transform and viewport.set_camera.
Assets
| Command | What it does | Key params |
|---|---|---|
assets.search |
Search spawnable assets by default | query |
assets.list |
List a content directory | directory, recursive |
assets.info |
Inspect one asset | path |
assets.exists |
Check an asset path | path |
assets.rename |
Rename or move an asset | old_path, new_path |
assets.duplicate |
Copy an asset | source, destination |
assets.delete |
Delete an asset | path |
assets.save |
Save an asset | path |
assets.selected |
List Content Browser selection | None |
assets.import_task |
Import an external file | source_file, destination_path |
Placed Verse Devices
| Command | What it does | Key params |
|---|---|---|
verse.find_device |
Find placed Verse device actors | query, class_filter |
verse.export_t3d |
Export complete serialized device state | target, filename |
verse.get_properties |
Read generated subobject properties | path, properties |
verse.set_property |
Write supported generated subobject properties | path, property_name, value, is_object_ref |
These direct verse.* commands inspect placed generated device objects. They are separate from the creator-toolset verse.* file aliases below.
Level, Viewport, Materials, and System
| Command | What it does |
|---|---|
level.info |
Read current level information |
level.save |
Save the current level |
viewport.camera |
Read viewport location and rotation |
viewport.set_camera |
Move the viewport camera |
materials.create_instance |
Create a material instance with parameters |
status |
Return version, routing configuration, commands, and current activity |
exec |
Run embedded Python and return the variable named result. If the code raises, the command fails (ok: false) and still returns result, stdout, stderr and traceback; changes made before the exception stay. A quiet budget stops an endless loop (see below) |
batch.exec |
Run direct Python commands in one undo transaction and main-thread tick |
undo, redo |
Use the editor transaction history |
log, history |
Inspect bridge diagnostics |
job.result |
The kept result of a command that outlived its deadline (Late Results and Jobs above) |
reload, shutdown |
Manage the bridge process |
bridge.check_update |
Check now whether a newer bridge is published |
bridge.update |
Install the published bridge files, verified, then reload (Updates below) |
fix_throttle |
Disable background CPU throttling |
store.install |
Install the persistent helper store |
exec runs on the editor's game thread, so an endless loop would freeze UEFN. A quiet budget stops it instead: once the script's Python has run budget_s seconds (default 120) without a sign of work, the bridge raises ExecInterrupted in it and the command fails with stopped_by_budget. Signs of work reset the clock: any unreal API call returning, any native call of 1 s or more, a print, or keep_alive() (available to the script). Time inside an editor call or a long native call never counts, and the stop never lands while one runs, so a long import, build or save is never cut short. ExecInterrupted is not an Exception, so except Exception does not swallow it. Changes made before the stop stay. Send budget_s up to 86400 for a long pure-Python computation, or 0 to turn the budget off.
batch.exec accepts direct Python commands only. Toolset Registry and MCP calls are asynchronous and serialized, so friendly aliases and all toolsets.* or mcp.* commands are rejected inside a batch.
UEFN-Specific Friendly Aliases
Version 0.3.0 maps all 42 UEFN-specific tools shipped with UEFN v42 to stable bridge command names. Version 0.6.0 adds 29 widgets.* aliases for Widget Blueprints, their Verse fields and view bindings (see "Widget Blueprints and Verse UI" in RULES.md, including a 42.40 bug where a blueprint made by widgets.create_blueprint never reflects its Verse fields). Version 0.7.0 follows UEFN 43.00's toolset renames (see "UEFN 43.00 toolset renames" below) and adds verse.file_tree, session.verse_output and three devices.*classic* aliases. Pass the official tool arguments directly as params.
| Domain | Friendly aliases |
|---|---|
| Python setup | uefn.python_enabled, uefn.enable_python |
| Verse files and build | verse.write_file, verse.replace, verse.read_file, verse.move, verse.list_files, verse.grep, verse.delete, verse.create_directory, verse.copy, verse.file_tree, verse.build |
| Play session | session.stop, session.stop_game, session.start, session.start_game, session.push_changes, session.status, session.game_state, session.client_log, session.verse_output |
| Creative devices | devices.set_property, devices.remove_event_binding, devices.place, devices.list_event_bindings, devices.list_properties, devices.list_assets, devices.get_properties, devices.get_binding_options, devices.add_event_binding, devices.list_classic_options, devices.get_classic_option_values, devices.set_classic_option |
| Scene Graph entities | entities.set_transform, entities.set_component_property, entities.remove_component, entities.list_classes, entities.list_component_properties, entities.list_component_classes, entities.get_transform, entities.get_components, entities.get_component_property, entities.find, entities.delete, entities.create, entities.add_component |
| Widget Blueprints | widgets.list_blueprints, widgets.list_classes, widgets.class_info, widgets.describe, widgets.tree, widgets.named_slots, widgets.create_blueprint, widgets.compile, widgets.add, widgets.remove, widgets.rename, widgets.move, widgets.wrap, widgets.replace_with_template, widgets.set_named_slot_content |
| Widget Verse fields | widgets.verse_field_types, widgets.verse_fields, widgets.add_verse_field, widgets.duplicate_verse_field, widgets.edit_verse_field, widgets.remove_verse_field, widgets.bind_verse_field |
| Widget view bindings (MVVM) | widgets.view_bindings, widgets.view_events, widgets.bindable_properties, widgets.conversion_functions, widgets.create_view_binding, widgets.create_view_event_binding, widgets.remove_view_binding |
UEFN 43.00 toolset renames
UEFN 43.00 (CL 59596594) renamed most of Epic's toolsets. The aliases name the 43.00 toolsets and fall back to the 42.40 names, so they work on either build:
| 42.40 | 43.00 |
|---|---|
ValkyrieToolset.VerseToolset |
VerseToolset.VerseToolset (adds FileTree) |
ValkyrieToolset.SessionToolset |
ValkyrieFortniteToolset.SessionToolset (adds GetVerseOutput) |
ValkyrieToolset.DeviceToolset |
ValkyrieFortniteToolset.DeviceToolset (adds three classic-device option tools) |
EditorToolset.LogsToolset |
ConsoleToolset.LogsToolset |
ValkyriePythonToolset.IsPythonEnabledInUEFN, EnablePythonInUEFN |
IsPythonReadyForMainProject, EnablePythonForMainProject |
editor_toolset.toolsets.* (snake_case tools) |
EditorToolset.* (PascalCase tools; SceneTools became LevelToolset) |
A toolsets.call that names a renamed Verse, Session, Device, Logs or Python tool by either build's name runs the one the running editor exposes, locally or through MCP. The editor_toolset.toolsets.* tools changed names and argument shapes, so call those by the running build's exact name. widgets.describe (GetWidgetDescription) exists only on 42.40.
Use toolsets.describe before the first unfamiliar call. Epic's JSON schema is the source of truth for parameter names, required fields, object reference shapes, and result values. When a schema requests an Unreal object reference, it commonly uses a JSON object such as {"refPath":"/Path/To/Object"}. Do not substitute that shape where a tool expects a plain string.
uefn-agent-bridge MCP questions
How does the bridge handle editor hangs or slow builds?
The status command reports the running command, the queue, and the time since the editor last ticked, helping distinguish between a slow build and a modal dialog hang.
Does the bridge support multiple programming languages?
Yes, it is a plain HTTP and JSON server with no dependencies beyond UEFN's embedded Python, making it compatible with any language.
How does the bridge prevent duplicate commands if a request times out?
If a call times out but may have already started, it is reported as outcome_unknown and is never replayed on another route to prevent stacking duplicate entities or sessions.