# Conectando clientes de IA — Unreal Engine · AI Game Developer Wiki

Conecte Claude Code, Cursor, Copilot, Codex, Gemini e outros clientes MCP ao Unreal MCP via endpoint na nuvem do ai-game.dev ou servidor local.

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

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](https://ai-game.dev/pt-br/docs/wiki/unreal/getting-started#ai-client)) 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](https://ai-game.dev/pt-br/docs/wiki/unreal/configuration)).

|  | Cloud (padrão) | Custom |
| --- | --- | --- |
| Servidor | O endpoint hospedado em ai-game.dev | Um `gamedev-mcp-server` que você executa, geralmente em `localhost` |
| Login | Sua conta ai-game.dev, fluxo de código de dispositivo | Opcional: nenhum, um token compartilhado ou OAuth |
| O que roda localmente | O editor e sua ponte | O editor, sua ponte e o servidor local |
| Indicado para | A maioria dos usuários, várias máquinas, trabalho através de firewalls | Configurações totalmente locais, trabalho offline, CI |

## 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](https://ai-game.dev/pt-br/mcp-endpoint-info) 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](https://ai-game.dev/docs/auth).

### 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**:

```text
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`).

```bash
# 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

| Agente | ID do `setup-mcp` | Arquivo de configuração |
| --- | --- | --- |
| Claude Code | `claude-code` | `.mcp.json` (projeto) |
| Claude Desktop | `claude-desktop` | `claude_desktop_config.json` (usuário) |
| Cursor | `cursor` | `.cursor/mcp.json` (projeto) |
| Visual Studio Code (Copilot) | `vscode-copilot` | `.vscode/mcp.json` (projeto) |
| Visual Studio (Copilot) | `vs-copilot` | `.vs/mcp.json` (projeto) |
| Rider (Junie) | `rider-junie` | `.junie/mcp/mcp.json` (projeto) |
| GitHub Copilot CLI | `github-copilot-cli` | `~/.copilot/mcp-config.json` (usuário) |
| Gemini | `gemini` | `.gemini/settings.json` (projeto) |
| Antigravity | `antigravity` | `mcp_config.json` em `~/.gemini/` (usuário) |
| Cline | `cline` | `cline_mcp_settings.json` no armazenamento global do VS Code (usuário) |
| Open Code | `open-code` | `opencode.json` (projeto) |
| Codex | `codex` | `.codex/config.toml` (projeto) |
| Kilo Code | `kilo-code` | `.kilocode/mcp.json` (projeto) |
| Qualquer outro cliente MCP | `custom` | `mcp.json` (projeto) |

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](https://ai-game.dev/pt-br/mcp-endpoint-info). A [visão geral do ecossistema](https://ai-game.dev/pt-br/docs/ecosystem) mostra como o servidor, os plugins e o app funcionam juntos.

---

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

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