MCP 集成

Locus MCP 集成可以让兼容的 MCP 客户端在 Unreal Editor 运行期间使用受支持的 Locus 笔记、文档、标记点和 Locus 状态。它是可选功能，默认禁用。

Locus 不包含自主 AI 助手。连接的 MCP 客户端执行 AI 工作流，并决定何时使用受支持的 Locus 工具。

连接前

你需要：

• 打开 Unreal Editor，并在项目中启用 Locus
• 在 Locus 设置中启用 MCP 集成
• 在同一台机器上运行兼容的 MCP 客户端

Locus 端点位于本机。Locus 不声称兼容所有 MCP 客户端或所有未来的客户端版本。Locus 为 OpenAI Codex、Claude Code 和 Gemini CLI 提供连接预设，也为其他兼容的 Streamable HTTP MCP 客户端提供通用选项。这些预设配置的是同一个 Locus MCP 服务器和同一组 18 个工具，并不是不同的 AI 集成。

实际客户端发布验证使用了 Codex CLI 0.147.0、Claude Code 2.1.228 和 Gemini CLI 0.55.1。请将这些视为已测试版本，而不是永久的兼容性保证。

连接客户端

1. 在 Unreal Editor 中打开 Editor Preferences > Plugins > Locus，然后打开 MCP 集成。
2. 打开 启用 MCP，等待状态显示为运行中 - 等待客户端。
3. 在连接下选择适当的客户端格式：OpenAI Codex、Claude Code、Gemini CLI 或 通用 Streamable HTTP MCP。
4. 选择复制配置。
5. 将复制的配置粘贴到 MCP 客户端的常规配置位置或设置流程中，然后连接它。
6. 返回 Locus，确认状态显示为客户端已连接。

复制的配置是当前端点和凭据的事实来源。除非客户端要求 Locus 未提供的格式，否则不要手动编写连接配置。

OpenAI Codex

对于 Codex，选择 OpenAI Codex 并使用复制配置。通过 Codex 的常规 MCP 设置流程添加复制的 TOML；如果 Codex 要求连接前重新加载或重启，请照做。在 Codex 的 MCP 服务器列表中确认 Locus 服务器。 对于 Unreal Engine 5.8，请参阅在 Unreal Engine 5.8 中将 Locus 与 Unreal MCP 配合使用部分。

Claude Code

对于 Claude Code，Locus 会复制官方 HTTP MCP 注册命令，并使用项目本地、用户私有的范围。在普通终端中运行复制的命令。它不会创建包含共享凭据的项目 .mcp.json。

Gemini CLI

对于 Gemini CLI，Locus 会复制带有 --scope user 的官方 HTTP MCP 注册命令。这样会将服务器条目和本地凭据存储到用户的私有 Gemini 配置中，而不会生成可能进入版本控制的项目 .gemini/settings.json。代价是该用户可以在多个项目中使用 Locus 条目，因此切换到活动端点或凭据不同的项目时，请复制新配置。

Locus 不会添加 Gemini 的 --trust 选项。Gemini 正常的工具确认策略仍然生效。

通用 Streamable HTTP MCP

当兼容客户端需要端点和 Authorization 标头，而不是某个受支持的客户端专用格式时，选择通用 Streamable HTTP MCP。遵循该客户端的私有配置指导；在保存的笔记或示例中使用 Bearer <LOCAL_LOCUS_CREDENTIAL> 等占位符。

在 Unreal Engine 5.8 中将 Locus 与 Unreal MCP 配合使用

Unreal Engine 5.8 内置的 Unreal MCP 和 Locus MCP 可以作为独立的 MCP 服务器并行运行。Locus 不依赖 Unreal MCP。

下面经过验证的设置使用 Codex。它是特定客户端的示例，并不表示这种独立服务器能力仅适用于 Codex。

Codex 示例

配置两个服务器

1. 在 Unreal Engine 5.8 中启用 Unreal MCP、All Toolsets、Terminal 和 Locus。确保 Unreal MCP 服务器已启用并设置为自动启动。

2. 在 Unreal 控制台中运行：

   ModelContextProtocol.GenerateClientConfig Codex

   Unreal 会在以下位置生成 Codex 配置：

   <Project>/.codex/config.toml

