Unreal-MCP

Servidor MCP de código aberto que conecta agentes de IA ao Unreal Engine 5.7, editor e runtime (plugin C++ + sidecar .NET).

GitHub

Experimente este MCPPatrocinado

Documentação

✨ AI Game Developer — Unreal MCP

Unreal MCP é um assistente de desenvolvimento de jogos com IA para o Unreal Editor. Conecte Claude, Cursor, Copilot ou qualquer agente compatível com MCP ao Unreal Engine e deixe-o inspecionar e conduzir seu projeto — criar atores, editar níveis, criar Blueprints, gerenciar assets, editar e compilar C++, capturar screenshots e muito mais.

Unreal-MCP é a contraparte do Unreal Engine do Unity-MCP e do Godot-MCP: um plugin de editor em C++ que expõe operações do Unreal Editor como AI Tools e as conecta a um servidor MCP através do mesmo backend hospedado em nuvem (ai-game.dev) que alimenta Unity-MCP e Godot-MCP — ou seu próprio servidor auto-hospedado. O servidor local é o GameDev-MCP-Server compartilhado e agnóstico de engine (binário gamedev-mcp-server) — um único servidor consumido por Unity-MCP, Godot-MCP e Unreal-MCP; nenhum código-fonte do servidor vive neste repositório.

