Troubleshooting

Most Godot MCP problems come from one of four places: the wrong Godot build, a .csproj that does not match the addon, a C# assembly that was not built, or an AI client that is not pointed at the right server. Work through the section that matches what you see. If you are stuck, raise the dock's Log Level to Debug, reproduce the problem and read the Output panel.

The addon does not load#

"Unable to load addon script" on first open#

Godot instantiates enabled addons as soon as the editor starts. On the very first open of a C# project that was never built, there is no assembly yet, so Godot reports it cannot load res://addons/godot_mcp/Editor/GodotMcpPlugin.cs and disables the addon.

Fix: build first, then enable the plugin again in Project, Project Settings, Plugins.

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

godot-cli open always builds before it starts the editor, so it avoids this problem.

The addon does not compile#

• You are using the standard Godot build. Godot MCP needs the .NET (mono) build of Godot 4.3 or newer.
• The .csproj is missing the NuGet packages, or has different versions than the addon you installed. Rerun godot-cli install-plugin, or copy the block from Installation with the versions of your addon release.
• The project has no .csproj. Create the C# solution from Godot, or use godot-cli create-project --dotnet for a new project.
• The .NET 8 SDK is not installed or not on PATH.

FileNotFoundException for a NuGet assembly#

Godot does not resolve a project's NuGet packages in the editor by itself; the addon does that by reading the build's .deps.json and your NuGet cache. If an assembly is still not found, run dotnet restore and build again. If the problem stays, delete .godot/mono/temp/obj and .godot/mono/temp/bin and rebuild: a stale build output is the usual cause.

A game started with Play cannot create C# scripts#

Symptom: every C# script fails with "Cannot instantiate C# script because the associated class could not be found", after a TypeLoadException naming an EditorPlugin class. Your .csproj is missing <EnableDynamicLoading>true</EnableDynamicLoading>, so the package assemblies are not copied next to the game assembly. Add it to the <PropertyGroup> next to <TargetFramework> and rebuild. godot-cli install-plugin and create-project set it for you.

The Extensions list is empty#

The dock reads the extension catalog from your compiled project. Your .csproj needs this line, then a rebuild:

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

The LogicalName must be exactly Godot-MCP.extensions.catalog.json. If the dock says no .csproj was found, the addon is not inside a Godot C# project. See Extensions.

The editor does not connect#

• Cloud mode, not signed in. Click Authorize in the dock, or run godot-cli login. The dock shows your sign-in status.
• Overridden by environment. A yellow note "Overridden by environment (GODOT_MCP_*)" means a variable or a .env file forces the mode or host, and changes in the dock do nothing. Remove the variable or change it.
• Custom mode, no server. Click Start Server in the dock, or start your own server. When offline, the server download fails with a warning in the Output panel and no local server starts; use Cloud mode or run a server you already have.
• Custom mode with oauth on a remote host. The addon sends your account token only to a localhost server. For other hosts set GODOT_MCP_TOKEN, otherwise the connection fails with "Refusing to send your ai-game.dev account token".

Check from a terminal with godot-cli status ./MyGodotProject and godot-cli wait-for-ready ./MyGodotProject.

The AI agent sees no Godot tools#

• The agent was started before its config was written. Restart it, or reload its MCP servers.
• Claude Code reads .mcp.json from the folder it starts in. Start it in the project folder, or write the config where you start it.
• Several editors are connected and the agent uses the plain /mcp URL. Use the pinned URL that setup-mcp writes by default, so the agent reaches the right project.
• The config points at another server than the editor (cloud vs local). Rerun godot-cli setup-mcp <agent> after you change mode, or click Reconfigure in the dock.
• Tools are hidden. Check the dock's MCP features section or godot-cli configure --list. A hidden tool is not listed to the agent.

Tool calls fail during a C# rebuild#

Godot reloads the project's C# assembly about half a second after the built DLL changes (script-build, the Build button or a dotnet build). The addon is part of that assembly, so it is torn down, rebuilt and reconnects within a few seconds. Around a reload, new calls are refused with a retryable error ("Godot is about to reload the project's C# assembly … Retry in a few seconds"). Wait and retry; script-build delivers its result after the reload.

The editor crashes or hangs after a reload on .NET 10#

This is a .NET runtime bug (dotnet/runtime#135441). Until the .NET 10 servicing fix ships, set this environment variable for the editor process and restart Godot:

DOTNET_ThreadPool_ThreadsToKeepAlive=-1

On Windows you can set it with setx DOTNET_ThreadPool_ThreadsToKeepAlive -1. Editors started by godot-cli open or exec get it automatically. Remove it once your .NET runtime includes the fix.

Calls go to an old build#

If tool calls behave like an older version of your code, more than one editor may be connected for the same project, for example a forgotten headless editor. Close the extra ones (godot-cli close --owned-only closes editors that godot-cli started) and keep one editor connected.

A build fails with MissingMethodException#

The project's Godot.NET.Sdk version should match the editor you run. A project built against 4.3 can throw MissingMethodException on a 4.4 or newer editor where APIs changed. Update the Sdk="Godot.NET.Sdk/…" version in your .csproj to your editor version and rebuild.

Still stuck#

Check the FAQ and the site FAQ, or report the problem on the Godot-MCP issue tracker with the Output panel log and your Godot, .NET and addon versions.