# Configuração — Unreal Engine · AI Game Developer Wiki

Configure o Unreal MCP: janela AI Game Developer, visibilidade em MCP Tools, arquivo de config do projeto, .env e variáveis UNREAL_MCP_*.

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

Esta página lista todas as configurações que o Unreal MCP tem hoje e onde alterá-las. A maioria das pessoas só mexe no modo de conexão e na configuração do agente de IA; o resto é para ajuste fino, automação e CI.

## Onde ficam as configurações

O Unreal MCP não tem página de Project Settings para a conexão do editor. Tudo fica na janela **AI Game Developer** (menu Tools) e é salvo por projeto em:

```text
<YourProject>/Saved/Config/UnrealMcp/ai-game-developer-config.json
```

`Saved/` é ignorado pelo controle de versão em todos os templates de projeto Unreal, então tokens nesse arquivo não vão parar no seu repositório por padrão.

As configurações são lidas nesta ordem, da maior prioridade para a menor:

1. Variáveis de ambiente do processo (por exemplo, definidas por `unreal-mcp-cli open` ou pelo seu shell).
2. Um arquivo `.env` na raiz do projeto.
3. O arquivo de configuração acima.
4. Os padrões internos.

Valores vindos do ambiente ou do `.env` substituem o arquivo naquela sessão, mas nunca são gravados de volta nele.

## A janela AI Game Developer

| Seção | O que você pode fazer |
| --- | --- |
| Cabeçalho | Escolha o **Log Level** (Trace, Debug, Info, Warning, Error, Exception, None), abra a pasta de logs do projeto com **Open log file** e veja a **Version** do plugin |
| Conexão | Alterne entre **Custom / Cloud**; no modo Cloud, **Authorize**, **Cancel** ou **Revoke**; no modo Custom, defina a **Server URL**; **Connect / Disconnect / Stop**; veja o status do Unreal, do servidor MCP e dos agentes de IA conectados, além da porta da bridge IPC |
| Servidor MCP (modo Custom) | **Start / Stop** do `gamedev-mcp-server` local, escolha o **Transport** (http ou stdio) e o modo de **Authorization** (none, token, oauth), gere um token com **New** |
| Agente de IA | Escolha um agente e então **Configure**, **Reconfigure** ou **Remove** a entrada MCP dele; abra o **Tutorial** ou **Download / Docs**; **Generate skill files**; **Regenerate key** para a chave do projeto |
| Extensões | Veja extensões instaladas e disponíveis, **Refresh catalog**, **Install** ou **Update**, ative ou desative uma extensão em tempo real, **Compile (Live Coding)** |
| Rodapé | **Help / Talk** (Discord), **Bug Report** (GitHub), **GitHub Star** e **Restart bridge** |

