# Configuração — Godot · AI Game Developer Wiki

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_*.

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

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](https://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](https://ai-game.dev/pt-br/docs/wiki/godot/connecting-ai-clients#custom-mode).

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](https://ai-game.dev/pt-br/docs/wiki/godot/extensions).

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

**Aviso**

Este arquivo armazena tokens como JSON puro. Não faça commit, sincronize nem compartilhe esse arquivo. Para rotacionar um token, saia ou limpe-o no dock (ou exclua o arquivo) e conecte novamente.

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

```bash
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ável | Valores | Finalidade |
| --- | --- | --- |
| `GODOT_MCP_CONNECTION_MODE` | `Cloud`, `Custom` | Força o modo de conexão. Padrão `Cloud`. |
| `GODOT_MCP_CLOUD_URL` | URL | Substitui a URL base da nuvem. Padrão `https://ai-game.dev`. |
| `GODOT_MCP_HOST` | URL | A URL do servidor no modo Custom. Padrão `http://localhost:8080`. |
| `GODOT_MCP_AUTH_OPTION` | `none`, `oauth`, `token` | Autorização do modo Custom. |
| `GODOT_MCP_TOKEN` | string | Bearer token do modo ativo. Substitui o token salvo e nunca é gravado de volta. |
| `GODOT_MCP_LOG_LEVEL` | `Trace` a `None` | Verbosidade do log. |
| `GODOT_MCP_CREDENTIALS_DIR` | caminho absoluto | Usa um armazenamento de credenciais separado, para testes isolados. |
| `GODOT_MCP_TOOL_FORMAT` | `Rql`, `Json` | Como as ferramentas recebem argumentos e retornam resultados. Padrão `Rql` (texto compacto); `Json` mantém os schemas e resultados JSON. |
| `GODOT_MCP_SERVER_PATH` | caminho absoluto | Somente no editor: inicia este binário de servidor já existente em vez de baixar a versão fixada. |
| `GODOT_MCP_RUNTIME_FROM_EDITOR` | `1` | Permite 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.

```bash
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](https://ai-game.dev/pt-br/docs/wiki/godot/cli#open).

## 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](https://ai-game.dev/pt-br/docs/wiki/godot/tools#rql).

---

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

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