# Conectando clientes de IA — Godot · AI Game Developer Wiki

Conecte Claude Code, Cursor, Copilot, Codex, Gemini e outros clientes MCP ao Godot MCP via nuvem do ai-game.dev ou servidor local.

Esta página foi traduzida automaticamente do inglês. [Leia o original em inglês](https://ai-game.dev/docs/wiki/godot/connecting-ai-clients).

O Godot MCP tem dois lados que se conectam a um servidor MCP: o addon no editor Godot e o cliente de IA com o qual você conversa. Esta página explica os dois modos de conexão, como o login funciona e como escrever a configuração MCP para cada agente compatível com `godot-cli setup-mcp` ou com o botão **Configure** do dock.

## Modo nuvem (padrão)

No modo nuvem, o addon se conecta ao backend hospedado em `https://ai-game.dev`, e seu cliente de IA se conecta ao endpoint MCP `https://ai-game.dev/mcp`. Nada extra é executado na sua máquina e funciona através de firewalls. Este é o modo padrão e o que recomendamos para a maioria das pessoas.

### Login com o fluxo de dispositivo

A autenticação na nuvem usa o fluxo de autorização de dispositivo do OAuth 2.1. Você nunca copia um token manualmente:

```bash
godot-cli login
```

A CLI imprime um código curto, abre seu navegador e espera até que você o aprove. A credencial (access token, refresh token rotativo e expiração) é salva no armazenamento da máquina `~/.ai-game-dev/credentials.json` (modo de arquivo 0600 no macOS e Linux, protegida por DPAPI no Windows). O addon do editor, as CLIs das outras engines e o app AI Game Dev a utilizam, e os access tokens expirados são renovados automaticamente. Clicar em **Authorize** no dock executa o mesmo fluxo de dentro do Godot.

Flags úteis do `login`: `--force` faz login novamente sobre uma credencial existente, `--project <path>` mantém uma credencial separada por projeto e `--tools-only` cria uma credencial mais restrita para runners de CI. Veja a [referência do godot-cli](https://ai-game.dev/pt-br/docs/wiki/godot/cli#login) e [Autenticação](https://ai-game.dev/docs/auth).

### URLs de projeto fixadas

O endpoint simples `https://ai-game.dev/mcp` encaminha seu agente para um dos seus editores conectados. Isso é ambíguo quando vários projetos estão abertos, então `setup-mcp` grava por padrão uma URL fixada: `https://ai-game.dev/mcp/p/<pin>`, em que o pin é derivado do projeto. Um agente iniciado com essa configuração sempre chega ao editor deste projeto. Passe `--no-pin` se quiser a URL simples.

### Chaves de projeto

Quando você está conectado, `setup-mcp` insere uma chave de projeto na configuração do agente como `Authorization: Bearer agd_pk_…`. Uma chave de projeto não expira e funciona apenas para o pin deste projeto, portanto não consegue alcançar outros projetos da sua conta. Ela é criada uma vez por projeto e reutilizada a partir de `~/.ai-game-dev/project-keys.json`.

- `--regenerate-key` cria uma nova chave, reescreve a configuração e revoga a chave antiga.
- `--oauth` grava, em vez disso, uma configuração somente com URL: o agente faz login com seu próprio prompt OAuth.
- Sem login na máquina, a configuração também fica somente com URL.

**Aviso**

Uma chave de projeto é uma credencial. Não faça commit de arquivos de configuração que contenham uma (por exemplo, `.mcp.json` ou `.cursor/mcp.json`) em um repositório público.

## Modo personalizado: seu próprio servidor

No modo personalizado, o addon se conecta a uma URL de servidor que você escolher, por exemplo um servidor na sua própria máquina. O servidor é o [GameDev-MCP-Server](https://github.com/IvanMurzak/GameDev-MCP-Server) de código aberto, o mesmo binário usado pelo Unity MCP e pelo Unreal MCP.

A maneira mais fácil é deixar o addon executá-lo:

1. No dock, mude o modo para **Custom**.
2. Deixe **Server URL** em `http://localhost:8080` ou informe outra URL local.
3. Clique em **Start Server**. O addon baixa do GitHub a build do servidor correspondente à sua versão de servidor fixada (HTTPS, somente github.com), guarda em cache em `.godot/mcp-server/<platform>/`, inicia o servidor e se conecta.

**Stop Server** o encerra, e fechar o editor também o encerra. Os downloads são ignorados em ambientes de CI. Para executar um servidor por conta própria, baixe um binário de release ou a imagem Docker `aigamedeveloper/mcp-server`:

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

### Autorização para um servidor personalizado

O modo personalizado tem uma opção **Authorization Token** com três valores:

| Valor | Significado |
| --- | --- |
| `none` | Sem autenticação. Adequado para um servidor que escuta apenas na sua própria máquina. |
| `oauth` | Envia o token da sua conta ai-game.dev autenticada, mas apenas para um servidor localhost (`localhost`, `127.0.0.0/8`, `::1`). |
| `token` | Um bearer token. Clique em **New** para gerar um; ele é armazenado de forma mascarada. |

Para qualquer host não local com `oauth`, o addon se recusa a enviar o token da sua conta; defina `GODOT_MCP_TOKEN` em vez disso. As variáveis de ambiente para os dois modos estão listadas em [Configuração](https://ai-game.dev/pt-br/docs/wiki/godot/configuration#environment-variables).

Para apontar um agente a um servidor local, passe a URL para `setup-mcp`:

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

Uma configuração de servidor local nunca carrega uma chave de projeto.

## Agentes compatíveis e arquivos de configuração

Execute `godot-cli setup-mcp --list` para ver todos os ids de agente. Estes são os ids que a CLI atual conhece e onde ela grava a configuração:

| Agente | id | Arquivo de configuração |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json` no projeto |
| Claude Desktop | `claude-desktop` | Use um conector personalizado do Claude (veja abaixo) |
| 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` e `~/.gemini/antigravity/mcp_config.json` |
| Cline | `cline` | `cline_mcp_settings.json` no armazenamento global do VS Code |
| Open Code | `open-code` | `opencode.json` |
| Codex | `codex` | `.codex/config.toml` |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` |
| Qualquer outro cliente MCP | `custom` | `mcp.json` no projeto |

Exemplos:

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

Toda configuração usa o transporte HTTP (`type: http` e uma URL). No Codex, a chave vai em `http_headers`.

### Claude Desktop e claude.ai

O Claude Desktop não aceita uma entrada de servidor HTTP no `claude_desktop_config.json`. O Claude Desktop e o claude.ai acessam o endpoint na nuvem como um conector personalizado do Claude: adicione um conector personalizado nas configurações do Claude, cole a URL fixada do projeto na nuvem e entre com sua conta ai-game.dev. O Claude Desktop não consegue usar um servidor em modo Custom, porque o Godot MCP não oferece transporte stdio para ele. Para um servidor local, use um agente da tabela que ofereça suporte a HTTP, como o Claude Code.

## Configurar pelo dock

A seção **AI agent** do dock faz o mesmo trabalho que o `setup-mcp`: escolha seu agente na lista e clique em **Configure** (ou **Reconfigure**). A linha de status informa se o arquivo de configuração do agente está definido, e um aviso **Reconfiguration Required** aparece quando você altera a URL do servidor, o modo ou a autorização após a configuração. **Remove** exclui a entrada do Godot MCP da configuração desse agente.

## Skills para seu agente

Alguns agentes leem arquivos de skill (`SKILL.md`) que ensinam como usar as ferramentas. A linha **Skills** do dock, dentro da seção AI agent, pode gerá-los (**Generate**, ou a opção **Auto-generate**). Pelo terminal:

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

Isso grava os arquivos na pasta de skills do agente, como `.claude/skills` para o Claude Code, sem precisar do editor em execução. `setup-skills --list` mostra quais agentes oferecem suporte a skills.

## Configurações para copiar e colar

Se seu cliente não estiver na lista, qualquer cliente MCP que ofereça suporte a servidores HTTP funciona: aponte-o para `https://ai-game.dev/mcp` (ou para a URL fixada) e deixe que ele entre com OAuth, ou adicione um cabeçalho bearer. Trechos prontos para muitos clientes estão na [página do endpoint MCP](https://ai-game.dev/pt-br/mcp-endpoint-info).

---

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

Machine-translated (pt-BR) from the English page: https://ai-game.dev/docs/wiki/godot/connecting-ai-clients