Ao contrário de Unity e Godot (engines em C# que hospedam o McpPlugin .NET em processo), o editor do Unreal é C++ — então o host MCP .NET roda como um processo sidecar gerenciado automaticamente (unreal-mcp-bridge) que o plugin inicia e com o qual se comunica através de um canal IPC em localhost. O design completo está em docs/ARCHITECTURE.md (veja o diagrama de visão geral do sistema na §0).

Status: beta. O plugin, o sidecar .NET, o unreal-mcp-cli, a interface do editor AI Game Developer e 61 ferramentas integradas em 7 famílias (mais 3 ferramentas de sistema) foram lançados e são exercitados pela CI. O unreal-mcp-cli está publicado no npm — instale o plugin com ele (Opção B abaixo); a listagem no Fab / Epic Marketplace para o plugin pré-compilado está chegando em breve (Opção A). As ferramentas de captura de pixels (screenshots) precisam de um editor com GPU; todo o resto roda headless.

💬 Junte-se ao nosso servidor Discord — Tire dúvidas, mostre seu trabalho e conecte-se com outros desenvolvedores!

✔️ Agentes de IA — Use os melhores agentes da Anthropic, OpenAI, Google ou qualquer outro provedor sem ficar preso a um fornecedor
✔️ 61 ferramentas integradas — Uma ampla gama de MCP Tools em 7 famílias para operar o Unreal Editor
✔️ Criação de Blueprints — Crie, edite e compile Blueprints com um loop de feedback estruturado de erros/avisos no qual a IA pode agir
✔️ Edição e compilação de C++ — Leia, crie a estrutura e edite o C++ do projeto, depois compile (Live Coding ou UBT) com um relatório de erros estruturado
✔️ Feedback visual — Capture screenshots do viewport, da visão do jogo, da câmera e de atores isolados que o LLM pode inspecionar diretamente
✔️ Ferramentas, Prompts e Recursos personalizados — Registre suas próprias AI Tools, modelos de prompt e recursos de qualquer plugin UE sem fork — um contrato público e modular de recursos (Personalize Ferramentas, Prompts e Recursos)
✔️ Nuvem ou auto-hospedado — Conecte-se ao ai-game.dev imediatamente, ou aponte para seu próprio GameDev-MCP-Server
✔️ Ativar/desativar por ferramenta — Ative ou desative qualquer ferramenta na janela MCP Tools; a alternância é aplicada no limite de execução, não apenas ocultada

AI Game Developer — Unreal MCP

Sumário

Requisitos
Instalação
Atualizando o plugin
Primeira execução
Ferramentas — todas as 7 famílias, 61 ferramentas (+ 3 ferramentas de sistema)
Ativar/desativar por ferramenta
unreal-mcp-cli
Personalize Ferramentas, Prompts e Recursos
Uso em tempo de execução (no jogo)
- Somente editor — exclua Unreal-MCP de jogos empacotados
Configuração e variáveis de ambiente
Solução de problemas
Como a Arquitetura do Unreal MCP Funciona
Estrutura do repositório
Links
Licença

AI Game Developer — Unreal MCP

Requisitos

Unreal Engine 5.5+ (desenvolvido e testado pela CI contra 5.7, e verificado para compilar e rodar no 5.8). O plugin deliberadamente não inclui nenhum pin de EngineVersion — a UE trata esse campo como uma correspondência exata de build, não um piso, e se recusaria a carregar em engines mais novos.
.NET 9 SDK para compilar o sidecar da ponte a partir do código-fonte. (Usuários finais de uma versão empacotada NÃO precisam disso — o sidecar autocontido está incluído dentro do plugin e é iniciado automaticamente, ARQUITETURA §6. O servidor MCP local é baixado como um binário de release pré-compilado do GameDev-MCP-Server, nunca compilado aqui.)
Node.js ^20.19.0 || >=22.12.0 para o unreal-mcp-cli opcional.
Um projeto Unreal em C++ (o plugin compila um módulo de Editor, então o projeto host deve ser capaz de compilar C++).

AI Game Developer — Unreal MCP

Instalação

Há três maneiras de instalar o plugin, em ordem de preferência. Fab / Epic Marketplace é o canal recomendado para usuários finais — ele envia binários pré-compilados por engine e o Epic Games Launcher os mantém atualizados automaticamente, então há zero compilação e zero risco de build desatualizado. Instalações por fonte / unreal-mcp-cli continuam sendo o caminho atual para desenvolvedores e adotantes iniciais até a listagem no Fab entrar no ar.

Opção A — Fab / Epic Marketplace (recomendado; em breve)

Status: ainda não ativo. A listagem no Fab é controlada pelo operador e rastreada separadamente; até que seja publicada, use a Opção B ou C abaixo. O enquadramento aqui é como será o fluxo do usuário final.

Instale Unreal-MCP do Fab (o sucessor do Epic Marketplace) no seu engine através do Epic Games Launcher.
Ative o plugin para seu projeto em Edit → Plugins.
Abra o projeto — a UE carrega o plugin pré-compilado (sem build C++ na sua máquina). Na inicialização, o Output Log imprime [Unreal-MCP] plugin loaded.

Como o Fab envia binários pré-compilados e o Epic Launcher os atualiza no lugar, você nunca compila o plugin e nunca precisa limpar um cache de build desatualizado — o caminho mais robusto para não desenvolvedores.

Opção B — `unreal-mcp-cli` (atual / avançado)

A CLI é o caminho recomendado hoje, até a listagem no Fab estar ativa. Instale-a do npm — sem clone de repositório, sem etapa de build. Por padrão, install-plugin / update usam um checkout local de UnrealMCP/ quando presente; caso contrário, baixam o asset de fonte unreal-mcp-plugin-source-<version>.zip dedicado do GitHub Release público que corresponde à versão da CLI. Esse asset de fonte mantém a semântica de descritor distribuída (sem pin de EngineVersion) e carrega o payload de ponte assinado sob Source/ThirdParty/UnrealMcpBridge/<rid>/; o instalador o materializa em Binaries/ThirdParty/... para conveniência na primeira abertura. --plugin-source <dir> permanece como a substituição offline / CI / dev. A CLI copia (ou, para dev, faz junction) o plugin para seu projeto e, na atualização, limpa automaticamente o cache de build UE desatualizado para que você sempre obtenha uma recompilação limpa do novo código (veja Atualizando o plugin). Em plataformas desktop (Win64 / Mac / Linux), unreal-mcp-cli open também executa um build pré-lançamento quando o estado do projeto/plugin ainda precisa de binários nativos do editor, e então dispensa automaticamente os diálogos de bloqueio conhecidos do Unreal (Missing ... Modules, UnrealMCP is Incompatible) se ainda aparecerem durante a inicialização. A automação de diálogos no Linux é somente X11; Wayland é detectado e avisado como não suportado.

# 1. Install unreal-mcp-cli (or use `npx unreal-mcp-cli@latest <command>` for a one-off, no install)
npm install -g unreal-mcp-cli

# 2. Install the UnrealMCP plugin into your project
unreal-mcp-cli install-plugin ./YourProject

# 3. Authorize against the cloud server (ai-game.dev)
unreal-mcp-cli login ./YourProject

# 4. Open the Unreal Editor for the project (wires the MCP connection env vars)
unreal-mcp-cli open ./YourProject

Veja cli/README.md para a referência completa dos 16 comandos.

Opção C — manual

Copie UnrealMCP/ para <YourProject>/Plugins/UnrealMCP/ (ou crie um junction / symlink de diretório para ele para desenvolvimento ao vivo).
Abra o projeto; a UE compila o módulo UnrealMcpEditor na primeira inicialização.
Na inicialização do editor, o Output Log imprime [Unreal-MCP] plugin loaded — isso confirma que o plugin e seu dispatcher de game-thread iniciaram.

O binário sidecar (unreal-mcp-bridge) está incluído dentro do plugin em uma versão empacotada: um binário pré-compilado e autocontido para sua plataforma é enviado sob UnrealMCP/Binaries/ThirdParty/UnrealMcpBridge/<rid>/ e o editor o inicia automaticamente na inicialização sem nenhuma ação do usuário — sem instalação .NET, sem variável de ambiente, sem inicialização manual (ARQUITETURA §6). A primeira aprovação do código de dispositivo OAuth do Cloud no navegador é a única etapa humana restante; depois disso, a reconexão em inicializações posteriores é sem cliques (o token da nuvem é armazenado em cache em Saved/Config/UnrealMcp/).

Quando você copia o checkout do código-fonte do repositório diretamente (Opção C/manual ou um junction de dev ao vivo), o binário incluído não está presente — o plugin então resolve o sidecar a partir da variável de ambiente UNREAL_MCP_BRIDGE_PATH: aponte-a para um sidecar compilado localmente, ou execute unreal-mcp-cli bootstrap-local para compilar a ponte a partir do código-fonte em <YourProject>/Intermediate/UnrealMCP/ e defina a variável para o resultado. Sem binário incluído nem variável de ambiente resolvida, o listener TCP do plugin ainda inicia, mas registra [Unreal-MCP] no sidecar binary resolved for rid <rid> … e não inicia nada.

AI Game Developer — Unreal MCP

Atualizando o plugin

Atualizar no lugar deve sempre deixar você rodando o código novo. O risco é o compilador incremental da UE: se o código-fonte do plugin mudar (novos arquivos .cpp, um novo módulo) mas o cache de build UnrealMCP/Intermediate/ antigo sobreviver, a UE pode fazer uma recompilação parcial contra uma lista de módulos desatualizada e silenciosamente deixar você em código antigo/parcial. Cada canal lida com isso de forma diferente:

Fab / Epic Marketplace → automático. O Epic Games Launcher substitui os binários pré-compilados no lugar; nada para compilar, nenhum cache para limpar. É por isso que Fab é o canal recomendado.
unreal-mcp-cli update → rebuild limpo automático. update recopia o código-fonte do plugin e, por padrão, exclui o Intermediate/ desatualizado do plugin instalado e o Binaries/ C++ para que a UE execute uma compilação limpa na próxima inicialização do editor — sem etapas manuais. A ponte sidecar incluída sob Binaries/ThirdParty/UnrealMcpBridge/<rid>/ é mantida intacta: instalações de fonte de release a atualizam de Source/ThirdParty/..., enquanto instalações de repositório/dev preservam a cópia anteriormente incluída quando necessário. Instalações de dev por junction nunca são limpas (isso apagaria as saídas da sua árvore de código-fonte ao vivo). Passe --no-clean para optar por não fazer a limpeza do cache.
```
node bin/unreal-mcp-cli.js update <YourProject>            # default: clean rebuild on version change
node bin/unreal-mcp-cli.js update <YourProject> --force    # re-copy even when versions match
node bin/unreal-mcp-cli.js update <YourProject> --no-clean # keep the existing build cache
```
Cópia manual → limpe o cache você mesmo. Se você sobrescrever <YourProject>/Plugins/UnrealMCP/ manualmente, feche o editor primeiro, exclua <YourProject>/Plugins/UnrealMCP/Intermediate/ e o Binaries/ C++ (mantenha Binaries/ThirdParty/ se uma ponte incluída estiver presente), então reinicie para que a UE recompile limpo.

AI Game Developer — Unreal MCP

Primeira execução

Abra a janela principal do AI Game Developer pelo menu Tools do editor (a aba está registrada na categoria do menu Tools).
Escolha um modo de conexão:
- Cloud (padrão) — conecta-se a ai-game.dev. Clique em Authorize para iniciar o fluxo device-code do OAuth: a janela mostra uma URL de verificação e um código curto de usuário; abra a URL, insira o código, aprove e o editor concluirá a autorização. Use Revoke para limpar o token de nuvem armazenado.
- Custom — conecta-se a um gamedev-mcp-server local que você executa (ou a qualquer servidor compatível). Insira a URL do servidor e aponte seu cliente de IA para ele. (O plugin não inicia o servidor local para você — execute unreal-mcp-cli ou seu próprio processo; veja Troubleshooting.)
A seção Connection mostra um ponto de status, um rótulo de status e um botão Connect / Disconnect / Stop; o status da ponte exibe Running (restarts: N) ou Stopped. Use-os para confirmar que o sidecar está ativo.
Aponte seu cliente de IA (Claude Code, Cursor, o aplicativo AI Game Developer, …) para o servidor. A seção AI agents lista os agentes atualmente conectados; para escrever uma configuração de cliente MCP, use unreal-mcp-cli setup-mcp.

As configurações de conexão persistem em <Project>/Saved/Config/UnrealMcp/ai-game-developer-config.json (Saved/ é ignorado pelo git em todos os templates da UE, então os tokens nunca vão para o VCS por padrão).

URL de cliente MCP fixada. unreal-mcp-cli setup-mcp <agent> grava uma configuração de cliente MCP que aponta para a URL de nuvem fixada ao projeto <base>/mcp/p/<pin>, então o agente roteia para o editor deste projeto mesmo quando sua conta controla vários. Passe --no-pin para gravar a URL <base>/mcp simples. A fixação é apenas um segmento de caminho de roteamento — o recurso OAuth permanece <base>/mcp.

Chave do projeto. Quando esta máquina está conectada (unreal-mcp-cli login, ou o Sign in do editor), uma configuração de nuvem também carrega Authorization: Bearer agd_pk_… — uma chave sem expiração e revogável vinculada à fixação deste projeto — para cada agente, então nenhum agente precisa do próprio OAuth. A chave é armazenada em cache em ~/.ai-game-dev/project-keys.json e reutilizada. Passe --oauth para uma configuração somente com URL (o agente faz login sozinho), ou --regenerate-key para gerar uma nova chave e revogar a antiga (o painel de agentes de IA do editor tem um botão Regenerate key). Não conectado, ou o servidor não pode gerar uma chave ⇒ configuração somente com URL.

É isso. Pergunte à sua IA "Spawn três cubos em uma fileira e uma luz pontual acima deles" e veja acontecer. ✨

AI Game Developer — Unreal MCP

Ferramentas

O Unreal-MCP inclui 61 ferramentas integradas ("core") em 7 famílias que sua IA pode chamar, além de 3 ferramentas de sistema que ela não pode (veja abaixo). Os IDs das ferramentas estão em kebab-case (actor-create, blueprint-compile), seguindo a convenção de nomenclatura do Unity/Godot. Extensões podem adicionar mais (veja Customize Tools, Prompts & Resources).

Esta lista é gerada a partir das fontes de registro da superfície STANDARD (UnrealMCP/Source/UnrealMcpEditor/Private/Tools/UnrealMcp*Tools.cpp, excluindo UnrealMcpSkillTools.cpp — sua ferramenta é uma ferramenta de sistema, listada separadamente abaixo). Contagens: actor 13, blueprint 11, asset 11, editor/reflection 9, level 7, source 6, screenshot 4 = 61.

Família Actor & component (13)

ID da ferramenta	O que faz
`actor-create`	Spawna um actor a partir de um caminho de classe (nativo ou Blueprint), com nome/localização/rotação/pai opcionais
`actor-destroy`	Destrói um actor
`actor-duplicate`	Duplica um actor
`actor-find`	Encontra actors, com leituras com escopo (`paths`/`viewQuery`)
`actor-modify`	Grava valores de `FProperty` do actor (incluindo transform)
`actor-set-parent`	Anexa um actor a um pai
`actor-component-add`	Adiciona um componente a um actor
`actor-component-destroy`	Destrói um componente
`actor-component-get`	Lê os dados de um componente
`actor-component-modify`	Modifica as propriedades de um componente
`actor-component-list-all`	Lista classes `UActorComponent` disponíveis (paginado)
`object-get-data`	Lê qualquer `UObject` por caminho
`object-modify`	Modifica qualquer `UObject` por caminho

Família Blueprint (11) — a superfície principal da Unreal

ID da ferramenta	O que faz
`blueprint-create`	Cria uma nova classe Blueprint a partir de um caminho de `UClass` pai
`blueprint-get`	Resumo do grafo para inspeção por LLM (variáveis, componentes, funções/eventos, cadeia de pais)
`blueprint-add-component`	Adiciona um componente via Simple Construction Script
`blueprint-remove-component`	Remove um componente SCS
`blueprint-add-variable`	Adiciona uma variável de membro tipada
`blueprint-modify-variable`	Modifica uma variável de membro
`blueprint-set-default`	Edita uma propriedade CDO (class-default)
`blueprint-add-function`	Adiciona um stub de função (nós de entrada/saída conectados)
`blueprint-add-event`	Adiciona/víncula um stub de evento (BeginPlay, Tick, input, …)
`blueprint-compile`	Compila o Blueprint e retorna uma lista estruturada de erros/avisos (o loop de feedback da IA)
`blueprint-spawn`	Instancia o Blueprint no nível atual

Família Asset / Content-Browser (11)

ID da ferramenta	O que faz
`asset-find`	Pesquisa o AssetRegistry por nome/classe/caminho/tags
`asset-get-data`	Lê os dados de um asset (leituras com escopo suportadas)
`asset-create-folder`	Cria uma pasta de Content
`asset-copy`	Copia um asset
`asset-move`	Move / renomeia um asset
`asset-delete`	Exclui um asset
`asset-refresh`	Reescaneia caminhos de assets
`asset-material-create`	Cria uma Material Instance a partir de um material pai
`asset-material-modify`	Define parâmetros escalares/vetoriais/textura de instância de material
`asset-material-get-data`	Lê informações do grafo/parâmetros do material (o análogo de "shader")
`asset-import`	Importa FBX/texturas via `AssetImportTask`

Família Editor / console / reflection (9)

ID da ferramenta	O que faz
`editor-application-get-state`	Lê o estado do aplicativo do editor (PIE, etc.)
`editor-application-set-state`	Inicia / para / pausa Play-In-Editor
`editor-selection-get`	Lê a seleção atual do editor
`editor-selection-set`	Define a seleção do editor
`console-get-logs`	Lê logs recentes do editor do buffer circular `LogCollector`
`console-clear-logs`	Limpa o buffer circular de logs capturados
`console-run-command`	Executa um comando de console / CVar
`reflection-method-find`	Descobre `UFunction`s chamáveis (retorna esquemas de invocação)
`reflection-method-call`	Invoca um `UFunction` (estático ou de instância, incl. `CallInEditor`)

Família Level / map (7)

ID da ferramenta	O que faz
`level-create`	Cria um novo nível
`level-open`	Abre um nível
`level-save`	Salva o nível (salvar como via caminho opcional)
`level-get-data`	Snapshot da árvore de actors de um nível (leituras com escopo)
`level-list-loaded`	Lista subníveis persistentes + streaming (ciente de World-Partition, somente leitura)
`level-set-current`	Define o nível atual/ativo
`level-unload-sublevel`	Descarrega um subnível de streaming

Família Source / C++ (6)

ID da ferramenta	O que faz
`source-read`	Lê um arquivo de código-fonte C++ do projeto (fatiado)
`source-create-class`	Cria um esqueleto de nova classe C++ (header + cpp a partir de templates)
`source-update`	Edita um arquivo de código-fonte
`source-delete`	Exclui um arquivo de código-fonte
`source-list`	Lista arquivos de código-fonte do módulo
`source-compile`	Compila o C++ do projeto (Live Coding quando ativo, senão UBT) com um relatório de erros estruturado

Todas as operações de arquivo são restritas a <Project>/Source/.

Família Screenshot / captura de viewport (4)

ID da ferramenta	O que faz
`screenshot-viewport`	Captura o viewport ativo do editor
`screenshot-game-view`	Captura a visualização PIE / jogo
`screenshot-camera`	Renderiza a partir de um actor de câmera resolvido via `USceneCaptureComponent2D`
`screenshot-isolated`	Renderiza um actor isoladamente (SceneCapture2D transitório + lista somente-exibição)

As capturas retornam um PNG base64 como conteúdo de imagem MCP para que o LLM possa inspecionar a renderização diretamente. As dimensões são limitadas (padrão 1024, teto rígido de 2048 por lado). A captura de pixels precisa de um editor com GPU; sob -nullrhi headless, essas ferramentas retornam um erro estruturado.

Ferramentas de sistema (3) — NÃO expostas à sua IA

Estas são ferramentas de sistema: infraestrutura do host que o unreal-mcp-cli e o aplicativo de desktop acionam diretamente via POST /api/system-tools/<name>. Elas estão deliberadamente ausentes do MCP tools/list, então nunca aparecem para (ou gastam tokens em) uma sessão de IA — a mesma divisão que Unity e Godot usam para as mesmas três ferramentas.

ID da ferramenta	O que faz
`ping`	Sonda de atividade — percorre a cadeia plugin ⇄ sidecar ⇄ servidor
`unreal-skill-create`	Gera uma nova ferramenta MCP como um arquivo C++ no módulo do editor do plugin. Requer uma recompilação do editor antes que a nova ferramenta seja chamável (Live Coding, ou recompilar o projeto) — o resultado diz isso explicitamente. Precisa de uma instalação do plugin a partir do código-fonte
`unreal-skill-generate`	Regenera cada `SKILL.md` a partir das ferramentas registradas em uma pasta de skills relativa ao projeto (padrão `.claude/skills`)

AI Game Developer — Unreal MCP

Ativar / desativar por ferramenta

Cada ferramenta pode ser individualmente ativada ou desativada na janela MCP Tools — a aba independente MCP Tools (registrada no menu Tools do editor). A janela mostra o título, a família e a descrição de cada ferramenta, além de uma linha de resumo "N / M ferramentas ativadas". Desativar uma ferramenta:

a remove completamente do manifesto servido — ela nunca aparece no MCP tools/list; e
é aplicada também no limite de execução — mesmo que um tools/list desatualizado seja despachado, uma ferramenta desativada é rejeitada em Execute() em vez de executada.

Dois filtros se combinam para decidir se uma ferramenta é servida (veja ARCHITECTURE §7/§8):

uma whitelist (enabledTools, substituível via UNREAL_MCP_TOOLS) — quando não vazia, apenas as ferramentas listadas são servidas; vazia significa "sem filtro"; e
uma blocklist (disabledTools) — os toggles por ferramenta que você alterna na interface.

Uma ferramenta é servida se e somente se passar na whitelist e não estiver na blocklist. Ambos os conjuntos persistem entre sessões do editor e sobrevivem a um hot-reload de extensão (uma ferramenta re-registrada herda o toggle retido, então uma recompilação nunca pode reativar silenciosamente uma ferramenta que você desativou).

Todas as configurações de conexão ficam na seção Connection da janela principal única AI Game Developer (não há aba separada de Settings nem página de Project-Settings — paridade com Unity-MCP). As janelas MCP Prompts e MCP Resources estão conectadas, mas vêm vazias nesta versão — cada uma renderiza uma mensagem de estado vazio discreta (o resumo "N / M ativadas" é exclusivo da janela Tools).

AI Game Developer — Unreal MCP

`unreal-mcp-cli`

Um CLI Node multiplataforma (unreal-mcp-cli) que cria projetos, instala o plugin, configura as configurações de conexão, aciona o servidor local e invoca ferramentas via HTTP. É um port de unity-mcp-cli / godot-cli. Referência completa: cli/README.md.

Publicado no npm — instale com npm install -g unreal-mcp-cli, ou execute uma vez com npx unreal-mcp-cli@latest <command>.

A superfície completa de 16 comandos:

Comando	O que faz
`create-project`	Estruturar um projeto C++ mínimo do Unreal Engine
`open`	Iniciar o Unreal Editor para um projeto, configurando as variáveis de ambiente de conexão MCP
`close`	Encerrar o processo do Unreal Editor que executa um projeto
`install-plugin`	Instalar o plugin UnrealMCP em `<project>/Plugins` (copiar ou `--junction`) a partir de um checkout local ou do asset de origem do GitHub correspondente à versão
`remove-plugin`	Remover o plugin UnrealMCP de `<project>/Plugins`
`configure`	Gravar valores de `UNREAL_MCP_*` em `<project>/.env` e adicionar `.env` ao gitignore
`setup-mcp`	Gravar um trecho de configuração de cliente MCP para um agente
`login`	Autorizar contra ai-game.dev por meio do fluxo de código de dispositivo OAuth
`status`	Relatar o status do pacote, projeto, plugin e conexão ativa
`wait-for-ready`	Bloquear até que o servidor MCP do projeto responda a um ping
`run-tool`	Invocar uma ferramenta MCP por meio do servidor MCP local do projeto (HTTP)
`run-system-tool`	Invocar uma ferramenta de sistema por meio do servidor MCP local do projeto (HTTP)
`bootstrap-local`	Compilar a ponte a partir do código-fonte em `<project>/Intermediate/UnrealMCP` (o servidor é baixado por `setup-mcp`, não compilado)
`update`	Atualizar o plugin UnrealMCP instalado em um projeto a partir de um checkout local ou do asset de origem do GitHub correspondente à versão
`install-engine`	Detectar mecanismos Unreal instalados; para uma versão ausente, vincular ao launcher da Epic
`setup-skills`	Gravar um stub de skill do Claude-Code que aciona o servidor MCP Unreal deste projeto

AI Game Developer — Unreal MCP

Personalizar Ferramentas, Prompts e Recursos

Este é o recurso de extensibilidade principal. Qualquer pessoa pode registrar suas próprias Ferramentas de IA, prompts e recursos — de qualquer plugin UE de terceiros — e fazê-los aparecer no manifesto MCP junto com os integrados. Sem fork, sem acoplamento em tempo de link, sem suposições de ordem de carregamento. Suas contribuições são descobertas automaticamente na inicialização do editor (e em carregamento tardio / descarregamento a quente), mescladas em ordem determinística e expostas a todos os agentes de IA conectados.

Todos os três tipos usam o mesmo contrato pequeno, público e baseado em recursos modulares — uma interface de provedor mais um construtor de registro fluente, ambos no módulo UnrealMcpRuntime (re-exportado por UnrealMcpEditor, então o mesmo contrato atende extensões de editor e runtime). O guia completo do autor é docs/EXTENSIONS.md.

Ferramentas

Implemente IUnrealMcpToolProvider e declare suas ferramentas com o construtor fluente FUnrealMcpToolRegistry:

#include "IUnrealMcpToolProvider.h"
#include "UnrealMcpToolRegistry.h"

class FMyExtensionProvider : public IUnrealMcpToolProvider
{
public:
    virtual FString GetExtensionId() const override      { return TEXT("com.foo.my-extension"); }
    virtual FText   GetDisplayName() const override      { return NSLOCTEXT("Foo", "Name", "My Extension"); }
    virtual FString GetExtensionVersion() const override { return TEXT("1.0.0"); }

    virtual void RegisterTools(FUnrealMcpToolRegistry& Registry) override
    {
        Registry.Tool(TEXT("hello-extension"))
            .Title(TEXT("Hello Extension"))
            .Description(TEXT("Returns a friendly greeting."))
            .ParamString(TEXT("name"), TEXT("Who to greet. Defaults to 'world'."))
            .ReadOnlyHint(true)
            .IdempotentHint(true)
            .Handle([](const FUnrealMcpToolCall& Call) -> FUnrealMcpToolResult
            {
                const FString Name = Call.Has(TEXT("name")) ? Call.GetString(TEXT("name")) : TEXT("world");
                return FUnrealMcpToolResult::Success(FString::Printf(TEXT("Hello, %s!"), *Name));
            });
    }
};

Em seguida, registre o provedor como um recurso modular no StartupModule do seu módulo (e cancele o registro em ShutdownModule):

// In StartupModule:
IModularFeatures::Get().RegisterModularFeature(
    IUnrealMcpToolProvider::GetModularFeatureName(), Provider.Get());

Prompts

Prompts são modelos de prompt reutilizáveis e parametrizados que o agente busca via prompts/get. Implemente IUnrealMcpPromptProvider e declare prompts com FUnrealMcpPromptRegistry. Os argumentos de prompt reutilizam os mesmos auxiliares Param* do construtor de ferramentas; um manipulador retorna mensagens com tags de função:

#include "IUnrealMcpPromptProvider.h"
#include "UnrealMcpPromptRegistry.h"

class FMyPromptProvider : public IUnrealMcpPromptProvider
{
public:
    virtual FString GetExtensionId() const override      { return TEXT("com.foo.my-extension"); }
    virtual FText   GetDisplayName() const override      { return NSLOCTEXT("Foo", "Name", "My Extension"); }
    virtual FString GetExtensionVersion() const override { return TEXT("1.0.0"); }

    virtual void RegisterPrompts(FUnrealMcpPromptRegistry& Registry) override
    {
        Registry.Prompt(TEXT("level-design-brief"))
            .Title(TEXT("Level Design Brief"))
            .Description(TEXT("Generate a level design brief from a single 'theme' argument."))
            .Role(EUnrealMcpPromptRole::User)
            .ParamString(TEXT("theme"), TEXT("The level theme (e.g. 'haunted forest')."),
                         EUnrealMcpParamRequirement::Required)
            .Handle([](const FUnrealMcpToolCall& Call) -> FUnrealMcpPromptResult
            {
                const FString Theme = Call.GetString(TEXT("theme"));
                if (Theme.IsEmpty())
                    return FUnrealMcpPromptResult::Error(TEXT("theme is required."));
                const FString Text = FString::Printf(
                    TEXT("Draft a level design brief for a \"%s\"-themed level."), *Theme);
                return FUnrealMcpPromptResult::Success(Text, EUnrealMcpPromptRole::User);
            });
    }
};

// Register under the prompt modular-feature name (and unregister in ShutdownModule):
IModularFeatures::Get().RegisterModularFeature(
    IUnrealMcpPromptProvider::GetModularFeatureName(), PromptProvider.Get());

level-design-brief é o prompt principal incluído — veja UnrealMCP/Source/UnrealMcpRuntime/Private/Prompts/UnrealMcpCorePrompts.cpp.

Recursos

Recursos são conteúdos endereçáveis e legíveis que o agente busca via resources/read — o URI do recurso é sua identidade. Implemente IUnrealMcpResourceProvider e declare recursos com FUnrealMcpResourceRegistry. Uma leitura retorna blocos de conteúdo — texto XOR um blob base64 + um tipo MIME:

#include "IUnrealMcpResourceProvider.h"
#include "UnrealMcpResourceRegistry.h"

virtual void RegisterResources(FUnrealMcpResourceRegistry& Registry) override
{
    Registry.Resource(TEXT("unreal://project/levels"))                  // JSON (text) resource
        .Name(TEXT("Project Levels"))
        .Description(TEXT("A JSON snapshot of the active world and its levels."))
        .MimeType(TEXT("application/json"))
        .Read([](const FString& Uri) -> FUnrealMcpResourceResult
        {
            return FUnrealMcpResourceResult::Text(Uri, BuildLevelsJson(), TEXT("application/json"));
        });

    Registry.Resource(TEXT("unreal://project/icon"))                    // binary (blob) resource
        .Name(TEXT("Project Icon"))
        .Description(TEXT("A small PNG, returned as a base64 blob."))
        .MimeType(TEXT("image/png"))
        .Read([](const FString& Uri) -> FUnrealMcpResourceResult
        {
            const FString Base64 = FBase64::Encode(IconBytes, sizeof(IconBytes));
            return FUnrealMcpResourceResult::Blob(Uri, Base64, TEXT("image/png"));
        });
}

// Register under the resource modular-feature name (and unregister in ShutdownModule):
IModularFeatures::Get().RegisterModularFeature(
    IUnrealMcpResourceProvider::GetModularFeatureName(), ResourceProvider.Get());

unreal://project/levels e unreal://project/icon são os recursos principais incluídos — veja UnrealMCP/Source/UnrealMcpRuntime/Private/Resources/UnrealMcpCoreResources.cpp. Apenas recursos estáticos, de URI fixo são suportados hoje (URIs modelados / parametrizados são adiados). Um blob é base64 no lado do Unreal e no fio IPC; uma peculiaridade upstream conhecida no GameDev-MCP-Server / MCP-Plugin-dotnet compartilhado pode emitir incorretamente bytes de blob no fio MCP final para o cliente (recursos de texto fazem round-trip limpo de ponta a ponta) — isso é um problema upstream, não do plugin Unreal ou da ponte.

Como se comporta (idêntico para ferramentas, prompts e recursos):

Descoberta automática e recarga a quente. Unreal-MCP enumera todos os provedores registrados (UnrealMcpToolProvider / UnrealMcpPromptProvider / UnrealMcpResourceProvider) na inicialização e assina eventos de registro/cancelamento — então carregar ou descarregar seu plugin a qualquer momento aciona uma reconstrução do registro e um aumento de revisão do manifesto, e o sidecar compara o novo manifesto e adiciona/remove as ferramentas / prompts / recursos afetados automaticamente. Você nunca envia nada por conta própria.
Mesclagem determinística. Os provedores são mesclados em ordem crescente de GetExtensionId(); dentro de um provedor, as entradas são registradas em ordem de declaração. Seu GetExtensionId() é carimbado em tudo que você contribui (não chame .ExtensionId(...) você mesmo).
Isolamento por extensão. Cada descritor é validado (uma ferramenta/prompt precisa de um nome kebab-case + esquema bem formado + manipulador vinculado; um recurso precisa de um URI não vazio + manipulador). Uma entrada inválida ou duplicada (nome de ferramenta/prompt duplicado, ou URI de recurso duplicado) é descartada/rejeitada e o motivo é registrado no registro da sua extensão — suas outras entradas válidas e todas as outras extensões não são afetadas. (Builds de UE sem exceções C++, então o isolamento é em nível de descritor, não em nível de corpo de manipulador; valide entradas e falhe graciosamente com os auxiliares de resultado Error(...).)
Alternâncias e ativar/desativar. Ferramentas contribuídas por extensões são alternadas na janela Ferramentas MCP como as integradas; uma extensão desativada não contribui com nada para nenhum manifesto. (As janelas Prompts MCP / Recursos MCP estão conectadas, mas ainda renderizam vazias nesta versão — veja Ativar/desativar por ferramenta — então alternar prompts/recursos pela UI é um acompanhamento; registro e uso funcionam hoje.)

Saiba mais:

Guia completo do autor: docs/EXTENSIONS.md — o contrato para ferramentas, prompts e recursos, os construtores, ciclo de vida, ordenação, semântica de isolamento e versionamento.
Design: docs/ARCHITECTURE.md §5 (ferramentas) + §A (o caminho de registro de prompt/recurso).
Exemplos funcionais: samples/UnrealAITemplate/ — uma extensão de editor completa e compilável com uma ferramenta hello-extension e uma chave de compilação (UNREAL_AI_TEMPLATE_INVALID_SCHEMA=1) que demonstra o comportamento de isolamento em primeira mão; samples/UnrealAIRuntimeSample/ — a contraparte runtime (em jogo), um plugin Type=Runtime cuja ferramenta game-time-dilation lê/define a dilatação do tempo do mundo ativo, chamável em um jogo em execução por uma conexão MCP runtime (docs/ARCHITECTURE.md §12.9; veja EXTENSIONS.md "Uso runtime"). Para prompts e recursos, as famílias principais incluídas (UnrealMcpCorePrompts.cpp level-design-brief, UnrealMcpCoreResources.cpp unreal://project/levels + unreal://project/icon) são a referência executável.

AI Game Developer — Unreal MCP

Uso runtime (em jogo)

Tudo acima aciona o editor. Unreal-MCP também pode rodar dentro de um jogo em execução — PIE, Standalone ou um build Development empacotado — para que um assistente de IA possa dirigir seu jogo ao vivo. Esta é a contraparte Unreal do suporte runtime (em jogo) do Unity-MCP: o análogo UE do UnityMcpPluginRuntime.Initialize().Build().Connect() do Unity e seu exemplo de bot de xadrez [AiTool].

O ponto de entrada runtime é um UGameInstanceSubsystem, UUnrealMcpRuntimeSubsystem (no módulo runtime UnrealMcpRuntime do plugin). Ele é instanciado automaticamente uma vez por UGameInstance, mas nunca se conecta automaticamente — uma conexão é sempre uma chamada explícita de opt-in (veja o contrato de segurança abaixo).

Conecte-se de três maneiras

Todas as três alcançam o mesmo UUnrealMcpRuntimeSubsystem::Connect(Host, Token, Mode, bAllowRemoteHost); o modo de conexão padrão é Custom (um servidor loopback fornecido pelo desenvolvedor).

1. De C++ (por exemplo, seu GameMode::BeginPlay):

#include "UnrealMcpRuntimeSubsystem.h"

void AMyGameMode::BeginPlay()
{
    Super::BeginPlay();

    if (UUnrealMcpRuntimeSubsystem* Mcp = UUnrealMcpRuntimeSubsystem::Get(this))
        Mcp->Connect(TEXT("http://localhost:8080"), TEXT("my-token")); // Custom mode, loopback
    // ... and, when you are done:
    //  Mcp->Disconnect();
}

Get(WorldContext) é um auxiliar estático BlueprintPure que retorna o subsistema para a instância de jogo do contexto (ou nulo). Connect retorna false (e não conecta nada) se qualquer porta de segurança rejeitar — veja abaixo.

2. De Blueprint — Get Unreal MCP Runtime Subsystem (o nó Get, ciente de WorldContext) → Connect (um nó BlueprintCallable sob a categoria Unreal MCP; Token / Mode / bAllowRemoteHost são pinos avançados). Combine-o com o nó Disconnect e o nó puro Is Connected para status.

3. Do console (conveniência de QA, sem recompilação) — registrado enquanto o subsistema está ativo:

UnrealMcp.Connect <host> [token]
UnrealMcp.Disconnect

O caminho do console sempre usa loopback + modo Custom.

Suas próprias ferramentas, prompts e recursos em jogo

Um jogo envia suas próprias ferramentas de gameplay (e, se útil, prompts e recursos) e a IA as aciona ao vivo — o análogo UE do WithToolsFromAssembly / [AiTool] Chess-bot do Unity. Você cria todos os três exatamente como para uma extensão de editor (a seção Personalizar Ferramentas, Prompts e Recursos acima), com duas mudanças para um módulo de jogo: torne-o Type=Runtime e dependa de UnrealMcpRuntime (não UnrealMcpEditor). Registre seus provedores na inicialização do módulo, ou use os wrappers descobríveis do subsistema — um par de registro/cancelamento por tipo:

if (UUnrealMcpRuntimeSubsystem* Mcp = UUnrealMcpRuntimeSubsystem::Get(this))
{
    Mcp->RegisterToolProvider(MyToolProvider);          // tools merge in; manifest re-pushed
    Mcp->RegisterPromptProvider(MyPromptProvider);      // prompts merge in; manifest re-pushed
    Mcp->RegisterResourceProvider(MyResourceProvider);  // resources merge in; manifest re-pushed
}
// ... before destroying the providers, call the matching Unregister*Provider(...) for each.

O exemplo completo e compilável é samples/UnrealAIRuntimeSample/ — um plugin Type=Runtime cuja ferramenta game-time-dilation lê/define o AWorldSettings::TimeDilation do mundo ativo (câmera lenta / avanço rápido), chamável em um jogo em execução por uma conexão MCP runtime. (Ele demonstra o caminho de ferramenta; prompts e recursos se registram pela mesma API de três wrappers mostrada acima e as famílias principais incluídas são a referência executável.) Os detalhes do lado do autor (o contrato, ciclo de vida, ordenação, isolamento) estão em docs/EXTENSIONS.md → Uso runtime.

Conjunto de ferramentas runtime vs somente editor

Uma conexão runtime envia exatamente uma ferramenta integrada: ping (uma sonda de vivacidade). ping é uma ferramenta de sistema, então responde em POST /api/system-tools/ping e não é anunciada a um agente de IA — o que significa que um jogo empacotado que não registra nada próprio apresenta uma lista de ferramentas vazia, o que é uma descrição honesta dele. Tudo que um agente de IA runtime pode fazer é traga o seu próprio: registre suas próprias ferramentas via o barramento de extensão acima (RegisterToolProvider) e elas aparecem normalmente.

Todas as famílias de desenvolvimento de mecanismo — a família de ator/componente, object-get-data / object-modify, level-get-data, as ferramentas de console/reflexão, todas as ferramentas de screenshot, além de autoria de Blueprint, operações de asset / Content-Browser, edição e compilação de C++, criação/abertura/salvamento de nível e estado de aplicação do editor — são somente editor (as 61 ferramentas de editor). Elas acionam o editor e várias são classe RCE (por exemplo, reflection-method-call, console-run-command), então não são compiladas em um jogo enviado por padrão. Não há editor em um jogo empacotado, então a superfície integrada runtime é intencionalmente apenas ping + quaisquer ferramentas que seu jogo registra.

Somente editor — exclua Unreal-MCP de jogos empacotados

Se você quer Unreal-MCP apenas para ferramentas de IA dentro do Unreal Editor e pretende enviar um jogo empacotado com zero pegada de Unreal-MCP — sem módulo runtime, sem binário sidecar .NET incluído — fixe o plugin ao editor com um TargetDenyList no .uproject do seu próprio projeto consumidor (não no .uplugin do plugin):

// <YourProject>.uproject — "Plugins" array
{
    "Name": "UnrealMCP",
    "Enabled": true,
    "TargetDenyList": [ "Game", "Client", "Server" ]
}

UE honra TargetDenyList / TargetAllowList em uma referência de plugin (PluginReferenceDescriptor::IsEnabledForTarget): o plugin permanece ativo no alvo Editor, mas é excluído dos builds empacotados Game / Client / Server — portanto, nem o módulo de infraestrutura de runtime nem o sidecar unreal-mcp-bridge incluído são preparados ou compilados no seu produto final. Módulos do tipo Editor (UnrealMcpEditor) são removidos de um build de jogo independentemente; a lista de negação também remove o módulo de infraestrutura UnrealMcpRuntime e seu sidecar RuntimeDependencies (§12.5), dando a você uma pegada de compilação zero.

Atenção — não crie uma dependência direta de módulo. Um TargetDenyList apenas exclui os módulos próprios do plugin. Se um dos seus módulos de jogo adicionar UnrealMcpRuntime (ou qualquer módulo UnrealMcp*) ao seu *.Build.cs PublicDependencyModuleNames / PrivateDependencyModuleNames, ou #includes um cabeçalho UnrealMcp*, essa dependência direta sobrepõe a lista de negação e o UBT compila o módulo de runtime no seu jogo de qualquer forma. Um projeto somente-editor puro não referencia nada do plugin, então ele permanece limpo por construção — só opte por uma dependência de módulo quando você realmente quiser uso em runtime (no jogo).

Para uso em runtime (no jogo) em vez disso, deixe a lista de negação desativada: o módulo de infraestrutura UnrealMcpRuntime + o ping embutido são incluídos no build empacotado (§12.5), e você registra suas próprias ferramentas de gameplay via IUnrealMcpToolProvider — veja Uso em runtime (no jogo) e Personalizar Ferramentas, Prompts e Recursos. Os dois são mutuamente exclusivos: lista de negação para um projeto somente-editor, sem lista de negação para um jogo que hospeda uma conexão MCP ao vivo.

Contrato de segurança

Uma conexão de runtime é controle remoto de um jogo em execução (actor-create, object-modify, CVars arbitrários via console-run-command, UFunctions arbitrários via reflection-method-call) — classe RCE se fosse alcançável em um produto enviado. A superfície de runtime é, portanto, bloqueada por cinco mitigações em camadas (docs/ARCHITECTURE.md §12.8), todas aplicadas dentro de Connect():

Somente opt-in. O subsistema se auto-instancia, mas nunca se auto-conecta — não há discagem automática no carregamento e nenhuma auto-conexão de ativo de configuração. Uma conexão só acontece por meio de uma chamada explícita Connect().
Interruptor de segurança, DESLIGADO por padrão. UUnrealMcpRuntimeSettings::bRuntimeMcpEnabled (Configurações do Projeto → Plugins → Unreal MCP (Runtime)) tem como padrão false. Enquanto estiver desligado, todo Connect() é rejeitado e nenhum sidecar é gerado. É uma configuração de Jogo (DefaultGame.ini, seção [/Script/UnrealMcpRuntime.UnrealMcpRuntimeSettings]), então ela viaja para o build empacotado onde a barreira deve ter efeito. Ligá-lo não auto-conecta — um Connect() explícito ainda é necessário.
Barreira de Shipping. O sinalizador bUnrealMcpAllowShipping *.Build.cs tem como padrão false (→ UNREAL_MCP_ALLOW_SHIPPING=0); em um build Shipping, Connect() registra e retorna false a menos que esse sinalizador tenha sido deliberadamente compilado. Builds de Development / PIE não são afetados.
Padrão de host loopback. Connect() rejeita qualquer Host que não seja loopback, a menos que o chamador passe explicitamente bAllowRemoteHost = true. O padrão mantém a conexão em localhost / 127.0.0.0/8 / ::1.
IPC loopback + token de stdin de uso único. A IPC plugin ⇄ sidecar é somente loopback e autenticada com um token de uso único entregue via stdin, nunca argv, e nunca registrado (mesmo modelo do editor, ARCHITECTURE §1.4).

Além disso, o caminho de runtime é somente Desktop (Win64 / Mac / Linux): gerar o processo sidecar .NET unreal-mcp-bridge não é possível em plataformas de console ou móveis, então essas plataformas não têm superfície MCP de runtime.

Runbook de ponta a ponta. O passo a passo completo do operador — habilitar o interruptor de segurança, conectar do PIE e de um build Development empacotado, e exercitar ferramentas pela conexão ao vivo — está em docs/RUNTIME-E2E.md. A metade determinística (barreiras de segurança, resolução de troca de mundo, segurança de conectar/desconectar/órfãos) é bloqueada por especificações Automation headless.

AI Game Developer — Unreal MCP

Configuração e variáveis de ambiente

O plugin lê a configuração com a precedência env do processo → <Project>/.env → arquivo de configuração → padrões embutidos. As variáveis UNREAL_MCP_* reconhecidas (definidas em UnrealMCP/Source/UnrealMcpEditor/Private/Config/UnrealMcpConfig.cpp):

Variável	Propósito
`UNREAL_MCP_CONNECTION_MODE`	`Cloud` ou `Custom`. Padrão é `Cloud`.
`UNREAL_MCP_HOST`	URL do servidor (modo Custom), ex.: `http://localhost:<port>`
`UNREAL_MCP_CLOUD_URL`	URL do backend de nuvem (padrão é ai-game.dev)
`UNREAL_MCP_TOKEN`	Token de autenticação (token IPC do sidecar / token do servidor). Segredo — nunca faça commit.
`UNREAL_MCP_AUTH_OPTION`	`none` ou `oauth` (autenticação do servidor local)
`UNREAL_MCP_KEEP_CONNECTED`	Persistir/restaurar o estado conectado
`UNREAL_MCP_TOOLS`	Substituição de ferramentas habilitadas (whitelist; vazio = sem filtro)
`UNREAL_MCP_START_SERVER`	Analisado e persistido como o sinalizador de configuração `startServer` (modo Custom); auto-gerar o `gamedev-mcp-server` local é planejado, ainda não conectado — nenhum código consome esse sinalizador hoje, então inicie o servidor você mesmo (ex.: `unreal-mcp-cli`).
`UNREAL_MCP_TRANSPORT`	`stdio` ou `http`
`UNREAL_MCP_LOG_LEVEL`	Verbosidade de log
`UNREAL_MCP_BRIDGE_PATH`	Caminho para um binário sidecar — a substituição dev/CI; vence sobre o binário incluído (§6). Uma versão empacotada resolve automaticamente o sidecar incluído, então usuários finais nunca definem isso; builds a partir do código-fonte usam isso.
`UNREAL_MCP_SERVER_PATH`	Caminho para um binário `gamedev-mcp-server` local (lido por `unreal-mcp-cli`, não pelo plugin) — pula o download do servidor + verificação de versão (§6).

Nunca faça commit de .env. Um .env na raiz do projeto pode conter UNREAL_MCP_TOKEN, e os modelos de projeto UE não incluem .gitignore. unreal-mcp-cli configure anexa .env ao .gitignore do projeto alvo; o scaffold deste repositório já o ignora via gitignore. O token IPC do sidecar viaja via stdin (nunca argv) e nunca é registrado.

AI Game Developer — Unreal MCP

Solução de problemas

No connected clients. Retrying [1..10] e depois HTTP 500 de um servidor local. O modo de conexão usou o padrão Cloud, então o sidecar discou para ai-game.dev em vez do seu servidor local. Defina UNREAL_MCP_CONNECTION_MODE=Custom (env, .env, ou o alternador de UI).
Nenhuma linha [Unreal-MCP] plugin loaded na inicialização. O módulo do editor falhou ao carregar — verifique o Output Log para um erro StartupModule ou um .uplugin malformado.
Um corpo de ferramenta retorna 'x' is required. quando invocado pelo passthrough REST. Envie -H "Content-Type: application/json"; sem isso, o servidor descarta o corpo JSON.
Ferramentas de screenshot retornam um erro estruturado. A captura de pixels precisa de um editor com suporte a GPU — elas não podem renderizar sob -nullrhi headless.
Sem sidecar / sidecar reiniciando constantemente. Verifique o status da ponte na seção Connection (Running (restarts: N) / Stopped). Se o log mostrar no sidecar binary resolved for rid <rid> …, nem um binário incluído nem UNREAL_MCP_BRIDGE_PATH foram resolvidos — em uma versão empacotada, isso significa que o plugin foi empacotado sem a ponte da sua plataforma (reinstale o build correto); em um build a partir do código-fonte, defina UNREAL_MCP_BRIDGE_PATH ou execute unreal-mcp-cli bootstrap-local para compilar um a partir do código-fonte. (O sidecar é incluído em versões empacotadas e auto-gerado, §6 — não há download na primeira execução.)
Portas. A IPC usa uma porta determinística por projeto em 30000–39999 e sonda para frente (depois uma porta efêmera) em colisão; o servidor local usa uma porta hash determinística em 20000–29999 sem sondagem — o CLI deriva o mesmo número sem ler nenhuma configuração, e o servidor vincula a porta exata solicitada. O número exato é uma conveniência de depuração, não um requisito.
Logs. Use a ação Open log file da janela principal, a ferramenta console-get-logs, ou o Output Log do editor (categoria LogUnrealMcp).

AI Game Developer — Unreal MCP

Como a Arquitetura do Unreal MCP Funciona

Unreal-MCP é uma ponte entre LLMs e o Unreal Editor. Ele expõe e explica as ferramentas do Unreal ao LLM, que então entende a interface e usa as ferramentas de acordo com suas solicitações.

Como o editor é C++, o host .NET McpPlugin não roda em processo (como faz no Unity/Godot). Em vez disso, o plugin escuta em uma porta TCP localhost e gera um processo sidecar auto-gerenciado (unreal-mcp-bridge) que disca para ele, autenticando com um token de uso único entregue via stdin. O sidecar retransmite IPC ⇄ SignalR para o servidor MCP (nuvem ai-game.dev por padrão, ou um gamedev-mcp-server local). As AI Tools que o plugin registra são então chamáveis por qualquer agente de IA compatível com MCP. O design autoritativo — protocolo IPC, registro dinâmico de ferramentas, geração de esquema, o despachante de thread do jogo, extensões, ciclo de vida do sidecar, UI e configuração — vive em docs/ARCHITECTURE.md (comece no diagrama de visão geral do sistema §0).

O que é `MCP`

MCP — Model Context Protocol. Em poucas palavras, é USB Type-C para IA, especificamente para LLMs (Large Language Models). Ele ensina o LLM a usar recursos externos — como o Unreal Engine neste caso, ou até mesmo sua própria ferramenta C++ personalizada. Documentação oficial.

O que é um `AI agent`

É um aplicativo com uma janela de chat. Pode ter agentes inteligentes para operar melhor e MCP Tools avançadas embutidas. Um cliente MCP bem construído é 50% do sucesso da IA na execução de uma tarefa — por isso é importante escolher um bom.

O que é o `MCP Server`

É a ponte entre o MCP Client e "algo mais" — neste caso, o Unreal Editor. No modo Cloud, é o backend hospedado ai-game.dev; no modo Custom, é o host compartilhado GameDev-MCP-Server que você executa você mesmo.

O que é um `MCP Tool`

Um MCP Tool é uma função que o LLM pode chamar para interagir com o Unreal. Essas ferramentas são a ponte entre solicitações em linguagem natural e operações reais do Unreal. Quando você pede à IA para "gerar um ator" ou "compilar este Blueprint", ela usa MCP Tools para executar a ação. As ferramentas têm parâmetros tipados e descritos; retornam resultados estruturados; e rodam na thread do jogo do editor via o despachante (a thread de leitura IPC nunca executa corpos de ferramentas).

AI Game Developer — Unreal MCP

Layout do repositório

Caminho	O que é
`UnrealMCP/`	O plugin do editor UE (C++, módulo `UnrealMcpEditor`, piso UE 5.5+, desenvolvido contra 5.7, verificado em 5.8)
`bridge/`	O sidecar .NET 9 (`unreal-mcp-bridge`) — host McpPlugin, retransmissor IPC ⇄ SignalR
`cli/`	Pacote npm `unreal-mcp-cli` (TypeScript) — 16 comandos
`samples/UnrealAITemplate/`	Plugin de modelo de extensão do editor (`hello-extension`)
`samples/UnrealAIRuntimeSample/`	Exemplo de extensão de runtime (no jogo) (`game-time-dilation`, `Type=Runtime`)
`docs/ARCHITECTURE.md`	O design de arquitetura autoritativo
`docs/EXTENSIONS.md`	Guia do autor de extensão
`docs/RELEASING.md`	CI/CD + runbook de versão do operador

Unreal-MCP

Documentação

✨ AI Game Developer — Unreal MCP

Sumário

Requisitos

Instalação

Opção A — Fab / Epic Marketplace (recomendado; em breve)

Opção B — unreal-mcp-cli (atual / avançado)

Opção C — manual

Atualizando o plugin

Primeira execução

Ferramentas

Ativar / desativar por ferramenta

unreal-mcp-cli

Personalizar Ferramentas, Prompts e Recursos

Ferramentas

Prompts

Recursos

Uso runtime (em jogo)

Conecte-se de três maneiras

Suas próprias ferramentas, prompts e recursos em jogo

Conjunto de ferramentas runtime vs somente editor

Somente editor — exclua Unreal-MCP de jogos empacotados

Contrato de segurança

Configuração e variáveis de ambiente

Solução de problemas

Como a Arquitetura do Unreal MCP Funciona

O que é MCP

O que é um AI agent

O que é o MCP Server

O que é um MCP Tool

Layout do repositório

Links

Licença

Opção B — `unreal-mcp-cli` (atual / avançado)

`unreal-mcp-cli`

O que é `MCP`

O que é um `AI agent`

O que é o `MCP Server`

O que é um `MCP Tool`