MCP Integration

Locus MCP Integration lets a compatible MCP client work with supported Locus Notes, Documents, Pins, and Locus status while Unreal Editor is running. It is optional and disabled by default.

Locus does not include an autonomous AI assistant. Your connected MCP client performs the AI workflow and decides when to use the supported Locus tools.

Before you connect

You need:

Unreal Editor open with Locus enabled for the project
MCP Integration enabled in Locus settings
a compatible MCP client running on the same machine

The Locus endpoint is local to your computer. Locus does not claim compatibility with every MCP client or every future client version. Locus provides onboarding presets for OpenAI Codex, Claude Code, and Gemini CLI, plus a generic option for other compatible Streamable HTTP MCP clients. These presets configure the same Locus MCP server and the same 18 tools; they are not separate AI integrations.

Real-client release validation used Codex CLI 0.147.0, Claude Code 2.1.228, and Gemini CLI 0.55.1. Treat these as tested versions, not permanent compatibility guarantees.

Connect a client

In Unreal Editor, open Editor Preferences > Plugins > Locus, then open MCP Integration.
Turn on Enable MCP and wait for the status to show Running - waiting for client.
Under Connection, choose the appropriate Client Format: OpenAI Codex, Claude Code, Gemini CLI, or Generic Streamable HTTP MCP.
Select Copy Configuration.
Paste the copied configuration into your MCP client’s normal configuration location or setup flow, then connect it.
Return to Locus and confirm the status shows Client connected.

The copied configuration is the source of truth for the current endpoint and credential. Do not hand-write a connection configuration unless your client requires a format that Locus does not offer.

OpenAI Codex

For Codex, choose OpenAI Codex and use Copy Configuration. Add the copied TOML to Codex through its normal MCP setup flow, then reload or restart Codex if it requires that before connecting. Confirm the Locus server from Codex’s MCP server list. For Unreal Engine 5.8, see Using Locus MCP with Unreal MCP in UE 5.8 for the verified Codex example.

Claude Code

For Claude Code, Locus copies the official HTTP MCP registration command with project-local, user-private scope. Run the copied command in a normal terminal. It does not create a shared credential-bearing project .mcp.json.

Gemini CLI

For Gemini CLI, Locus copies the official HTTP MCP registration command with --scope user. This stores the server entry and local credential in the user’s private Gemini configuration instead of generating a project .gemini/settings.json that could enter source control. The tradeoff is that the Locus entry is available to that user across projects, so copy a fresh configuration when switching to a project with a different active endpoint or credential.

Locus does not add Gemini’s --trust option. Gemini’s normal tool-confirmation policy remains in effect.

Generic Streamable HTTP MCP

Choose Generic Streamable HTTP MCP when a compatible client needs the endpoint and Authorization header rather than one of the supported client-specific formats. Follow that client’s private configuration guidance and use placeholders such as Bearer <LOCAL_LOCUS_CREDENTIAL> in any notes or examples you keep.

Using Locus MCP with Unreal MCP in UE 5.8

Unreal Engine 5.8’s built-in Unreal MCP and Locus MCP can run side by side as independent MCP servers. Locus does not depend on Unreal MCP.

The verified setup below uses Codex. It is a client-specific example, not a claim that this independent-server capability is Codex-only.

Codex example

Configure both servers

In Unreal Engine 5.8, enable Unreal MCP, All Toolsets, Terminal, and Locus. Ensure the Unreal MCP server is enabled and set to auto-start.

In the Unreal console, run:

ModelContextProtocol.GenerateClientConfig Codex

Unreal generates the Codex configuration at:

<Project>/.codex/config.toml

In Unreal, open Editor Preferences > Plugins > Locus > MCP Integration. Enable the Locus MCP server, then select Copy Connection Configuration > OpenAI Codex (config.toml).
Paste the generated Locus MCP block below the Unreal-generated MCP configuration in <Project>/.codex/config.toml. Do not recreate Locus URLs, headers, or credentials by hand; the copied block is the current connection configuration.

The file should contain both MCP server entries:

unreal-mcp
locus

Start Codex and verify the connection

Open the Unreal Engine Terminal at the project root and run:

codex

Ask Codex to check the available MCP servers:

Check which MCP servers are available to you.

It should list unreal-mcp and locus. Then test each integration independently:

Use Unreal MCP to inspect my currently selected actor.

Use Locus to get its current status and list my Notes. Do not modify anything.

Keep the connection local and private

Locus listens only on the local loopback interface, so the MCP endpoint is available only on the same machine. A generated user-local bearer credential authenticates the client.

Copy Configuration is the explicit action that produces credential-bearing text. Treat the copied configuration as sensitive: paste it only into a trusted client. Do not include it in documentation, issue reports, screenshots, chat messages, or source-controlled configuration. Locus does not intentionally display the credential in Settings or emit it in logs. If you believe it was exposed, use Advanced > Regenerate Credential…, then copy a fresh configuration into the client.

Turning off Enable MCP stops Locus MCP access. Closing Unreal Editor also ends the active Locus MCP endpoint. For the broader local-content and external-client privacy boundary, see Privacy and Feedback.

Choose permissions deliberately

Setting	What it allows
Read Only	The default. Clients can use supported read operations, but supported mutation operations are denied. The status summary shows this as `ReadOnly` when Allow Changes is off.
Allow Changes	Enables the supported create, update, archive, and comment operations. Turn it on only when you want the connected client to modify Locus content. It does not grant arbitrary Unreal project modification.