3. 在 Unreal 中打开 Editor Preferences > Plugins > Locus > MCP Integration。启用 Locus MCP 服务器，然后选择 Copy Connection Configuration > OpenAI Codex (config.toml)。

4. 将生成的 Locus MCP 块粘贴到 <Project>/.codex/config.toml 中 Unreal 生成的 MCP 配置下方。不要手动重建 Locus URL、标头或凭据；复制的块就是当前连接配置。

该文件应包含两个 MCP 服务器条目：

unreal-mcp
locus

请将 Codex 配置保密

生成的 Locus 块可能包含本地 Bearer 凭据。包含凭据时，不要将 <Project>/.codex/config.toml 提交到版本控制。

启动 Codex 并验证连接

在项目根目录打开 Unreal Engine Terminal，并运行：

codex

请求 Codex 检查可用的 MCP 服务器：

Check which MCP servers are available to you.

它应列出 unreal-mcp 和 locus。然后分别测试每个集成：

Use Unreal MCP to inspect my currently selected actor.

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

保持连接本地和私有

Locus 只监听本地回环接口，因此 MCP 端点只能在同一台机器上访问。生成的用户本地 bearer 凭据用于验证客户端。

复制配置是生成包含凭据文本的明确操作。请将复制的配置视为敏感信息，只粘贴到可信客户端中。不要将它放入文档、问题报告、屏幕截图、聊天消息或版本控制配置中。Locus 不会有意在设置中显示凭据或将其写入日志。如果认为凭据已暴露，请使用 Advanced > Regenerate Credential…，然后将新配置复制到客户端。

关闭启用 MCP会停止 Locus MCP 访问。关闭 Unreal Editor 也会结束活动的 Locus MCP 端点。有关本地内容和外部客户端隐私边界的更广泛说明，请参阅隐私和反馈。

有意选择权限

设置	允许的内容
只读	默认设置。客户端可以使用受支持的读取操作，但受支持的变更操作会被拒绝。允许更改关闭时，状态摘要显示为 ReadOnly。
允许更改	启用受支持的创建、更新、归档和评论操作。只有希望连接的客户端修改 Locus 内容时才打开。它不会授予任意修改 Unreal 项目的权限。

私有内容单独受到保护。允许私有笔记和标记点默认关闭；启用 MCP 或打开允许更改都不会自动授予此权限。只有当连接的客户端应访问用户本地私有笔记和标记点时才打开。文档始终由项目所有，不存在私有范围。

客户端可以执行的操作

Locus 暴露 18 个 MCP 工具。它们按支持的工作类型分组，而不是按 MCP 协议细节分组。

组	工具	支持的工作
基础设施 (2)	locus.get_status, locus.get_capabilities	检查 Locus 状态、权限和可用能力。
笔记 (6)	locus.list_notes, locus.get_note, locus.search_notes, locus.create_note, locus.update_note, locus.archive_note	查找、读取、创建、更新和归档笔记。
文档 (5)	locus.list_documents, locus.get_document, locus.search_documents, locus.create_document, locus.update_document	查找、读取、创建和更新项目所有的 Markdown 文档。MCP 不提供重命名、移动和删除。
标记点 (5)	locus.list_pins, locus.get_pin, locus.create_pin, locus.update_pin, locus.add_pin_comment	查找、读取、创建、更新标记点和添加评论。MCP 不提供删除或归档标记点。

即使处于只读状态，也可以使用读取工具。受支持的创建、更新、归档和评论工具需要允许更改。现有的 Locus 安全措施，包括版本控制和内容验证规则，仍然适用。

通过 MCP 创建的文档遵循与在 Editor 中创建的文档相同的延迟添加工作流：它们以本地未跟踪状态开始。在 Locus 中整理、重命名、移动或编辑它们，路径准备好后再明确使用标记为添加。MCP 不提供文档重命名、移动、删除或标记为添加工具。

文档呈现根

MCP 了解文档工作区中显示的相同两个呈现根。两者都是单一 <Project>/ProjectDocuments/ 存储库的视图：

• Locus 文档包含保留的 Content/... 映射之外的普通文档。显示路径 Design/Combat.md 的权威路径也是 Design/Combat.md。
• 内容浏览器包含投影到 Unreal 内容浏览器上下文的 Markdown 文档。显示路径 Characters/Hero.md 的权威文档路径是 Content/Characters/Hero.md，并映射到对应的 /Game/Characters 上下文。

