Skip to content
Godot MCP Studioby Coadite
Documentation

Troubleshooting

Fixes for the most common setup snags.

Most issues come down to the editor not being open or the addon not being enabled. Work down this list.

Installer security warnings

Windows installers are code-signed. Apple Developer ID signing and notarization for macOS are still in progress. Either way, download the app only from the official download page, and do not disable an operating-system security feature just to install it.

Windows SmartScreen warning

Windows installers are signed with an SSL.com certificate issued to Asaf Efe Bağ, the developer behind Coadite. The certificate is new, and Microsoft Defender SmartScreen builds trust from download history, so it can still show a Windows protected your PC prompt for a while even though the installer is signed.

  • Check that the prompt names the publisher. If it says Unknown publisher, the file is not our signed build: delete it and download again from the download page.
  • Choose More info and then Run anyway only when the publisher matches and you downloaded that exact file from this site.
  • Windows 11 Smart App Control also relies on reputation and can block a newly signed app without offering a bypass. Do not disable it just to install the app.

The prompt goes away on its own once the certificate has earned reputation.

macOS Gatekeeper warning

The macOS app has been verified, but it is not yet signed with an Apple Developer ID or notarized. You can install it while signing is in progress. Move the app from the .dmg into Applications before opening it. If macOS blocks the launch:

  1. Confirm the .dmg came from the official download page.
  2. In Finder, Control-click Godot MCP Studio in Applications and choose Open.
  3. Review the macOS warning and choose Open only when the app name and download source are correct.

If macOS does not offer an Open option, wait for the signed build. Do not run commands that remove quarantine protection from the app. This notice will be removed after Developer ID signing and notarization are complete.

The AI can't see my project

  • Confirm the app has the right project selected.
  • Make sure you copied the app's generated MCP config, not the example from the docs, and restarted your AI client after pasting it.
  • Re-run Test connection in the app.

Pro users can open Project Health and Repair to check the selected project's client configuration, add-on and server versions, rules version, dependencies, imports, script parsing, and recent editor errors in one place. Repairs are previewed before they run.

Cursor shows no tools, or fewer than expected

Pro releases before 1.3.4 shipped one tool schema that Cursor's MCP validator rejects, and Cursor then drops the whole tool list: the server shows as connected with 0 tools and no error. Update the app; the fix is in Pro 1.3.4 and later. Lite was never affected.

Every client now gets the full catalog. An older config may still carry a --tool-profile core argument; current servers ignore it and expose every tool, and Project Health offers to rewrite the config without it. On an older server, remove it (or regenerate the config from the app) and restart Cursor.

If Cursor lists the server with zero tools right after an app update, it is usually mid-handover: the old server exits on its own once it has been idle for a minute after the update, and Cursor restarts it. Ask the AI to run get_bridge_status; a server_update entry means the restart is coming. If Cursor shows the server as stopped and does not restart it, toggle it off and on in its MCP settings. Cursor's Output panel (select "MCP") and the server's own log show the real reason when it is something else.

Live tools fail or say "not connected"

  • Godot must be open with the addon enabled (Project → Project Settings → Plugins).
  • Running-game tools additionally need the game to be playing.
  • If you just installed the addon, restart the Godot editor once.
  • If two Godot projects are open and both try to use the same connection, the app tells you instead of connecting your AI to the wrong project.

When Godot isn't connected, your AI checks why and tells you what to fix.

Running-game tools stop responding

The per-play bridge is short-lived by design. If the game was closed and reopened, ask the AI to reconnect (re-run the tool). Stale relays are dropped automatically after a timeout. If the game can't connect, for example after you renamed the project, your AI is told why.

If the game stops with "Identifier not declared" for a class your AI just created, the error says what to do. Scripts your AI creates, renames or deletes are picked up before the game starts, so this should be rare.

Addon didn't install

  • Ensure the project folder is writable.
  • Check that addons/godot_mcp_studio/ was created. If not, re-run Install addon and watch for a permissions prompt.

License won't activate

  • Generate a fresh code from your dashboard and copy it with no extra spaces. Codes expire after 15 minutes and can only be used once.
  • If you moved machines, deactivate the old device from the app first.
  • Still stuck? See Licensing & activation.

Updates aren't applying

Updates apply on launch. Fully quit and reopen the app. Corporate networks that block the update host can prevent this, so try another network once.

The full edition updates on the device's own license token, so an app that was activated on this device keeps updating even while its license needs attention. An install that was never activated has no token to update with: activate it, or download the current installer from the website while signed in.

From Pro 1.3.4 and Lite 1.1.2, Check for updates in Settings says which of these applies, and an MCP server that does not match the app refuses to start until Repair now on the server card reinstalls the matching one. Reinstalling the app does the same.

On Windows, an AI client that is still running the MCP server keeps the server executable open. From Pro 1.3.4 and Lite 1.1.2, the installer moves the old server aside so the update can complete; on earlier versions, quit the AI client before updating. The old server then notices the replacement and, once idle for a minute, exits so the client restarts it into the new version. Clients that do not restart a stopped server on their own need it toggled off and on. Project Health in the app reports if a client is still on an older server version.

Still stuck?

Open the support chat with the button in the bottom right corner of any page on our website. The AI assistant answers right away from these docs, and can find the right installer or the current price for you. Ask for a person at any time and someone from the team replies in the same chat; the assistant keeps helping until they join. Your earlier chats stay in the same place.

Pro users can attach the redacted Diagnostics Bundle from the desktop app's Settings, under Support. It contains setup and version information, but never tokens or project source.