Private content is protected separately. Allow Private Notes and Pins is off by default, and neither enabling MCP nor turning on Allow Changes grants it automatically. Turn it on only when the connected client should access user-local Private Notes and Pins. Documents are always project-owned and have no Private scope.

What clients can do

Locus exposes 18 MCP tools. They are grouped by the kind of work they support rather than by MCP protocol details.

Group	Tools	Supported work
Infrastructure (2)	`locus.get_status`, `locus.get_capabilities`	Check Locus status, permissions, and available capabilities.
Notes (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Find, read, create, update, and archive Notes.
Documents (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Find, read, create, and update project-owned Markdown Documents. Rename, move, and delete are not available through MCP.
Pins (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Find, read, create, update, and comment on Pins. Pin delete and archive are not available through MCP.

Read tools remain available in Read Only. The supported create, update, archive, and comment tools need Allow Changes. Existing Locus safeguards, including source-control and content validation rules, still apply.

Documents created through MCP follow the same deferred-add workflow as Documents created in the Editor: they begin local and Untracked. Organize, rename, move, or edit them in Locus, then explicitly use Mark for Add when the final path is ready. MCP does not offer Document rename, move, delete, or Mark for Add tools.

Documents presentation roots

MCP understands the same two presentation roots shown in the Documents workspace. Both are views of the single <Project>/ProjectDocuments/ repository:

Locus Documents contains normal Documents outside the reserved Content/... mapping. A presentation path such as Design/Combat.md has the same authoritative path: Design/Combat.md.
Content Browser contains Markdown Documents projected into Unreal Content Browser context. A presentation path such as Characters/Hero.md has the authoritative Document path Content/Characters/Hero.md and maps to the corresponding /Game/Characters context.

Content Browser Documents remain external Markdown files. They are not UAssets, and /Game/... is presentation context rather than Document identity. The normalized ProjectDocuments-relative Markdown path remains authoritative.

locus.list_documents and locus.search_documents accept an optional presentationRoot value of all, locusDocuments, or contentBrowser; omitting it defaults to all. Filtering remains part of the indexed list/search operation and keeps the existing ordering and pagination behavior.

locus.create_document accepts locusDocuments or contentBrowser when the caller wants to choose a visible root explicitly. In that mode, relativePath is relative to the selected presentation root:

`presentationRoot`	Supplied `relativePath`	Authoritative path created
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

Do not prepend Content/ when explicitly creating under contentBrowser; Locus applies the reserved mapping once. Existing callers that omit presentationRoot keep the previous authoritative-path contract, so a legacy Content/Characters/Hero.md input retains its existing meaning.

Document results distinguish:

relativePath: the authoritative normalized identity beneath ProjectDocuments
presentationRoot: locusDocuments or contentBrowser
presentationPath: the path visible beneath that presentation root

The root fields provide context; they do not introduce another repository or Document identifier.

locus.archive_note changes a Note’s lifecycle state to Archived; it does not move the Note into a separate Archived Notes panel. Locus 1.0 keeps archived Notes visible in the normal Notes workspace and has no dedicated Editor Archive/Restore workflow or locus.restore_note tool. To return a Note to the Open state through MCP, use locus.update_note with the current revision and status: "open".

Pin world support

The supported Pin baseline is a saved project-owned /Game/... world with an explicit world identity and Unreal world-space position. Basic saved project-owned World Partition Pin work is supported.

Do not rely on MCP Pins for plugin-mounted maps; unsaved, transient, preview, or PIE/runtime worlds; specialized unloaded World Partition regions; actor-following or external-actor anchors; Data Layer-specific behavior; Level Instances; traditional streaming sublevels; or world rename/redirect recovery. Those contexts are outside the current supported baseline.

One client at a time

Locus permits one active authorized client session and completes tool calls one at a time. If another client owns the session, a second client can be rejected or shown as busy until the active session ends or expires.

Close or disconnect the earlier client first, wait briefly if it was interrupted, then retry. If that does not release the session, use Troubleshooting > Reset Active Client in MCP Integration. Disable and re-enable MCP only when it is necessary to recover the local server.

Disconnect or disable MCP

Disconnect the client when you have finished using it. To stop Locus MCP access entirely, turn off Enable MCP. Disabling MCP does not delete your Locus content or the local credential; it only stops the local endpoint until you enable it again.

Troubleshoot a connection

Symptom	What to do
MCP is disabled or no endpoint is available	Keep Unreal Editor open, open MCP Integration, turn on Enable MCP, and wait for a running status.
The client rejects the connection or credential	Copy a fresh configuration. Do this after changing the local port or regenerating the credential; older copied configurations no longer work.
Another client is active or Locus is busy	Close the other client, wait briefly, and retry. Use Reset Active Client only when that client is no longer in use. Wait for an in-progress Locus operation to finish before retrying a tool call.
A client cannot change content	Allow Changes is off. Enable it only for the supported Locus changes you intend to allow.
Private Notes or Pins are denied	Enable Allow Private Notes and Pins separately. Allow Changes alone does not grant Private access.
A Pin request reports an unsupported world context	Use a saved project-owned `/Game/...` world, or move the task back to the Locus Editor workflow. See Pins for normal viewport requirements.
Unreal Editor restarted	Reopen the project and reconnect the client. Copy a fresh configuration if the status shows a different endpoint or credential.

For general Locus issues, see Troubleshooting. For the rest of the Locus settings surface, see Settings.