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

Solución de problemas

Soluciona fallos habituales de Unity MCP: herramientas ausentes, errores de acceso y conexión, descargas del servidor y conflictos de puertos.

Actualizado el 4 de noviembre de 2026 Ver como Markdown

Esta página recopila los problemas que más se dan con Unity MCP y cómo solucionarlos. Empieza por la lista de comprobación rápida; si no te sirve, busca tu síntoma a continuación.

Lista de comprobación rápida

  1. Abre Window > AI Game Developer — MCP y observa la línea de tiempo: Unity, MCP server y AI agent deberían estar todos en verde.
  2. Revisa la Consola de Unity en busca de errores. Un error de compilación en cualquier parte del proyecto impide que se carguen los scripts de editor del plugin.
  3. Ejecuta unity-mcp-cli status ./MyUnityProject para ver si Unity está en ejecución y qué servidor es accesible.
  4. Reinicia tu cliente de IA después de cualquier cambio en la configuración.
  5. Asegúrate de que el plugin y tus extensiones están en las versiones actuales.

El cliente de IA no muestra ninguna herramienta de Unity

  • El cliente se conectó antes de que Unity estuviera listo. Vuelve a conectar el servidor MCP en el cliente (en Claude Code, /mcp), o reinicia el cliente cuando la ventana muestre Connected.
  • El cliente no estaba configurado o usa una configuración antigua. Haz clic en Configure (o Reconfigure) para tu agente en la ventana, o ejecuta unity-mcp-cli setup-mcp <agent> ., y luego reinicia el cliente.
  • No se ha iniciado sesión en el modo Cloud. La ventana muestra «Authorization Required». Haz clic en Authorize y aprueba el código en el navegador.
  • Hay varios proyectos abiertos. Una URL https://ai-game.dev/mcp sin fijar puede dirigirse a otro Editor. Usa la URL fijada que escribe Configure.
  • El agente se inicia desde otra carpeta. Las configuraciones a nivel de proyecto, como .mcp.json o .cursor/mcp.json, solo se leen cuando el cliente se ejecuta en la carpeta del proyecto de Unity.
  • En VS Code, cambia Copilot Chat al modo Agent.

Problemas de inicio de sesión en Cloud

  • «Authorization Required» no deja de aparecer. Tu credencial ha caducado o se ha revocado. Haz clic en Authorize de nuevo, o ejecuta unity-mcp-cli login --force.
  • «Connection Required». El inicio de sesión funcionó, pero Unity no está conectado. Haz clic en Connect.
  • Has iniciado sesión con la cuenta equivocada. Haz clic en Revoke (esto cierra la sesión en todas las herramientas de AI Game Dev de la máquina) y luego en Authorize con la cuenta correcta. unity-mcp-cli login pregunta antes de cambiar de cuenta.

La gestión de sesiones y dispositivos de tu cuenta se describe en Autenticación.

El servidor MCP local no se inicia (modo Custom)

  • El binario no se ha descargado. Va a Library/mcp-server/<platform>/. Si la descarga ha fallado (sin conexión, firewall, proxy), la ventana muestra «Server binary error» y un botón Download / Retry server. También puedes usar Tools > AI Game Developer > Server > Download Binaries.
  • El antivirus ha bloqueado el ejecutable. Permite gamedev-mcp-server en tu software de seguridad y vuelve a intentarlo.
  • El transporte es stdio. Con stdio, el agente de IA inicia el servidor por sí mismo, así que el botón Start está deshabilitado. Cambia a http si quieres que Unity lo ejecute.
  • Lee los registros del servidor. Usa Tools > AI Game Developer > Server > Open Logs y Open Log Errors.
  • Prueba el servidor directamente. Tools > AI Game Developer > Server > Launch MCP Inspector abre el MCP Inspector contra el servidor local (solo transporte HTTP; requiere Node.js).

Conflictos de puertos

