UEFN MCP

O UEFN MCP incorpora um servidor de MCP ao processo do Unreal Editor para Fortnite, permitindo que qualquer agente de IA compatível com MCP, como o Claude Code, o Cursor ou o MCP Inspector, possa controlar o editor por meio de uma conexão HTTP local.

Ele expõe as seguintes funcionalidades específicas do UEFN: 

• Criação e modificação de entidades do Scene Graph em Verse;

• Leitura e programação de arquivos Verse;

• Colocação de dispositivos do Modo Criativo e edição de suas propriedades;

• Inicialização, interrupção e inspeção de uma sessão de jogo.

O que é o MCP?

O UEFN MCP incorpora um servidor do Model Context Protocol (MCP) ao processo do editor do UEFN. Qualquer agente de IA compatível com MCP se conecta a ele via HTTP local e controla o editor por meio de ferramentas tipadas, agrupadas em conjuntos de ferramentas. Assim, o editor é transformado em algo que um agente pode inspecionar e operar lendo código Verse, editando o Scene Graph, colocando e configurando dispositivos do Modo Criativo e executando uma sessão de jogo. 

Uma vez configurado com o membro desenvolvedor indicando um agente (como o Claude Code) no editor em execução, você pode começar a fazer perguntas ou dar instruções em linguagem natural. Alguns exemplos são:

• Quais dispositivos posso colocar?

• Adicione um log quando a rodada começar e compile-o.

• Inicie uma sessão para que eu possa testar.

Com esses tipos de perguntas e orientações, o agente descobre os conjuntos de ferramentas disponíveis, chama as ferramentas e informa suas conclusões. 

Pré-requisitos do UEFN MCP

O UEFN MCP exige que as seguintes configurações sejam feitas no projeto antes que você possa prosseguir.

1. Habilite a Programação no editor Python para o projeto.

2. Configure a inicialização automática para o MCP.

3. Gere um arquivo de configuração do cliente.

4. Inicie um agente de IA do diretório de instalação do UEFN do Fortnite.

Habilite Python e o UEFN MCP

Em Configurações de Projeto, marque as caixas de seleção de Programação no editor Python e Conjuntos de ferramentas do UEFN MCP.

Como configurar a inicialização automática do MCP

Para configurar a inicialização automática do MCP:

• Abra Editar, Preferências do Editor.

• No grupo Geral, selecione Model Context Protocol (MCP).

Assim, expomos a configuração Servidor de início automático que, quando habilitada, inicia o servidor de MCP automaticamente sempre que o editor for inicializado, vinculando o servidor de MCP a http://127.0.0.1:8000/mcp. 

Este mesmo painel também expõe a porta de escuta (padrão: 8000) e o caminho da URL (padrão: /mcp) para ambientes onde esses padrões entram em conflito com outro serviço local. O nome do servidor anunciado em ServerInfo.name é sempre unreal-mcp.

Se quiser iniciar o servidor sob demanda, desative a opção Servidor de início automático e insira ModelContextProtocol.StartServer no console do editor.

O comando também aceita uma porta opcional: ModelContextProtocol.StartServer:8000.

Crie uma configuração de cliente

Cada agente de IA espera sua lista de servidores em um formato de arquivo específico e em um local específico na árvore do projeto. Ele precisa saber o local onde o UEFN está instalado. 

Para acessar rapidamente, você pode verificar o local de instalação do inicializador para abrir diretamente no local desa pasta.

Depois de obter o local onde os arquivos de instalação do UEFN estão armazenados (não os arquivos do seu projeto), você criará um arquivo .mcp.json.

Para criar o arquivo mcp.json: 

1. Na pasta raiz do seu projeto do UEFN, clique com o botão direito e crie um novo documento de texto. Dê a ele o nome de .mcp.txt;  

   

2. Abra o documento de texto;

