# Solución de problemas — Unity · AI Game Developer Wiki Soluciona fallos habituales de Unity MCP: herramientas ausentes, errores de acceso y conexión, descargas del servidor y conflictos de puertos. Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/unity/troubleshooting). 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 .`, 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](https://ai-game.dev/docs/auth). ## El servidor MCP local no se inicia (modo Custom) - **El binario no se ha descargado.** Va a `Library/mcp-server//`. 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: ```powershell netstat -ano | findstr : ``` ```bash lsof -i : ``` 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](https://ai-game.dev/es/docs/wiki/unity/custom-tools#main-thread). ## 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](https://ai-game.dev/es/docs/wiki/unity/faq) o las [FAQ](https://ai-game.dev/docs/faq) de todo el sitio. --- Source (HTML): https://ai-game.dev/es/docs/wiki/unity/troubleshooting Machine-translated (es) from the English page: https://ai-game.dev/docs/wiki/unity/troubleshooting