# Connecting AI clients

Connect Claude Code, Cursor, Copilot, Codex, Gemini and other MCP clients to Godot MCP through the ai-game.dev cloud endpoint or your own local server.

_Last updated: 2026-11-04_

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:

```bash
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](https://ai-game.dev/docs/wiki/godot/cli#login) and [Authentication](https://ai-game.dev/docs/auth).

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

**Warning**

A project key is a credential. Do not commit config files that contain one (for example `.mcp.json` or `.cursor/mcp.json`) to a public repository.

## 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](https://github.com/IvanMurzak/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:

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

### Authorization for a custom server

Custom mode has an **Authorization Token** switch with three values:

| Value | Meaning |
| --- | --- |
| `none` | No authentication. Fine for a server that only listens on your own machine. |
| `oauth` | Sends your signed-in ai-game.dev account token, but only to a localhost server (`localhost`, `127.0.0.0/8`, `::1`). |
| `token` | A bearer token. Click **New** to generate one; it is stored masked. |

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](https://ai-game.dev/docs/wiki/godot/configuration#environment-variables).

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

```bash
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:

| Agent | id | Config file |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json` in the project |
| Claude Desktop | `claude-desktop` | Use a Claude custom connector (see below) |
| Cursor | `cursor` | `.cursor/mcp.json` |
| Visual Studio Code (Copilot) | `vscode-copilot` | `.vscode/mcp.json` |
| Visual Studio (Copilot) | `vs-copilot` | `.vs/mcp.json` |
| Rider (Junie) | `rider-junie` | `.junie/mcp/mcp.json` |
| GitHub Copilot CLI | `github-copilot-cli` | `~/.copilot/mcp-config.json` |
| Gemini | `gemini` | `.gemini/settings.json` |
| Antigravity | `antigravity` | `~/.gemini/config/mcp_config.json` and `~/.gemini/antigravity/mcp_config.json` |
| Cline | `cline` | `cline_mcp_settings.json` in VS Code's global storage |
| Open Code | `open-code` | `opencode.json` |
| Codex | `codex` | `.codex/config.toml` |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` |
| Any other MCP client | `custom` | `mcp.json` in the project |

Examples:

```bash
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:

```bash
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](https://ai-game.dev/mcp-endpoint-info).

---

Source (HTML): https://ai-game.dev/docs/wiki/godot/connecting-ai-clients