# Solución de problemas — Godot · AI Game Developer Wiki

Resuelve problemas comunes de Godot MCP: addon que no carga, lista Extensions vacía, herramientas ausentes, errores de recarga y fallos de .NET 10.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/godot/troubleshooting).

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**.

```bash
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](https://ai-game.dev/es/docs/wiki/godot/installation#nuget-packages) 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:

```xml
<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](https://ai-game.dev/es/docs/wiki/godot/extensions#catalog).

## 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:

```text
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](https://ai-game.dev/es/docs/wiki/godot/faq) y las [FAQ del sitio](https://ai-game.dev/docs/faq), o informa del problema en el [seguidor de incidencias de Godot-MCP](https://github.com/IvanMurzak/Godot-MCP/issues) con el registro del panel Output y tus versiones de Godot, .NET y del addon.

---

Source (HTML): https://ai-game.dev/es/docs/wiki/godot/troubleshooting

Machine-translated (es) from the English page: https://ai-game.dev/docs/wiki/godot/troubleshooting