Cada proyecto recibe un puerto fijo entre 20000 y 29999 derivado de su ruta. Si algo más ya está escuchando en él, la ventana muestra el servidor MCP como External. Encuentra el proceso:

netstat -ano | findstr :<port>
lsof -i :<port>

Detén ese proceso, o desconecta y escribe otro puerto en Server URL (por ejemplo http://localhost:25000), y luego haz clic en Configure de nuevo para que el agente use el nuevo puerto.

Desconexiones durante la compilación

Unity recarga los scripts después de cada cambio de código y al entrar en el modo Play. El plugin se desconecta antes de la recarga y se vuelve a conectar después, así que un breve «Disconnected» o «Connecting...» es normal. Una llamada a herramienta que estuviera en curso durante la recarga puede fallar; pide al agente que la reintente.

Errores de compilación o DLLs ausentes tras la instalación

El plugin descarga sus dependencias de .NET desde NuGet en Assets/Plugins/NuGet.

  • Errores sobre tipos ausentes de McpPlugin, ReflectorNet o SignalR. Espera a que termine la primera importación y luego usa Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs.
  • «Path too long» en Windows. El entorno de ejecución de Unity no puede abrir DLLs que superen el límite de 260 caracteres de ruta de Windows, ni siquiera con las rutas largas habilitadas. Mueve el proyecto a una carpeta más corta, como C:/Projects/MyGame.
  • Reinstalación limpia. Cierra Unity, elimina Assets/Plugins/NuGet y su archivo .meta, y vuelve a abrir el proyecto.

Ruta del proyecto con espacios

Si la Consola muestra «The project path contains spaces», mueve el proyecto a una carpeta sin espacios. El plugin avisa porque esas rutas pueden causar problemas al usarlo.

Las llamadas a herramientas fallan o agotan el tiempo de espera

  • Errores como «object not found». Pide al agente que consulte primero (por ejemplo con rql-query) en lugar de adivinar nombres o rutas. Las rutas de assets empiezan por Assets/.
  • Las operaciones largas agotan el tiempo de espera. Aumenta Tool timeout (ms) en la ventana (valor predeterminado 300000) para bakes lentos o ejecuciones de pruebas grandes.
  • Las capturas de pantalla fallan en modo batch. Un Editor iniciado con -nographics no tiene dispositivo gráfico. Inícialo en modo headless sin -nographics; unity-mcp-cli open --headless ya lo hace.
  • Una herramienta personalizada lanza errores de subproceso. Envuelve las llamadas a la API de Unity en MainThread.Instance.Run. Consulta Herramientas personalizadas.

Problemas con unity-mcp-cli

  • open se detiene en «Enter Safe Mode?» La CLI hace clic en Ignore automáticamente. En macOS, concede permiso de Accesibilidad a tu terminal; en Linux, instala xdotool.
  • exec espera y luego se rinde. El proyecto está abierto en un Editor que la CLI no inició, y su plugin no responde localmente (por ejemplo, está conectado a la nube). Conecta el plugin, cámbialo a Custom o pasa --url.
  • setup-skills falla. Necesita un Editor en ejecución con el plugin conectado. Ejecuta open y wait-for-ready primero.
  • Usa --verbose en cualquier comando para obtener registros detallados.

Restablecimiento completo

  1. Cierra Unity.
  2. Elimina Library/mcp-server/ en el proyecto.
  3. Vuelve a abrir Unity y elige Tools > AI Game Developer > Reset Config.
  4. Inicia sesión de nuevo (Cloud) o inicia el servidor (Custom) y luego haz clic en Configure para tu agente.
  5. Reinicia tu cliente de IA.

Obtener ayuda

Usa Help / Talk (Discord) o Bug Report (issues de GitHub) en la parte inferior de la ventana de AI Game Developer. Incluye tu versión de Unity, el sistema operativo, la versión del plugin (que se muestra en la ventana), el error de la Consola y los pasos para reproducirlo. También puedes consultar las FAQ o las FAQ de todo el sitio.