Solución de problemas

La mayoría de los problemas de Godot MCP vienen de uno de cuatro sitios: una compilación de Godot equivocada, un .csproj que no coincide con el addon, un ensamblado de C# que no se compiló, o un cliente de IA que no apunta al servidor correcto. Repasa la sección que coincida con lo que ves. Si te quedas atascado, sube el Log Level del dock a Debug, reproduce el problema y lee el panel Output.

El addon no se carga#

"Unable to load addon script" la primera vez que se abre#

Godot instancia los addons habilitados en cuanto arranca el editor. La primera vez que se abre un proyecto de C# que nunca se ha compilado todavía no existe ningún ensamblado, así que Godot informa de que no puede cargar res://addons/godot_mcp/Editor/GodotMcpPlugin.cs y deshabilita el addon.

Solución: compila primero y luego vuelve a habilitar el plugin en Project, Project Settings, Plugins.

godot-cli build ./MyGodotProject
godot-cli open ./MyGodotProject

godot-cli open siempre compila antes de iniciar el editor, así que evita este problema.

El addon no compila#

• Estás usando la compilación estándar de Godot. Godot MCP necesita la compilación .NET (mono) de Godot 4.3 o posterior.
• Al .csproj le faltan los paquetes NuGet, o tiene versiones distintas a las del addon que instalaste. Vuelve a ejecutar godot-cli install-plugin, o copia el bloque de Instalación con las versiones de tu release del addon.
• El proyecto no tiene .csproj. Crea la solución de C# desde Godot, o usa godot-cli create-project --dotnet para un proyecto nuevo.
• El SDK de .NET 8 no está instalado o no está en el PATH.

FileNotFoundException de un ensamblado NuGet#

Godot no resuelve por sí solo los paquetes NuGet de un proyecto en el editor; el addon lo hace leyendo el .deps.json de la compilación y tu caché de NuGet. Si aun así no se encuentra un ensamblado, ejecuta dotnet restore y vuelve a compilar. Si el problema persiste, elimina .godot/mono/temp/obj y .godot/mono/temp/bin y recompila: la causa habitual es una salida de compilación obsoleta.

Un juego iniciado con Play no puede crear scripts de C##

Síntoma: todos los scripts de C# fallan con "Cannot instantiate C# script because the associated class could not be found", tras una TypeLoadException que nombra una clase EditorPlugin. A tu .csproj le falta <EnableDynamicLoading>true</EnableDynamicLoading>, así que los ensamblados del paquete no se copian junto al ensamblado del juego. Añádelo al <PropertyGroup> junto a <TargetFramework> y vuelve a compilar. godot-cli install-plugin y create-project lo configuran por ti.

La lista Extensions está vacía#

El dock lee el catálogo de extensiones desde tu proyecto compilado. Tu .csproj necesita esta línea y, después, recompilar:

<EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />

El LogicalName debe ser exactamente Godot-MCP.extensions.catalog.json. Si el dock indica que no se encontró ningún .csproj, el addon no está dentro de un proyecto de C# de Godot. Consulta Extensions.

El editor no se conecta#

• Modo Cloud, sin sesión iniciada. Haz clic en Authorize en el dock, o ejecuta godot-cli login. El dock muestra tu estado de sesión.
• Anulado por el entorno. Una nota amarilla "Overridden by environment (GODOT_MCP_*)" significa que una variable o un archivo .env fuerza el modo o el host, y los cambios en el dock no hacen nada. Elimina la variable o cámbiala.
• Modo Custom, sin servidor. Haz clic en Start Server en el dock, o inicia tu propio servidor. Cuando no hay conexión, la descarga del servidor falla con una advertencia en el panel Output y no se inicia ningún servidor local; usa el modo Cloud o ejecuta un servidor que ya tengas.
• Modo Custom con oauth en un host remoto. El addon solo envía el token de tu cuenta a un servidor localhost. Para otros hosts define GODOT_MCP_TOKEN; de lo contrario, la conexión falla con "Refusing to send your ai-game.dev account token".

Compruébalo desde una terminal con godot-cli status ./MyGodotProject y godot-cli wait-for-ready ./MyGodotProject.

El agente de IA no ve ninguna herramienta de Godot#

• El agente se inició antes de que se escribiera su configuración. Reinícialo o recarga sus servidores MCP.
• Claude Code lee .mcp.json desde la carpeta en la que se inicia. Inícialo en la carpeta del proyecto, o escribe la configuración donde lo inicies.
• Hay varios editores conectados y el agente usa la URL /mcp sin más. Usa la URL fijada que setup-mcp escribe por defecto, para que el agente llegue al proyecto correcto.
• La configuración apunta a un servidor distinto del editor (cloud vs local). Vuelve a ejecutar godot-cli setup-mcp <agent> después de cambiar de modo, o haz clic en Reconfigure en el dock.
• Las herramientas están ocultas. Consulta la sección de funcionalidades MCP del dock o godot-cli configure --list. Una herramienta oculta no se muestra al agente.

Las llamadas a herramientas fallan durante una recompilación de C##

Godot recarga el ensamblado de C# del proyecto aproximadamente medio segundo después de que cambie el DLL compilado (script-build, el botón Build o un dotnet build). El addon forma parte de ese ensamblado, así que se destruye, se reconstruye y se vuelve a conectar en unos segundos. Durante una recarga, las llamadas nuevas se rechazan con un error reintentable ("Godot is about to reload the project's C# assembly … Retry in a few seconds"). Espera y vuelve a intentarlo; script-build entrega su resultado después de la recarga.

El editor se bloquea o se cuelga tras una recarga en .NET 10#

Se trata de un bug del runtime de .NET (dotnet/runtime#135441). Hasta que se publique la corrección de mantenimiento de .NET 10, define esta variable de entorno para el proceso del editor y reinicia Godot:

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

En Windows puedes definirla con setx DOTNET_ThreadPool_ThreadsToKeepAlive -1. Los editores iniciados por godot-cli open o exec la reciben automáticamente. Elimínala cuando tu runtime de .NET incluya la corrección.

Las llamadas van a una compilación antigua#

Si las llamadas a herramientas se comportan como una versión anterior de tu código, puede que haya más de un editor conectado para el mismo proyecto, por ejemplo un editor headless olvidado. Cierra los sobrantes (godot-cli close --owned-only cierra los editores que inició godot-cli) y mantén un solo editor conectado.

Una compilación falla con MissingMethodException#

La versión de Godot.NET.Sdk del proyecto debe coincidir con el editor que ejecutas. Un proyecto compilado contra 4.3 puede lanzar MissingMethodException en un editor 4.4 o posterior donde las API han cambiado. Actualiza la versión Sdk="Godot.NET.Sdk/…" de tu .csproj a la versión de tu editor y vuelve a compilar.

Si sigues atascado#

Consulta las FAQ y las FAQ del sitio, o informa del problema en el seguidor de incidencias de Godot-MCP con el registro del panel Output y tus versiones de Godot, .NET y del addon.