Detalhes de conexão estão em [Connecting AI clients](https://ai-game.dev/pt-br/docs/wiki/unreal/connecting-ai-clients) e as extensões em [Extensões](https://ai-game.dev/pt-br/docs/wiki/unreal/extensions).

## A janela MCP Tools: visibilidade por ferramenta

Abra **Tools** e depois **MCP Tools**. A janela lista todas as ferramentas registradas com título, família e descrição, uma caixa **Visible** por ferramenta e um resumo como "27 / 27 tools visible".

- **Visible** decide se uma ferramenta é listada para os agentes de IA em `tools/list`. Ocultar ferramentas de que você não precisa mantém a lista de ferramentas do agente curta e economiza tokens.
- Isso **não** é controle de acesso. Uma ferramenta oculta continua sendo executada quando um cliente a chama pelo nome, e `unreal-tool-list` mostra as ferramentas ocultas (marcadas como hidden) para que o agente possa encontrá-las.
- A escolha é salva como `hiddenTools` e sobrevive a reinicializações do editor e recarregamentos de extensões.

Para impedir que uma ferramenta seja servida de vez, use a whitelist `UNREAL_MCP_TOOLS` abaixo.

## Outras janelas

O menu Tools também tem as janelas **MCP Prompts** e **MCP Resources**. Na versão atual, elas mostram uma mensagem de estado vazio; prompts e resources registrados pelo plugin ou por extensões continuam funcionando para os clientes de IA. Uma janela **Serialization Check** serializa um ator ou objeto selecionado para JSON, para você inspecionar o que as ferramentas veem.

## Variáveis de ambiente

O plugin lê estas variáveis `UNREAL_MCP_*` do ambiente do processo ou do arquivo `.env` do projeto:

| Variável | Finalidade |
| --- | --- |
| `UNREAL_MCP_CONNECTION_MODE` | `Cloud` (padrão) ou `Custom` |
| `UNREAL_MCP_HOST` | URL do servidor no modo Custom, por exemplo `http://localhost:<port>` |
| `UNREAL_MCP_CLOUD_URL` | URL base da nuvem; o padrão é ai-game.dev |
| `UNREAL_MCP_TOKEN` | Token de autenticação. Um segredo: nunca faça commit dele |
| `UNREAL_MCP_AUTH_OPTION` | Autenticação no modo Custom: `none`, `token` ou `oauth` (o valor mais antigo `required` é lido como `token`) |
| `UNREAL_MCP_KEEP_CONNECTED` | Restaura a conexão automaticamente ao iniciar (padrão true) |
| `UNREAL_MCP_TOOLS` | Whitelist de ferramentas a servir; vazio significa sem filtro |
| `UNREAL_MCP_START_SERVER` | `true`: o editor inicia o servidor local por conta própria (modo Custom, somente http) e o encerra ao sair |
| `UNREAL_MCP_TRANSPORT` | `http` ou `stdio` |
| `UNREAL_MCP_LOG_LEVEL` | Verbosidade do log |
| `UNREAL_MCP_TOOL_TIMEOUT` | Tempo máximo para uma chamada de ferramenta, em milissegundos; padrão `300000` (5 minutos) |
| `UNREAL_MCP_BRIDGE_PATH` | Caminho para um binário da bridge; um override de desenvolvedor que tem precedência sobre o binário incluído |
| `UNREAL_MCP_SERVER_PATH` | Caminho para um `gamedev-mcp-server` local; lido pelo `unreal-mcp-cli`, que pula o download do servidor |

**Dica:** Aumente `UNREAL_MCP_TOOL_TIMEOUT` se scripts longos de `python-execute` ou importações grandes de assets estourarem o tempo. Uma chamada de ferramenta que expira antes de o editor iniciá-la é ignorada, não executada depois.

## Escrever o .env com a CLI

`unreal-mcp-cli configure` grava estes valores em `<project>/.env` e adiciona `.env` ao `.gitignore` do projeto:

```bash
unreal-mcp-cli configure --path ./YourProject --mode Custom --host http://localhost:23456 --start-server
```

Os templates de projeto Unreal vêm sem um `.gitignore`, então o comando cria um se necessário. Passe `--no-gitignore` para não mexer nele. Todas as flags estão na [referência da CLI](https://ai-game.dev/pt-br/docs/wiki/unreal/cli#configure).

**Aviso:** Nunca faça commit do `.env`. Ele pode conter `UNREAL_MCP_TOKEN`.

## Credenciais e chaves no disco

| Arquivo | Conteúdo |
| --- | --- |
| `~/.ai-game-dev/credentials.json` | O login do ai-game.dev em toda a máquina, compartilhado com o app, os plugins e as CLIs |
| `~/.ai-game-dev/project-keys.json` | Chaves de projeto em cache usadas nas configurações de MCP Cloud |
| `<project>/Saved/Config/UnrealMcp/ai-game-developer-config.json` | As configurações do plugin por projeto |
| `<project>/.env` | Overrides opcionais, nunca versionados |

## Portas

- O servidor MCP local usa uma porta fixa por projeto, entre 20000 e 29999, calculada a partir do caminho do projeto. A CLI calcula o mesmo número, então não é preciso configurar nada.
- O plugin e sua bridge se comunicam por uma porta de loopback entre 30000 e 39999 (a próxima livre em caso de colisão). A janela a mostra como "IPC bridge port".

Você nunca precisa abrir essas portas para a rede; ambas são locais.

---

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

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