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

Configuração

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

Atualizado em 4 de novembro de 2026 Ver como Markdown

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:

<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çãoO que você pode fazer
CabeçalhoEscolha 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ãoAlterne 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 IAEscolha 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õesVeja 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 e as extensões em Extensões.

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ávelFinalidade
UNREAL_MCP_CONNECTION_MODECloud (padrão) ou Custom
UNREAL_MCP_HOSTURL do servidor no modo Custom, por exemplo http://localhost:<port>
UNREAL_MCP_CLOUD_URLURL base da nuvem; o padrão é ai-game.dev
UNREAL_MCP_TOKENToken de autenticação. Um segredo: nunca faça commit dele
UNREAL_MCP_AUTH_OPTIONAutenticação no modo Custom: none, token ou oauth (o valor mais antigo required é lido como token)
UNREAL_MCP_KEEP_CONNECTEDRestaura a conexão automaticamente ao iniciar (padrão true)
UNREAL_MCP_TOOLSWhitelist de ferramentas a servir; vazio significa sem filtro
UNREAL_MCP_START_SERVERtrue: o editor inicia o servidor local por conta própria (modo Custom, somente http) e o encerra ao sair
UNREAL_MCP_TRANSPORThttp ou stdio
UNREAL_MCP_LOG_LEVELVerbosidade do log
UNREAL_MCP_TOOL_TIMEOUTTempo máximo para uma chamada de ferramenta, em milissegundos; padrão 300000 (5 minutos)
UNREAL_MCP_BRIDGE_PATHCaminho para um binário da bridge; um override de desenvolvedor que tem precedência sobre o binário incluído
UNREAL_MCP_SERVER_PATHCaminho 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:

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.

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

Credenciais e chaves no disco

ArquivoConteúdo
~/.ai-game-dev/credentials.jsonO login do ai-game.dev em toda a máquina, compartilhado com o app, os plugins e as CLIs
~/.ai-game-dev/project-keys.jsonChaves de projeto em cache usadas nas configurações de MCP Cloud
<project>/Saved/Config/UnrealMcp/ai-game-developer-config.jsonAs configurações do plugin por projeto
<project>/.envOverrides 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.