Conectando clientes de IA
Conecte Claude Code, Cursor, Copilot, Codex, Gemini e outros clientes MCP ao Godot MCP via nuvem do ai-game.dev ou servidor local.
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:
godot-cli loginA 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 e Autenticação.
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-keycria uma nova chave, reescreve a configuração e revoga a chave antiga.--oauthgrava, 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.
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 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:
- No dock, mude o modo para Custom.
- Deixe Server URL em
http://localhost:8080ou informe outra URL local. - 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:
./gamedev-mcp-server --client-transport streamableHttp --port 8080Autorizaçã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.
Para apontar um agente a um servidor local, passe a URL para setup-mcp:
godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:8080Uma 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:
godot-cli setup-mcp cursor ./MyGodotProject
godot-cli setup-mcp codex ./MyGodotProject
godot-cli setup-mcp vscode-copilot ./MyGodotProject --oauthToda 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:
godot-cli setup-skills claude-code ./MyGodotProjectIsso 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.