Integración de MCP

La Integración de MCP de Locus permite que un cliente MCP compatible trabaje con Notas, Documentos, Pines e información de estado de Locus compatibles mientras Unreal Editor está en ejecución. Es opcional y está deshabilitada de forma predeterminada.

Locus no incluye un asistente de IA autónomo. Tu cliente MCP conectado realiza el flujo de IA y decide cuándo usar las herramientas compatibles de Locus.

Antes de conectar

Necesitas:

Unreal Editor abierto con Locus habilitado para el proyecto;
MCP Integration habilitada en los ajustes de Locus;
un cliente MCP compatible ejecutándose en la misma máquina.

El endpoint de Locus es local a tu equipo. Locus no declara compatibilidad con todos los clientes MCP ni con todas las versiones futuras. Ofrece ajustes de incorporación para OpenAI Codex, Claude Code y Gemini CLI, además de una opción genérica para otros clientes MCP Streamable HTTP compatibles. Estos ajustes configuran el mismo servidor MCP de Locus y las mismas 18 herramientas; no son integraciones de IA separadas.

La validación de lanzamiento con clientes reales usó Codex CLI 0.147.0, Claude Code 2.1.228 y Gemini CLI 0.55.1. Trátalas como versiones probadas, no como garantías permanentes de compatibilidad.

Conectar un cliente

En Unreal Editor, abre Editor Preferences > Plugins > Locus y después MCP Integration.
Activa Enable MCP y espera a que el estado muestre Running - waiting for client.
En Connection, elige el Formato de cliente adecuado: OpenAI Codex, Claude Code, Gemini CLI o Generic Streamable HTTP MCP.
Selecciona Copiar configuración.
Pega la configuración copiada en la ubicación o flujo normal de configuración del cliente MCP y conéctalo.
Vuelve a Locus y confirma que el estado muestra Client connected.

La configuración copiada es la fuente de verdad del endpoint y la credencial actuales. No escribas una configuración a mano salvo que el cliente requiera un formato que Locus no ofrezca.

OpenAI Codex

Para Codex, elige OpenAI Codex y usa Copiar configuración. Añade el TOML copiado a Codex mediante su flujo normal de configuración MCP y vuelve a cargar o reinicia Codex si lo requiere antes de conectar. Confirma el servidor Locus en la lista de servidores MCP de Codex. Para Unreal Engine 5.8, consulta la sección Usar Locus con Unreal MCP en Unreal Engine 5.8.

Claude Code

Para Claude Code, Locus copia el comando oficial de registro HTTP MCP con ámbito local de proyecto y privado del usuario. Ejecuta el comando copiado en una terminal normal. No crea un .mcp.json de proyecto compartido que contenga credenciales.

Gemini CLI

Para Gemini CLI, Locus copia el comando oficial de registro HTTP MCP con --scope user. Esto guarda la entrada del servidor y la credencial local en la configuración privada de Gemini del usuario en lugar de generar un .gemini/settings.json de proyecto que podría entrar en el control de código fuente. La contrapartida es que la entrada de Locus está disponible para ese usuario en todos los proyectos; copia una configuración nueva al cambiar a un proyecto con un endpoint o credencial activos diferentes.

Locus no añade la opción --trust de Gemini. La política normal de confirmación de herramientas de Gemini sigue vigente.

Generic Streamable HTTP MCP

Elige Generic Streamable HTTP MCP cuando un cliente compatible necesite el endpoint y el encabezado Authorization en lugar de un formato específico. Sigue las indicaciones de configuración privada de ese cliente y usa marcadores como Bearer <LOCAL_LOCUS_CREDENTIAL> en las notas o ejemplos que conserves.

Usar Locus con Unreal MCP en Unreal Engine 5.8

El Unreal MCP integrado de Unreal Engine 5.8 y Locus MCP pueden ejecutarse en paralelo como servidores MCP independientes. Locus no depende de Unreal MCP.

La configuración verificada de abajo usa Codex. Es un ejemplo específico de cliente, no una afirmación de que esta capacidad de servidores independientes sea exclusiva de Codex.

Ejemplo de Codex

Configurar ambos servidores

En Unreal Engine 5.8, habilita Unreal MCP, All Toolsets, Terminal y Locus. Asegúrate de que el servidor Unreal MCP esté habilitado y configurado para iniciarse automáticamente.
En la consola de Unreal, ejecuta:
```
ModelContextProtocol.GenerateClientConfig Codex
```
Unreal genera la configuración de Codex en:
```
<Project>/.codex/config.toml
```
En Unreal, abre Editor Preferences > Plugins > Locus > MCP Integration. Habilita el servidor MCP de Locus y selecciona Copy Connection Configuration > OpenAI Codex (config.toml).
Pega el bloque MCP de Locus generado debajo de la configuración MCP generada por Unreal en <Project>/.codex/config.toml. No recrees manualmente las URL, los encabezados ni las credenciales de Locus; el bloque copiado es la configuración de conexión actual.