内容浏览器文档仍是外部 Markdown 文件。它们不是 UAsset，/Game/... 是呈现上下文而不是文档身份。规范化的 ProjectDocuments 相对 Markdown 路径才是权威身份。

locus.list_documents 和 locus.search_documents 接受可选的 presentationRoot 值 all、locusDocuments 或 contentBrowser；省略时默认为 all。筛选属于已建立索引的列表/搜索操作，并保持现有排序和分页行为。

当调用方要明确选择可见根时，locus.create_document 接受 locusDocuments 或 contentBrowser。在这种模式中，relativePath 相对于选定的呈现根：

presentationRoot	提供的 relativePath	创建的权威路径
locusDocuments	Design/Combat.md	Design/Combat.md
contentBrowser	Characters/Hero.md	Content/Characters/Hero.md

在 contentBrowser 下显式创建时，不要添加前缀 Content/；Locus 会应用一次保留映射。省略 presentationRoot 的现有调用方仍遵循之前的权威路径契约，因此传统输入 Content/Characters/Hero.md 保留原有含义。

文档结果区分：

• relativePath：ProjectDocuments 下的权威规范化身份
• presentationRoot：locusDocuments 或 contentBrowser
• presentationPath：呈现根下可见的路径

根字段只提供上下文，不会引入另一个存储库或文档标识符。

locus.archive_note 会将笔记的生命周期状态改为 Archived；不会将笔记移到单独的 Archived Notes 面板。Locus 1.0 会让已归档笔记继续显示在普通笔记工作区中，并且没有专用的 Editor Archive/Restore 工作流或 locus.restore_note 工具。要通过 MCP 将笔记恢复为 Open 状态，请使用当前修订版本和 status: "open" 调用 locus.update_note。

标记点世界支持

支持的标记点基线是保存的项目所有 /Game/... 世界，具有明确的世界身份和 Unreal 世界空间位置。支持基本的已保存项目所有 World Partition 标记点工作。

不要依赖 MCP 标记点处理插件挂载的地图、未保存/临时/预览/PIE 运行时世界、特殊的未加载 World Partition 区域、跟随 Actor 或外部 Actor 锚点、特定于 Data Layer 的行为、Level Instances、传统流式加载子关卡或世界重命名/重定向恢复。这些上下文不在当前支持基线内。

一次一个客户端

Locus 只允许一个活动的授权客户端会话，并一次完成一个工具调用。如果另一个客户端拥有会话，第二个客户端可能会被拒绝，或显示为忙碌，直到活动会话结束或过期。

先关闭或断开早先的客户端；如果它被中断，请稍等片刻再重试。如果仍未释放会话，请在 MCP 集成的故障排除 > 重置活动客户端中操作。只有在需要恢复本地服务器时才禁用并重新启用 MCP。

断开或禁用 MCP

使用结束后断开客户端。要完全停止 Locus MCP 访问，请关闭启用 MCP。禁用 MCP 不会删除 Locus 内容或本地凭据，只会停止本地端点，直到再次启用。

连接故障排除

症状	处理方式
MCP 已禁用或没有端点	保持 Unreal Editor 打开，打开MCP 集成，启用启用 MCP并等待运行状态。
客户端拒绝连接或凭据	复制新配置。更改本地端口或重新生成凭据后务必执行此操作；旧的复制配置不再有效。
另一个客户端活动或 Locus 忙碌	关闭另一个客户端，稍等片刻后重试。只有在不再使用该客户端时才使用重置活动客户端。重试工具调用前等待正在进行的 Locus 操作完成。
客户端无法更改内容	允许更改已关闭。只为你要允许的受支持 Locus 更改启用它。
私有笔记或标记点被拒绝	单独启用允许私有笔记和标记点。仅启用允许更改不会授予私有访问权限。
标记点请求报告不支持的世界上下文	使用已保存的项目所有 /Game/... 世界，或将任务转回 Locus Editor 工作流。常规视口要求请参阅标记点。
Unreal Editor 已重新启动	重新打开项目并连接客户端。如果状态显示不同的端点或凭据，请复制新配置。

一般 Locus 问题请参阅故障排除。Locus 其余设置请参阅设置。