Connecting AI clients

Godot MCP has two sides that both connect to an MCP server: the addon in the Godot editor, and the AI client you chat with. This page explains the two connection modes, how sign-in works, and how to write the MCP config for each supported agent with godot-cli setup-mcp or the dock's Configure button.

Cloud mode (default)#

In Cloud mode the addon connects to the hosted backend at https://ai-game.dev, and your AI client connects to the MCP endpoint https://ai-game.dev/mcp. Nothing extra runs on your machine and it works across firewalls. This is the default mode and the one we recommend for most people.

Sign in with the device flow#

Cloud authentication uses the OAuth 2.1 device-authorization flow. You never copy a token by hand:

godot-cli login

The CLI prints a short code, opens your browser and waits until you approve it. The credential (access token, rotating refresh token and expiry) is saved to the machine store ~/.ai-game-dev/credentials.json (file mode 0600 on macOS and Linux, DPAPI-protected on Windows). The editor addon, the other engine CLIs and the AI Game Dev app all pick it up, and expired access tokens are refreshed automatically. Clicking Authorize in the dock runs the same flow from inside Godot.

Useful login flags: --force signs in again over an existing credential, --project <path> keeps a separate per-project credential, and --tools-only creates a narrower credential for CI runners. See the godot-cli reference and Authentication.

Pinned project URLs#

The plain endpoint https://ai-game.dev/mcp routes your agent to one of your connected editors. That is ambiguous when several projects are open, so setup-mcp writes a pinned URL by default: https://ai-game.dev/mcp/p/<pin>, where the pin is derived from the project. An agent started with that config always reaches this project's editor. Pass --no-pin if you want the plain URL.

Project keys#

When you are signed in, setup-mcp puts a project key into the agent config as Authorization: Bearer agd_pk_…. A project key does not expire and works only for this project's pin, so it cannot reach other projects on your account. It is created once per project and reused from ~/.ai-game-dev/project-keys.json.

• --regenerate-key creates a new key, rewrites the config and revokes the old key.
• --oauth writes a URL-only config instead: the agent signs in with its own OAuth prompt.
• Without a machine sign-in the config is URL-only as well.

Custom mode: your own server#

In Custom mode the addon connects to a server URL you choose, for example a server on your own machine. The server is the open-source GameDev-MCP-Server, the same binary used by Unity MCP and Unreal MCP.

The easiest way is to let the addon run it:

1. In the dock, switch the mode to Custom.
2. Leave Server URL at http://localhost:8080, or enter another local URL.
3. Click Start Server. The addon downloads the server build for its pinned server version from GitHub (HTTPS, github.com only), caches it in .godot/mcp-server/<platform>/, starts it and connects.

Stop Server stops it, and closing the editor stops it too. Downloads are skipped in CI environments. To run a server yourself instead, download a release binary or the aigamedeveloper/mcp-server Docker image:

./gamedev-mcp-server --client-transport streamableHttp --port 8080

Authorization for a custom server#

Custom mode has an Authorization Token switch with three values:

For any non-local host with oauth, the addon refuses to send your account token; set GODOT_MCP_TOKEN instead. Environment variables for both modes are listed on Configuration.

To point an agent at a local server, pass the URL to setup-mcp:

godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:8080

A local server config never carries a project key.

Supported agents and config files#

Run godot-cli setup-mcp --list to see every agent id. These are the ids the current CLI knows and where it writes the config:

Examples:

godot-cli setup-mcp cursor ./MyGodotProject
godot-cli setup-mcp codex ./MyGodotProject
godot-cli setup-mcp vscode-copilot ./MyGodotProject --oauth

Every config uses the HTTP transport (type: http and a URL). For Codex the key goes into http_headers.

Claude Desktop and claude.ai#

Claude Desktop does not take an HTTP server entry from claude_desktop_config.json. Claude Desktop and claude.ai reach the cloud endpoint as a Claude custom connector instead: add a custom connector in Claude's settings, paste the project's pinned cloud URL and sign in with your ai-game.dev account. Claude Desktop cannot use a Custom-mode server, because Godot MCP offers no stdio transport for it. For a local server, use an agent from the table that supports HTTP, such as Claude Code.

Configure from the dock#

The AI agent section of the dock does the same job as setup-mcp: pick your agent from the list, then click Configure (or Reconfigure). The status line says whether the agent's config file is set up, and a Reconfiguration Required notice appears when you change the server URL, mode or authorization after configuring. Remove deletes the Godot MCP entry from that agent's config.

Skills for your agent#

Some agents read skill files (SKILL.md) that teach them how to use the tools. The dock's Skills row, inside the AI agent section, can generate them (Generate, or the Auto-generate switch). From a terminal:

godot-cli setup-skills claude-code ./MyGodotProject

This writes the files into the agent's skills folder, such as .claude/skills for Claude Code, without a running editor. setup-skills --list shows which agents support skills.

Copy-paste configs#

If your client is not in the list, any MCP client that supports HTTP servers works: point it at https://ai-game.dev/mcp (or the pinned URL) and let it sign in with OAuth, or add a bearer header. Ready-made snippets for many clients are on the MCP endpoint page.