El archivo debe contener ambas entradas de servidor MCP:

unreal-mcp
locus

Iniciar Codex y comprobar la conexión

Abre la Terminal de Unreal Engine en la raíz del proyecto y ejecuta:

codex

Pide a Codex que compruebe los servidores MCP disponibles:

Check which MCP servers are available to you.

Debe enumerar unreal-mcp y locus. Después, prueba cada integración por separado:

Use Unreal MCP to inspect my currently selected actor.

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

Mantener la conexión local y privada

Locus solo escucha en la interfaz de bucle local; el endpoint MCP solo está disponible en la misma máquina. Una credencial bearer local generada para el usuario autentica al cliente.

Copiar configuración es la acción explícita que produce texto con credenciales. Trata la configuración copiada como confidencial y pégala solo en un cliente de confianza. No la incluyas en documentación, informes, capturas, mensajes ni configuraciones bajo control de código fuente. Locus no muestra intencionadamente la credencial en Ajustes ni la escribe en registros. Si crees que se ha expuesto, usa Advanced > Regenerate Credential… y copia una configuración nueva al cliente.

Desactivar Enable MCP detiene el acceso MCP de Locus. Cerrar Unreal Editor también termina el endpoint MCP activo. Para el límite de privacidad más amplio del contenido local y los clientes externos, consulta Privacidad y comentarios.

Elegir permisos deliberadamente

Ajuste	Qué permite
Solo lectura	El valor predeterminado. Los clientes pueden usar operaciones de lectura compatibles, pero se rechazan las operaciones de cambio compatibles. El resumen muestra `ReadOnly` cuando Permitir cambios está desactivado.
Permitir cambios	Habilita las operaciones compatibles de crear, actualizar, archivar y comentar. Actívalo solo cuando quieras que el cliente conectado modifique contenido de Locus. No concede modificación arbitraria del proyecto Unreal.

El contenido privado está protegido por separado. Permitir notas y pines privados está desactivado de forma predeterminada; ni habilitar MCP ni Permitir cambios lo activa automáticamente. Actívalo solo si el cliente debe acceder a Notas y Pines privados locales. Los Documentos siempre son propiedad del proyecto y no tienen ámbito privado.

Qué pueden hacer los clientes

Locus expone 18 herramientas MCP agrupadas por el tipo de trabajo que permiten, no por detalles del protocolo MCP.

