# Solución de problemas — Unreal Engine · AI Game Developer Wiki Soluciona problemas comunes de Unreal MCP: plugin que no carga, bridge ausente, conexión atascada, agente de IA sin herramientas de Unreal y errores. Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/unreal/troubleshooting). Esta página enumera los problemas más frecuentes con Unreal MCP y cómo solucionarlos. Empieza por las comprobaciones rápidas y luego salta a la sección correspondiente. ## Comprobaciones rápidas 1. **¿Está cargado el plugin?** El Output Log debería contener `[Unreal-MCP] plugin loaded` después de que se inicie el editor. 2. **¿Qué dice la ventana?** Abre **Tools**, **AI Game Developer** y lee la línea de estado (Connected, Connecting, Reconnecting, Disconnected o No MCP bridge). 3. **¿Qué ve la CLI?** Ejecuta `unreal-mcp-cli status --path ./YourProject`. 4. **Lee el log.** Usa **Open log file** en la ventana, filtra el Output Log por la categoría `LogUnrealMcp` o pide al agente `console | where Verbosity == "Error"`. ## El plugin no se carga Si no aparece la línea `[Unreal-MCP] plugin loaded`, el módulo del editor no llegó a iniciarse. - Busca en el Output Log un error de inicio del plugin o un `.uplugin` dañado. - Asegúrate de que el proyecto sea un **proyecto de C++** con una cadena de herramientas de compilador funcional. Consulta [Instalación](https://ai-game.dev/es/docs/wiki/unreal/installation#requirements). - Si Unreal indica que faltan módulos o que el plugin es incompatible, deja que recompile, o abre el proyecto con `unreal-mcp-cli open ./YourProject`, que compila primero los módulos nativos y descarta esos avisos. ## Una actualización no tiene efecto La compilación incremental de Unreal puede conservar código antiguo del plugin cuando cambia el código fuente pero sobrevive su antigua carpeta `Intermediate/`. - Actualiza con `unreal-mcp-cli update ./YourProject`, que limpia la caché de compilación de forma predeterminada. - Tras una copia manual: cierra el editor, elimina `Plugins/UnrealMCP/Intermediate/` y los archivos C++ de `Plugins/UnrealMCP/Binaries/` (conserva `Binaries/ThirdParty/`) y vuelve a abrirlo. ## "No MCP bridge" o el bridge no deja de reiniciarse El plugin necesita su proceso bridge, `unreal-mcp-bridge`. La ventana muestra el estado del bridge y un recuento de reinicios. - Si el log dice `no sidecar binary resolved for rid `, no se encontró ningún bridge. - **Instalación desde la app o la CLI:** el bridge viene incluido. Reinstala con `unreal-mcp-cli install-plugin ./YourProject` (o desde la app); puede que el paquete no incluya tu plataforma. - **Checkout del código fuente:** compila uno con `unreal-mcp-cli bootstrap-local ./YourProject` o define `UNREAL_MCP_BRIDGE_PATH`. - Haz clic en **Restart bridge** en el pie de la ventana después de corregir la causa. ## Atascado en "Connecting" o "Reconnecting" - **Modo Cloud:** comprueba que has iniciado sesión. Si la ventana muestra "Sign in required", tu sesión guardada ha caducado; haz clic en **Authorize** y aprueba el nuevo código. - Comprueba que la máquina puede acceder a ai-game.dev (reglas de proxy o firewall). - **Modo Custom:** asegúrate de que el servidor local está en marcha (**Start** en la tarjeta del servidor MCP, o `--start-server`) y de que **Server URL** apunta a él. - Usa **Disconnect** y luego **Connect**, o **Restart bridge**. ## El servidor local dice "No connected clients" Si un `gamedev-mcp-server` local registra `No connected clients. Retrying` y luego responde con HTTP 500, el editor sigue en modo **Cloud** y conectado a ai-game.dev en lugar de a tu servidor local. Cambia a **Custom** en la ventana, define `UNREAL_MCP_CONNECTION_MODE=Custom` o pasa `--connection-mode Custom` (o `--host`) a `unreal-mcp-cli open`. ## El agente de IA no tiene herramientas de Unreal - Revisa la configuración del agente: ejecuta `unreal-mcp-cli setup-mcp --path ./YourProject --dry-run` y compárala, o haz clic en **Configure** (o **Reconfigure**) en la sección del agente de IA. - Reinicia o recarga el agente después de cambiar la configuración. Muchos clientes solo leen las configuraciones de MCP al arrancar. - Claude Code lee `.mcp.json` de la carpeta en la que lo inicias; inícialo en la carpeta del proyecto. - Si configuraste con `setup-mcp` antes de abrir el editor alguna vez, puede que la configuración apunte a `localhost` en lugar de a la nube. Abre el proyecto una vez y vuelve a ejecutar `setup-mcp`, o pasa `--url`. - Revisa la fila **AI agents** de la sección Connection. Si tu agente no aparece en la lista, no está conectado al mismo servidor que el editor. - Si ocultaste herramientas en la ventana **MCP Tools** o definiste `UNREAL_MCP_TOOLS`, el agente verá menos herramientas. ## El agente llega al editor equivocado Si tienes varios editores en una misma cuenta, usa la URL fijada al proyecto (`/mcp/p/`), que `setup-mcp` escribe de forma predeterminada. Vuelve a ejecutar `setup-mcp` sin `--no-pin`. Consulta [Conectar clientes de IA](https://ai-game.dev/es/docs/wiki/unreal/connecting-ai-clients#pinned-url). ## Errores 401 en el agente - En el modo Cloud, una configuración que solo contiene una URL necesita que el agente inicie sesión por sí mismo. O bien dejas que ejecute su inicio de sesión OAuth, o inicias sesión en la máquina (`unreal-mcp-cli login`) y ejecutas `setup-mcp` de nuevo para que la configuración incluya una clave de proyecto. - Si la clave de proyecto fue revocada, usa **Regenerate key** en el editor o `setup-mcp --regenerate-key`. - En el modo Custom con autenticación **token**, la configuración debe incluir el mismo token que el editor. Usa **Reconfigure** después de generar un token nuevo. ## Las llamadas a herramientas agotan el tiempo de espera Una llamada a herramienta puede ejecutarse durante 5 minutos de forma predeterminada. Aumenta `UNREAL_MCP_TOOL_TIMEOUT` (milisegundos) para scripts Python largos o importaciones grandes. `python-execute` también tiene su propio `timeout` (30 segundos por defecto) que el agente puede establecer en cada llamada. ## Las herramientas de captura de pantalla devuelven un error La captura de píxeles necesita un editor con GPU. Con `-nullrhi`, las herramientas de captura de pantalla devuelven un error estructurado. `unreal-mcp-cli exec` y `open --headless` inician editores que renderizan fuera de pantalla, así que las capturas siguen funcionando ahí. ## Las herramientas de Python fallan `python-execute` usa el Python Editor Script Plugin de Unreal, que Unreal MCP habilita. Si Python no está disponible, comprueba que el plugin esté habilitado en **Edit, Plugins**. Los errores apuntan a líneas de `snippet.py`, que es el código que envió el agente. ## La extensión no aparece - Las extensiones requieren Unreal Engine 5.7 o posterior y Unreal MCP 0.26.0 o posterior. - Tras la instalación, la extensión debe compilarse: vuelve a abrir el editor, usa `--build` o **Compile (Live Coding)** en la sección Extensions. - Comprueba que la extensión esté habilitada en la sección Extensions. ## ¿Sigues atascado? - Consulta las [FAQ](https://ai-game.dev/es/docs/wiki/unreal/faq) y las [FAQ](https://ai-game.dev/docs/faq) generales. - Usa **Help / Talk** en la ventana para preguntar en Discord, o **Bug Report** para abrir un issue en GitHub. Incluye la versión de Unreal, tu sistema operativo, la línea de estado de la ventana y las líneas de log relevantes (nunca tus tokens). --- Source (HTML): https://ai-game.dev/es/docs/wiki/unreal/troubleshooting Machine-translated (es) from the English page: https://ai-game.dev/docs/wiki/unreal/troubleshooting