Conectando clientes de IA

Esta página explica como um cliente de IA chega até o seu Unreal Editor, como funciona o login e como escrever a configuração MCP para cada agente suportado. Se você quer apenas o caminho mais rápido, o botão Configure na seção AI agent do editor (veja Primeiros passos) faz tudo isso por você.

Cloud ou Custom: escolha um modo de conexão#

A seção Connection da janela do AI Game Developer tem um seletor Custom / Cloud. A mesma configuração é UNREAL_MCP_CONNECTION_MODE (veja Configuração).

Modo Cloud#

No modo Cloud, a ponte se conecta a ai-game.dev e seu cliente de IA se conecta ao mesmo endpoint, https://ai-game.dev/mcp. O servidor roteia as chamadas de ferramentas do cliente para o seu editor. Veja a página do endpoint MCP para o endpoint em si.

Entrar com o fluxo de código de dispositivo#

Você faz login uma vez por máquina. Qualquer uma destas opções funciona, e todas compartilham um único armazenamento de credenciais (~/.ai-game-dev/credentials.json) com o app, os outros plugins de engine e as CLIs:

• No editor: escolha Cloud, clique em Authorize, abra a página de verificação, insira o código de usuário exibido na janela e aprove.
• Em um terminal: unreal-mcp-cli login.
• No app AI Game Dev: faça login como de costume.

Aviso: Revoke no editor desconecta a máquina inteira, não apenas este projeto. O editor pede confirmação antes, porque todas as ferramentas do AI Game Dev que compartilham a credencial (plugins de engine, CLIs e o app desktop) são desconectadas.

Como funcionam contas, dispositivos e tokens está na página de autenticação.

URLs fixadas ao projeto#

Se sua conta tem vários editores conectados, um cliente usando a URL simples https://ai-game.dev/mcp pode chegar ao editor errado. Por isso o plugin e o unreal-mcp-cli setup-mcp gravam por padrão uma URL fixada ao projeto:

https://ai-game.dev/mcp/p/<pin>

A fixação é derivada da pasta do projeto, então o cliente sempre roteia para o editor deste projeto. Use setup-mcp --no-pin para gravar a URL simples em vez disso.

Chaves de projeto#

Quando a máquina está conectada, uma configuração Cloud também carrega uma project key, um cabeçalho Authorization: Bearer agd_pk_… vinculado a este projeto. Com ela, o agente não precisa de login próprio. A chave não expira, pode ser revogada e fica em cache em ~/.ai-game-dev/project-keys.json para que todo agente do projeto a reutilize.

• setup-mcp --oauth grava uma configuração somente com URL; o agente então faz seu próprio login OAuth.
• setup-mcp --regenerate-key, ou o botão Regenerate key na seção AI agent do editor, cria uma nova chave, reescreve os agentes configurados com ela e revoga a antiga.
• Um --token explícito tem prioridade sobre ambos.

Se a máquina não estiver conectada, a configuração é somente com URL e o agente faz o login por conta própria.

Modo Custom: um servidor local#

No modo Custom, a ponte se conecta a um servidor que você controla, normalmente o gamedev-mcp-server compartilhado rodando na sua máquina. Cada projeto recebe uma porta local fixa na faixa de 20000 a 29999, derivada do caminho do projeto, para que o editor e a CLI concordem sobre ela sem qualquer configuração.

Para executá-lo a partir do editor:

1. Mude a seção Connection para Custom.
2. No card MCP server, escolha o transporte http e clique em Start. O editor baixa a versão fixada do servidor se ela estiver faltando, inicia-o e o encerra quando o editor fecha. O botão Start funciona apenas com o modo Custom e o transporte http.
3. Escolha um modo de Authorization: none (local, anônimo), token (um segredo compartilhado; New gera um, segure Reveal para vê-lo) ou oauth.

Para iniciá-lo a partir de um terminal, use unreal-mcp-cli open ./YourProject --start-server --connection-mode Custom, ou defina UNREAL_MCP_START_SERVER=true com unreal-mcp-cli configure.

Observação: Se você apontar um servidor local para o editor mas a janela ainda disser Cloud, a ponte se conecta a ai-game.dev e seu servidor local responde "No connected clients". Defina o modo Custom explicitamente. Passar --host para unreal-mcp-cli open seleciona Custom automaticamente.

Grave a configuração do cliente com setup-mcp#

unreal-mcp-cli setup-mcp <agent> grava uma entrada de configuração MCP para um agente. Ele lê as configurações de conexão salvas do projeto, então abra o projeto no editor uma vez primeiro (ou passe --url).

# Claude Code: writes .mcp.json in the project
unreal-mcp-cli setup-mcp claude-code --path ./YourProject

# Cursor, with the local server over stdio instead of http
unreal-mcp-cli setup-mcp cursor --path ./YourProject --transport stdio

# Print the snippet without writing anything
unreal-mcp-cli setup-mcp vscode-copilot --path ./YourProject --dry-run

# List every agent and its config path
unreal-mcp-cli setup-mcp --list

Com --transport stdio, a CLI baixa a versão fixada do gamedev-mcp-server para <project>/Intermediate/UnrealMCP/server/ e o agente inicia esse servidor por conta própria.

Agentes compatíveis#

O menu suspenso AI agent do editor oferece o mesmo tipo de configuração com um clique, além de Remove para excluir a entrada, links Tutorial e Download / Docs, e Generate skill files para agentes que suportam skills.

Claude Code e Unreal Engine#

O Claude Code lê o .mcp.json da pasta em que você o inicia. Então, para o Claude Code no Unreal:

1. Execute unreal-mcp-cli setup-mcp claude-code --path ./YourProject (ou Configure no editor com o Claude Code selecionado).
2. Inicie o Claude Code a partir da pasta do projeto.
3. Peça a ele para "list the actors in the current level" para confirmar que as ferramentas do Unreal estão disponíveis.

Opcionalmente, unreal-mcp-cli setup-skills --path ./YourProject grava uma skill do Claude Code (.claude/skills/unreal-mcp/SKILL.md) que ensina o Claude a operar o servidor MCP deste projeto.

Outros clientes#

Trechos de configuração prontos para muitos clientes, incluindo alguns não listados acima, estão na página do endpoint MCP. A visão geral do ecossistema mostra como o servidor, os plugins e o app funcionam juntos.