Grupo	Herramientas	Trabajo compatible
Infraestructura (2)	`locus.get_status`, `locus.get_capabilities`	Consultar estado, permisos y capacidades disponibles de Locus.
Notas (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Encontrar, leer, crear, actualizar y archivar Notas.
Documentos (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Encontrar, leer, crear y actualizar Documentos Markdown propiedad del proyecto. MCP no permite cambiar nombre, mover ni eliminar.
Pines (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Encontrar, leer, crear, actualizar y comentar Pines. MCP no permite eliminar ni archivar Pines.

Las herramientas de lectura siguen disponibles en Solo lectura. Las de crear, actualizar, archivar y comentar requieren Permitir cambios. Las protecciones de Locus, incluidas las reglas de control de código fuente y validación de contenido, siguen aplicándose.

Los Documentos creados mediante MCP siguen el mismo flujo de adición diferida que los creados en el Editor: comienzan locales y Sin seguimiento. Organízalos, cambia su nombre, muévelos o edítalos en Locus y usa explícitamente Marcar para añadir cuando la ruta final esté lista. MCP no ofrece herramientas para cambiar el nombre, mover, eliminar o marcar para añadir Documentos.

Raíces de presentación de Documentos

MCP entiende las mismas dos raíces de presentación del espacio de trabajo Documentos. Ambas son vistas del único repositorio <Project>/ProjectDocuments/:

Documentos de Locus contiene Documentos normales fuera de la asignación reservada Content/.... Una ruta de presentación como Design/Combat.md tiene la misma ruta autoritativa: Design/Combat.md.
Content Browser contiene Documentos Markdown proyectados en el contexto de Unreal Content Browser. Una ruta como Characters/Hero.md tiene la ruta autoritativa Content/Characters/Hero.md y se asigna al contexto /Game/Characters correspondiente.

Los Documentos de Content Browser siguen siendo archivos Markdown externos. No son UAssets y /Game/... es contexto de presentación, no identidad del Documento. La ruta Markdown normalizada relativa a ProjectDocuments sigue siendo autoritativa.

locus.list_documents y locus.search_documents aceptan opcionalmente presentationRoot con valor all, locusDocuments o contentBrowser; si se omite, el valor predeterminado es all. El filtrado sigue formando parte de la operación indexada de lista/búsqueda y conserva el orden y la paginación existentes.

locus.create_document acepta locusDocuments o contentBrowser para elegir explícitamente una raíz visible. En ese modo, relativePath es relativo a la raíz seleccionada:

`presentationRoot`	`relativePath` proporcionado	Ruta autoritativa creada
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

No antepongas Content/ al crear explícitamente bajo contentBrowser; Locus aplica la asignación reservada una vez. Los clientes existentes que omiten presentationRoot conservan el contrato de ruta autoritativa anterior, por lo que una entrada heredada Content/Characters/Hero.md mantiene su significado.

Los resultados de Documentos distinguen:

relativePath: identidad normalizada autoritativa bajo ProjectDocuments;
presentationRoot: locusDocuments o contentBrowser;
presentationPath: ruta visible bajo esa raíz de presentación.

Los campos de raíz proporcionan contexto; no introducen otro repositorio ni identificador de Documento.

locus.archive_note cambia el estado de ciclo de vida de una Nota a Archived; no la mueve a un panel Archived separado. Locus 1.0 mantiene las Notas archivadas visibles en el espacio de trabajo normal de Notas y no tiene un flujo dedicado Archive/Restore del Editor ni una herramienta locus.restore_note. Para devolver una Nota al estado Open mediante MCP, usa locus.update_note con la revisión actual y status: "open".

Compatibilidad de mundos para Pines

La base compatible de Pines es un mundo /Game/... guardado y propiedad del proyecto, con identidad explícita de mundo y posición espacial de Unreal. Se admite el trabajo básico de Pines World Partition guardados y propiedad del proyecto.

No dependas de Pines MCP para mapas montados por plugins; mundos no guardados, transitorios, de vista previa o PIE/runtime; regiones especializadas de World Partition descargadas; anclajes que sigan actores o actores externos; comportamiento específico de Data Layers; Level Instances; subniveles de streaming tradicionales; ni recuperación por renombrado/redirección de mundo. Esos contextos quedan fuera de la base compatible actual.

Un cliente a la vez

Locus permite una sesión de cliente autorizado y completa las llamadas de herramientas de una en una. Si otro cliente posee la sesión, un segundo cliente puede ser rechazado o aparecer ocupado hasta que termine o expire la sesión activa.

Cierra o desconecta primero el cliente anterior, espera un poco si fue interrumpido y vuelve a intentarlo. Si no libera la sesión, usa Troubleshooting > Reset Active Client en Integración de MCP. Deshabilita y vuelve a habilitar MCP solo cuando sea necesario para recuperar el servidor local.

Desconectar o deshabilitar MCP

Desconecta el cliente cuando termines. Para detener por completo el acceso MCP de Locus, desactiva Enable MCP. Deshabilitar MCP no elimina el contenido de Locus ni la credencial local; solo detiene el endpoint local hasta que vuelvas a habilitarlo.

Solucionar problemas de conexión

Síntoma	Qué hacer
MCP está deshabilitado o no hay endpoint	Mantén Unreal Editor abierto, abre MCP Integration, activa Enable MCP y espera a un estado en ejecución.
El cliente rechaza la conexión o credencial	Copia una configuración nueva. Hazlo después de cambiar el puerto local o regenerar la credencial; las configuraciones antiguas ya no funcionarán.
Otro cliente está activo o Locus está ocupado	Cierra el otro cliente, espera y vuelve a intentarlo. Usa Reset Active Client solo cuando ya no se use ese cliente. Espera a que termine una operación Locus en curso antes de repetir la llamada.
Un cliente no puede cambiar contenido	Permitir cambios está desactivado. Actívalo solo para los cambios compatibles de Locus que quieras permitir.
Se rechazan Notas o Pines privados	Habilita Permitir notas y pines privados por separado. Permitir cambios por sí solo no concede acceso privado.
Una solicitud de Pin informa de un mundo no compatible	Usa un mundo `/Game/...` guardado y propiedad del proyecto, o vuelve al flujo del Editor de Locus. Consulta Pines para los requisitos normales del viewport.
Unreal Editor se reinició	Vuelve a abrir el proyecto y conecta de nuevo el cliente. Copia una configuración nueva si el estado muestra otro endpoint o credencial.

Para problemas generales de Locus, consulta Solución de problemas. Para el resto de Ajustes de Locus, consulta Ajustes.