Esta página se tradujo automáticamente del inglés. Lee el original en inglés.

Solución de problemas

Soluciona problemas comunes de Unreal MCP: plugin que no carga, bridge ausente, conexión atascada, agente de IA sin herramientas de Unreal y errores.

Actualizado el 4 de noviembre de 2026 Ver como Markdown

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.
  • 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 <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 <agent> --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/<pin>), que setup-mcp escribe de forma predeterminada. Vuelve a ejecutar setup-mcp sin --no-pin. Consulta Conectar clientes de IA.

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 y las 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).