3. Copie e cole o texto a seguir no arquivo. Este é o JSON específico do modelo e precisa ser formatado para o agente de IA específico que você está usando. O exemplo abaixo é o JSON do Claude:

   Config

   mcp.json
   {
     "mcpServers": {
       "unreal-mcp": {
         "type": "http",
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

   Copy full snippet(9 lines long)

4. Salve como Todos os arquivos com a extensão .json no final, substituindo .txt.

   

Depois de criar a configuração para seu agente de IA, você precisará lembrar de fazer uma manutenção ao usar a CLI do Codex. A configuração de TOML que ele usa grava somente uma vez, o que significa que o comando não substituirá um arquivo existente. Por isso, uma configuração desatualizada deve ser removida manualmente. As configurações em formato JSON usadas pelo Claude Code, Cursor, VS Code e Gemini são mescladas com quaisquer entradas existentes, o que torna seguro executar o comando repetidamente. 

Como conectar um agente de IA

Para conectar um agente de IA ao UEFN, inicialize o aplicativo ou a CLI do seu agente de IA preferido a partir do projeto ou da raiz do espaço de trabalho onde os arquivos de configuração ".mcp.json" foram gerados. Você pode consultar o Log de Saída quando estiver gerando o arquivo de configuração para o local desse arquivo. 

Abaixo apresentamos um exemplo de como iniciar o Claude da pasta onde o arquivo ".mcp.json" foi criado: 

Se estiver tendo problemas para se conectar, tente o seguinte:

• Se a CLI ou o aplicativo do seu agente de IA não encontrar o Unreal MCP, verifique se ele foi inicializado a partir da raiz do projeto, ou do espaço de trabalho, onde os arquivos de configuração foram colocados.

• Tente uma porta diferente se a porta padrão (8000) estiver sendo usada por outro serviço. Essa definição pode ser feita nas Preferências do Editor com o número da porta do servidor.

• Certifique-se de que tanto o Programação no editor Python quanto os Conjuntos de ferramentas do UEFN MCP estejam habilitados nas Configurações de Projeto.

• Para iniciar e parar o servidor, você deve fechar e reabrir o editor. Na dúvida, tente reiniciar o editor.

Com quais outras funcionalidades o Unreal MCP interage?

Sugestões de prompts para conjuntos de ferramentas

A tabela abaixo inclui algumas instruções que você pode usar para explorar as funcionalidades de cada recurso, e também como uma forma de verificar se cada conjunto de ferramentas está funcionando como esperado. 

Dicas para obter melhores resultados

• Tenha precisão com a nomenclatura.

  • Ao criar um prompt, é melhor apresentar a maior precisão possível ao pedir para que agente faça algo com um objeto. Por exemplo, pedir ao agente para alterar algo com "o dispositivo Temporizador" em vez de "aquela coisa que adicionei" gerará um resultado melhor.

• Peça aos agentes para listarem as ferramentas disponíveis.

  • Existem ferramentas de descoberta para isso que ajudam a reduzir suposições erradas.

• Peça um plano para solicitações de vários passos.

  • Analise o plano apresentado antes que o agente execute a tarefa. Assim, impedimos que o agente presuma incorretamente sua solicitação pretendida.

• Mantenha as alterações revisáveis.

  • Pequenas edições são mais simples de se verificar do que um grande conjunto de alterações. Pode se tornar cada vez mais difícil verificar esses tipos de alterações ou perder algo ao longo do caminho.

Problemas conhecidos

Esta é uma lista de problemas conhecidos que estão sendo investigados e poderão ser resolvidos em uma versão futura:

• A tradução do sistema de coordenadas e da transformação do formato LUF para o XYZ.

  • Atualmente, os conjuntos de ferramentas Python usam o formato XYZ em vez do sistema de coordenadas Left-Up-Forward (LUF). Para a tradução entre o XYZ e o LUF que o UEFN usa, algumas vezes funciona quando solicitamos que um agente de IA faça a conversão, mas, como os sistemas funcionam de forma diferente em relação à matemática espacial, o potencial para erros é multiplicado.

• Travamento do editor

  • Chamadas de ferramentas de MCP podem fazer com que o editor trave e congele. Estamos analisando esse problema e avaliando maneiras de tornar as chamadas de ferramentas mais eficientes no editor.