Esta página foi traduzida automaticamente do inglês. Leia o original em inglês.

Configuração

Configure o Godot MCP no dock do AI Game Developer, escolha as ferramentas visíveis aos agentes e substitua ajustes com variáveis GODOT_MCP_*.

Atualizado em 4 de novembro de 2026 Ver como Markdown

A maioria das pessoas nunca altera uma configuração: o addon inicia no modo Cloud, conecta depois que você faz login e expõe todas as suas ferramentas. Esta página descreve o que você pode alterar quando precisar, no dock AI Game Developer, nas configurações salvas e por meio de variáveis de ambiente para CI e execuções por script.

O dock do AI Game Developer

O addon adiciona um dock chamado AI Game Developer à área de docks superior direita do editor Godot. De cima para baixo, ele tem estas seções.

Cabeçalho

O cabeçalho mostra a versão do addon e um seletor Log Level. O nível de log controla o quanto o addon e sua conexão imprimem no painel Output (Trace, Debug, Info, Warning, Error, None; padrão Info). Aumente para Debug ou Trace quando estiver diagnosticando um problema de conexão. Quando GODOT_MCP_LOG_LEVEL está definido, o seletor fica desabilitado e uma nota indica isso.

Conexão

  • Cloud / Custom: o modo de conexão. Cloud conecta a ai-game.dev; Custom conecta a uma URL de servidor que você escolher.
  • Connect / Stop: inicia ou para a conexão com o servidor MCP. O addon continua tentando em segundo plano até conectar.
  • No modo Cloud: seu status de login, com Authorize (inicia o login de dispositivo pelo navegador) e Sign out.
  • Uma linha de três pontos — Godot, servidor MCP e agente de IA — que mostra o que está conectado. A linha do agente de IA lista os clientes conectados por nome, ou diz "(conecta sob demanda)" quando nenhum está conectado ainda.

No modo Custom, um cartão MCP server adiciona:

  • Server URL: o servidor ao qual se conectar, padrão http://localhost:8080.
  • Authorization Token: none, oauth (o token da sua conta ai-game.dev, enviado apenas a um servidor localhost) ou token (um bearer token; New gera um).
  • Start Server / Stop Server: baixa, inicia e para um servidor local que corresponde à versão de servidor fixada do addon. Veja Conectando clientes de IA.

Se uma variável de ambiente forçar o modo ou o host, uma nota amarela exibe "Substituído pelo ambiente (GODOT_MCP_*)" e as alterações no dock não têm efeito.

Agente de IA

Escolha o cliente de IA que você usa (Claude Code é o padrão). A seção então mostra:

  • Skills: onde os arquivos de skill do agente ficam, um interruptor Auto-generate que os atualiza quando o addon carrega, e um botão Generate. Agentes sem suporte a skills mostram "Skills não suportadas por este agente".
  • Model Context Protocol (MCP): se a configuração MCP do agente está definida, com Configure / Reconfigure e Remove. Um aviso Reconfiguration Required aparece quando as configurações do servidor mudaram depois que você configurou o agente.

Recursos do MCP

Três linhas, Tools, Prompts e Resources, cada uma com uma contagem de itens visíveis em relação ao total (as ferramentas também mostram um custo estimado em tokens) e um botão Open. A janela que abre lista todos os itens com um interruptor Visible e um campo de filtro.

Visible só decide se os clientes MCP veem o item na lista de ferramentas deles. Ocultar ferramentas que você não precisa mantém o contexto do agente menor. Isso não é controle de acesso: uma ferramenta oculta ainda é executada se um cliente a chamar pelo nome.

Extensões

A lista de extensões opcionais do Godot MCP com botões Install e Update. Ela lê o catálogo de extensões incorporado ao seu .csproj; se a lista estiver vazia, veja Extensões.

Rodapé

Links para ajuda e relato de problemas, e uma janela Serialization Check que mostra como um nó ou objeto selecionado é serializado para a IA (útil ao relatar um bug).

Onde as configurações são salvas

O dock salva suas configurações em user://godot-mcp-config.json, na pasta de dados por usuário do Godot para o projeto (não dentro do projeto). Ele contém o modo de conexão, host customizado, opção de autorização, nível de log, agente selecionado, visibilidade das ferramentas e os tokens que você usou.

As credenciais de login do Cloud ficam separadas, no armazenamento da máquina ~/.ai-game-dev/credentials.json, compartilhado com as outras ferramentas do AI Game Developer. As chaves de projeto para configurações de agentes ficam em ~/.ai-game-dev/project-keys.json.

Em um terminal, godot-cli configure lista e altera a visibilidade de ferramentas, prompts e recursos no arquivo do projeto .godot-mcp/features.json:

godot-cli configure ./MyGodotProject --list
godot-cli configure ./MyGodotProject --disable-tools script-delete,script-execute
godot-cli configure ./MyGodotProject --enable-all-tools

Variáveis de ambiente

As variáveis de ambiente substituem as configurações salvas sem editar nenhum arquivo, o que é útil para CI, execuções headless e desenvolvimento local. O addon também as lê de um arquivo .env no projeto; o ambiente do processo tem precedência sobre o .env.

VariávelValoresFinalidade
GODOT_MCP_CONNECTION_MODECloud, CustomForça o modo de conexão. Padrão Cloud.
GODOT_MCP_CLOUD_URLURLSubstitui a URL base da nuvem. Padrão https://ai-game.dev.
GODOT_MCP_HOSTURLA URL do servidor no modo Custom. Padrão http://localhost:8080.
GODOT_MCP_AUTH_OPTIONnone, oauth, tokenAutorização do modo Custom.
GODOT_MCP_TOKENstringBearer token do modo ativo. Substitui o token salvo e nunca é gravado de volta.
GODOT_MCP_LOG_LEVELTrace a NoneVerbosidade do log.
GODOT_MCP_CREDENTIALS_DIRcaminho absolutoUsa um armazenamento de credenciais separado, para testes isolados.
GODOT_MCP_TOOL_FORMATRql, JsonComo as ferramentas recebem argumentos e retornam resultados. Padrão Rql (texto compacto); Json mantém os schemas e resultados JSON.
GODOT_MCP_SERVER_PATHcaminho absolutoSomente no editor: inicia este binário de servidor já existente em vez de baixar a versão fixada.
GODOT_MCP_RUNTIME_FROM_EDITOR1Permite que um jogo iniciado com Play conecte também seu próprio runtime MCP dentro do jogo.

Exemplo: iniciar o editor apontando para um servidor local.

export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
godot --editor --path ./MyGodotProject

godot-cli open define essas variáveis para você com --mode, --url, --cloud-url, --token, --auth e --log-level. Veja a referência do godot-cli.

Formato das ferramentas

Com o formato padrão Rql, as ferramentas recebem valores RQL como argumentos (um caminho de nó como "Level/Player", ou godot.find("Name")) e retornam texto compacto, que gasta menos tokens. O formato Json, definido com GODOT_MCP_TOOL_FORMAT=Json ou a chave toolFormat, mantém os schemas JSON completos e resultados estruturados para os clientes que preferem isso. Mais sobre RQL: Ferramentas.