Solução de problemas

A maioria dos problemas do Godot MCP vem de um de quatro lugares: a build errada do Godot, um .csproj que não corresponde ao addon, um assembly C# que não foi compilado ou um cliente de IA que não aponta para o servidor certo. Percorra a seção que corresponde ao que você está vendo. Se travar, aumente o Log Level do dock para Debug, reproduza o problema e leia o painel Output.

O addon não carrega#

"Unable to load addon script" na primeira abertura#

O Godot instancia os addons habilitados assim que o editor inicia. Na primeiríssima abertura de um projeto C# que nunca foi compilado, ainda não existe assembly, então o Godot informa que não consegue carregar res://addons/godot_mcp/Editor/GodotMcpPlugin.cs e desativa o addon.

Correção: compile primeiro e depois habilite o plugin novamente em Project, Project Settings, Plugins.

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

O godot-cli open sempre compila antes de iniciar o editor, então evita esse problema.

O addon não compila#

• Você está usando a build padrão do Godot. O Godot MCP precisa da build .NET (mono) do Godot 4.3 ou mais recente.
• O .csproj está sem os pacotes NuGet, ou tem versões diferentes das do addon que você instalou. Rode godot-cli install-plugin novamente, ou copie o bloco de Instalação com as versões da sua release do addon.
• O projeto não tem um .csproj. Crie a solução C# pelo Godot, ou use godot-cli create-project --dotnet para um projeto novo.
• O SDK do .NET 8 não está instalado ou não está no PATH.

FileNotFoundException para um assembly NuGet#

O Godot não resolve os pacotes NuGet de um projeto no editor por conta própria; o addon faz isso lendo o .deps.json da build e o seu cache do NuGet. Se um assembly ainda não for encontrado, rode dotnet restore e compile de novo. Se o problema persistir, exclua .godot/mono/temp/obj e .godot/mono/temp/bin e recompile: uma saída de build antiga costuma ser a causa.

Um jogo iniciado com Play não consegue criar scripts C##

Sintoma: todo script C# falha com "Cannot instantiate C# script because the associated class could not be found", depois de uma TypeLoadException citando uma classe EditorPlugin. Seu .csproj está sem <EnableDynamicLoading>true</EnableDynamicLoading>, então os assemblies do pacote não são copiados ao lado do assembly do jogo. Adicione essa linha ao <PropertyGroup> junto de <TargetFramework> e recompile. godot-cli install-plugin e create-project já configuram isso para você.

A lista de Extensões está vazia#

O dock lê o catálogo de extensões do seu projeto compilado. Seu .csproj precisa desta linha e, depois, de uma recompilação:

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

O LogicalName deve ser exatamente Godot-MCP.extensions.catalog.json. Se o dock disser que nenhum .csproj foi encontrado, o addon não está dentro de um projeto C# do Godot. Veja Extensions.

O editor não conecta#

• Modo Cloud, sem login. Clique em Authorize no dock, ou rode godot-cli login. O dock mostra seu status de login.
• Sobrescrito pelo ambiente. Uma nota amarela "Overridden by environment (GODOT_MCP_*)" significa que uma variável ou um arquivo .env força o modo ou o host, e mudanças no dock não fazem efeito. Remova a variável ou altere-a.
• Modo Custom, sem servidor. Clique em Start Server no dock, ou inicie seu próprio servidor. Quando offline, o download do servidor falha com um aviso no painel Output e nenhum servidor local inicia; use o modo Cloud ou rode um servidor que você já tenha.
• Modo Custom com oauth em um host remoto. O addon envia o token da sua conta apenas para um servidor localhost. Para outros hosts, defina GODOT_MCP_TOKEN, caso contrário a conexão falha com "Refusing to send your ai-game.dev account token".

Verifique em um terminal com godot-cli status ./MyGodotProject e godot-cli wait-for-ready ./MyGodotProject.

O agente de IA não vê nenhuma ferramenta do Godot#

• O agente foi iniciado antes de sua config ser escrita. Reinicie-o, ou recarregue seus servidores MCP.
• O Claude Code lê o .mcp.json da pasta em que é iniciado. Inicie-o na pasta do projeto, ou escreva a config onde você o inicia.
• Vários editores estão conectados e o agente usa a URL /mcp simples. Use a URL fixada que o setup-mcp escreve por padrão, para que o agente alcance o projeto certo.
• A config aponta para um servidor diferente do editor (cloud vs local). Rode godot-cli setup-mcp <agent> novamente depois de mudar de modo, ou clique em Reconfigure no dock.
• As ferramentas estão ocultas. Verifique a seção de recursos MCP do dock ou godot-cli configure --list. Uma ferramenta oculta não é listada para o agente.

As chamadas de ferramentas falham durante uma recompilação de C##

O Godot recarrega o assembly C# do projeto cerca de meio segundo depois que a DLL compilada muda (script-build, o botão Build ou um dotnet build). O addon faz parte desse assembly, então ele é desmontado, recompilado e se reconecta em poucos segundos. Em torno de uma recarga, novas chamadas são recusadas com um erro que permite nova tentativa ("O Godot está prestes a recarregar o assembly C# do projeto … Tente novamente em alguns segundos"). Aguarde e tente de novo; o script-build entrega seu resultado após a recarga.

O editor trava ou congela após uma recarga no .NET 10#

Este é um bug do runtime .NET (dotnet/runtime#135441). Até que a correção de manutenção do .NET 10 seja lançada, defina esta variável de ambiente para o processo do editor e reinicie o Godot:

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

No Windows, você pode defini-la com setx DOTNET_ThreadPool_ThreadsToKeepAlive -1. Editores iniciados por godot-cli open ou exec a recebem automaticamente. Remova-a quando seu runtime .NET incluir a correção.

As chamadas vão para uma build antiga#

Se as chamadas de ferramentas se comportam como uma versão mais antiga do seu código, pode haver mais de um editor conectado ao mesmo projeto, por exemplo um editor headless esquecido. Feche os extras (godot-cli close --owned-only fecha os editores que o godot-cli iniciou) e mantenha um único editor conectado.

Uma build falha com MissingMethodException#

A versão do Godot.NET.Sdk do projeto deve corresponder ao editor que você usa. Um projeto compilado para 4.3 pode lançar MissingMethodException em um editor 4.4 ou mais recente, onde as APIs mudaram. Atualize a versão Sdk="Godot.NET.Sdk/…" no seu .csproj para a versão do seu editor e recompile.

Ainda com problemas#

Consulte o FAQ e o FAQ do site, ou relate o problema no rastreador de issues do Godot-MCP com o log do painel Output e suas versões do Godot, do .NET e do addon.