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

Solução de problemas

Corrija problemas comuns do Unreal MCP: plugin não carrega, bridge ausente, conexão travada, agente sem ferramentas do Unreal e erros.

Atualizado em 4 de novembro de 2026 Ver como Markdown

Esta página lista os problemas que as pessoas mais encontram com o Unreal MCP e como corrigi-los. Comece pelas verificações rápidas e depois vá para a seção correspondente.

Verificações rápidas

  1. O plugin está carregado? O Output Log deve conter [Unreal-MCP] plugin loaded depois que o editor iniciar.
  2. O que a janela diz? Abra Tools, AI Game Developer e leia a linha de status (Connected, Connecting, Reconnecting, Disconnected ou No MCP bridge).
  3. O que a CLI vê? Execute unreal-mcp-cli status --path ./YourProject.
  4. Leia o log. Use Open log file na janela, filtre o Output Log pela categoria LogUnrealMcp ou peça ao agente console | where Verbosity == "Error".

O plugin não carrega

Se não houver a linha [Unreal-MCP] plugin loaded, o módulo do editor falhou ao iniciar.

  • Procure no Output Log um erro de inicialização do plugin ou um .uplugin corrompido.
  • Certifique-se de que o projeto é um projeto C++ com um toolchain de compilador funcional. Veja Instalação.
  • Se o Unreal disser que faltam módulos ou que o plugin é incompatível, deixe-o recompilar, ou abra o projeto com unreal-mcp-cli open ./YourProject, que compila primeiro os módulos nativos e dispensa esses avisos.

Uma atualização não tem efeito

O build incremental do Unreal pode manter código antigo do plugin quando o código-fonte do plugin muda, mas a pasta Intermediate/ antiga sobrevive.

  • Atualize com unreal-mcp-cli update ./YourProject, que limpa o cache de build por padrão.
  • Após uma cópia manual: feche o editor, exclua Plugins/UnrealMCP/Intermediate/ e os arquivos C++ em Plugins/UnrealMCP/Binaries/ (mantenha Binaries/ThirdParty/) e reabra.

"No MCP bridge" ou a bridge reinicia sem parar

O plugin precisa do seu processo de bridge, unreal-mcp-bridge. A janela mostra o estado da bridge e um contador de reinícios.

  • Se o log disser no sidecar binary resolved for rid <rid>, nenhuma bridge foi encontrada.
    • Instalação pelo app ou CLI: a bridge vem incluída. Reinstale com unreal-mcp-cli install-plugin ./YourProject (ou pelo app); o pacote pode não ter a sua plataforma.
    • Checkout do código-fonte: compile uma com unreal-mcp-cli bootstrap-local ./YourProject, ou defina UNREAL_MCP_BRIDGE_PATH.
  • Clique em Restart bridge no rodapé da janela depois de corrigir a causa.

Travado em "Connecting" ou "Reconnecting"

  • Modo Cloud: verifique se você está autenticado. Se a janela mostrar "Sign in required", sua sessão salva expirou; clique em Authorize e aprove o novo código.
  • Verifique se a máquina consegue acessar ai-game.dev (regras de proxy ou firewall).
  • Modo Custom: certifique-se de que o servidor local está em execução (Start no card do servidor MCP, ou --start-server) e que o Server URL aponta para ele.
  • Use Disconnect e depois Connect, ou Restart bridge.

O servidor local diz "No connected clients"

Se um gamedev-mcp-server local registra No connected clients. Retrying e depois responde com HTTP 500, o editor ainda está no modo Cloud e conectado a ai-game.dev em vez do seu servidor local. Mude para Custom na janela, defina UNREAL_MCP_CONNECTION_MODE=Custom, ou passe --connection-mode Custom (ou --host) para unreal-mcp-cli open.

O agente de IA não tem ferramentas do Unreal

  • Verifique a configuração do agente: execute unreal-mcp-cli setup-mcp <agent> --path ./YourProject --dry-run e compare, ou clique em Configure (ou Reconfigure) na seção do agente de IA.
  • Reinicie ou recarregue o agente depois das mudanças de configuração. Muitos clientes leem as configurações de MCP apenas na inicialização.
  • O Claude Code lê o .mcp.json da pasta em que você o inicia; inicie-o na pasta do projeto.
  • Se você configurou com setup-mcp antes de abrir o editor alguma vez, a configuração pode apontar para localhost em vez da nuvem. Abra o projeto uma vez e execute setup-mcp de novo, ou passe --url.
  • Verifique a linha AI agents na seção Connection. Se o seu agente não estiver listado, ele não está conectado ao mesmo servidor que o editor.
  • Se você ocultou ferramentas na janela MCP Tools ou definiu UNREAL_MCP_TOOLS, o agente vê menos ferramentas.

O agente acessa o editor errado

Com vários editores em uma conta, use a URL fixada ao projeto (/mcp/p/<pin>), que o setup-mcp grava por padrão. Execute setup-mcp de novo sem --no-pin. Veja Conectando clientes de IA.

Erros 401 no agente

  • No modo Cloud, uma configuração apenas com URL exige que o agente faça login por conta própria. Ou deixe-o executar o login OAuth dele, ou faça login na máquina (unreal-mcp-cli login) e execute setup-mcp novamente para que a configuração carregue uma project key.
  • Se a project key foi revogada, use Regenerate key no editor ou setup-mcp --regenerate-key.
  • No modo Custom com autenticação por token, a configuração deve carregar o mesmo token que o editor. Use Reconfigure após gerar um novo token.

As chamadas de ferramentas expiram

Uma chamada de ferramenta pode durar 5 minutos por padrão. Aumente UNREAL_MCP_TOOL_TIMEOUT (em milissegundos) para scripts Python longos ou importações grandes. python-execute também tem seu próprio timeout (padrão de 30 segundos) que o agente pode definir por chamada.

As ferramentas de captura de tela retornam um erro

A captura de pixels precisa de um editor com suporte a GPU. Sob -nullrhi, as ferramentas de captura de tela retornam um erro estruturado. unreal-mcp-cli exec e open --headless iniciam editores que renderizam fora da tela, então as capturas ainda funcionam neles.

As ferramentas Python falham

python-execute usa o Python Editor Script Plugin do Unreal, que o Unreal MCP habilita. Se o Python não estiver disponível, verifique se o plugin está habilitado em Edit, Plugins. Os erros apontam para linhas de snippet.py, que é o código enviado pelo agente.

A extensão não aparece

  • As extensões exigem Unreal Engine 5.7 ou superior e Unreal MCP 0.26.0 ou superior.
  • Após instalar, a extensão precisa ser compilada: reabra o editor, use --build ou Compile (Live Coding) na seção Extensions.
  • Verifique se a extensão está habilitada na seção Extensions.

Ainda com problemas?

  • Consulte o FAQ e o FAQ geral.
  • Use Help / Talk na janela para perguntar no Discord, ou Bug Report para abrir uma issue no GitHub. Inclua a versão do Unreal, seu sistema operacional, a linha de status da janela e as linhas de log relevantes (nunca seus tokens).