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

Solução de problemas

Resolva problemas comuns do Unity MCP: ferramentas ausentes no cliente de IA, erros de login e conexão, falhas de download e conflitos de porta.

Atualizado em 4 de novembro de 2026 Ver como Markdown

Esta página reúne os problemas mais comuns com o Unity MCP e como corrigi-los. Comece pela lista rápida; se isso não ajudar, encontre seu sintoma abaixo.

Lista rápida

  1. Abra Window > AI Game Developer — MCP e veja a linha do tempo: Unity, MCP server e AI agent devem estar todos verdes.
  2. Verifique o Console do Unity em busca de erros. Um erro de compilação em qualquer lugar do projeto impede o carregamento dos scripts de editor do plugin.
  3. Execute unity-mcp-cli status ./MyUnityProject para ver se o Unity está em execução e qual servidor está acessível.
  4. Reinicie seu cliente de IA após qualquer alteração na configuração.
  5. Certifique-se de que o plugin e suas extensões estejam nas versões atuais.

O cliente de IA não mostra nenhuma ferramenta do Unity

  • O cliente se conectou antes de o Unity estar pronto. Reconecte o servidor MCP no cliente (no Claude Code, /mcp) ou reinicie o cliente depois que a janela mostrar Connected.
  • O cliente não foi configurado ou usa uma configuração antiga. Clique em Configure (ou Reconfigure) para o seu agente na janela, ou execute unity-mcp-cli setup-mcp <agent> . e reinicie o cliente.
  • O modo Cloud não está autenticado. A janela mostra "Authorization Required". Clique em Authorize e aprove o código no navegador.
  • Vários projetos estão abertos. Uma URL https://ai-game.dev/mcp não fixada pode encaminhar para outro Editor. Use a URL fixada que Configure grava.
  • O agente é iniciado de outra pasta. Configurações em nível de projeto, como .mcp.json ou .cursor/mcp.json, só são lidas quando o cliente é executado na pasta do projeto Unity.
  • No VS Code, mude o Copilot Chat para o modo Agent.

Problemas de login no Cloud

  • "Authorization Required" não para de aparecer. Sua credencial expirou ou foi revogada. Clique em Authorize novamente ou execute unity-mcp-cli login --force.
  • "Connection Required". O login funcionou, mas o Unity não está conectado. Clique em Connect.
  • Login feito com a conta errada. Clique em Revoke (isso desconecta todas as ferramentas do AI Game Dev da máquina) e depois em Authorize com a conta correta. O unity-mcp-cli login pergunta antes de trocar de conta.

O gerenciamento de sessões e dispositivos da sua conta está descrito em Autenticação.

O servidor MCP local não inicia (modo Custom)

  • O binário não foi baixado. Ele vai para Library/mcp-server/<platform>/. Se o download falhou (offline, firewall, proxy), a janela mostra "Server binary error" e um botão Download / Retry server. Você também pode usar Tools > AI Game Developer > Server > Download Binaries.
  • O antivírus bloqueou o executável. Permita gamedev-mcp-server no seu software de segurança e tente novamente.
  • O transporte é stdio. Com stdio, o agente de IA inicia o servidor por conta própria, então o botão Start fica desabilitado. Mude para http se quiser que o Unity o execute.
  • Leia os logs do servidor. Use Tools > AI Game Developer > Server > Open Logs e Open Log Errors.
  • Teste o servidor diretamente. Tools > AI Game Developer > Server > Launch MCP Inspector abre o MCP Inspector para o servidor local (apenas transporte HTTP; requer Node.js).

Conflitos de porta

Cada projeto recebe uma porta fixa entre 20000 e 29999, derivada do seu caminho. Se outra coisa já estiver escutando nela, a janela mostra o servidor MCP como External. Encontre o processo:

netstat -ano | findstr :<port>
lsof -i :<port>

Encerre esse processo, ou desconecte e digite outra porta em Server URL (por exemplo http://localhost:25000), e clique em Configure novamente para que o agente use a nova porta.

Desconexões durante a compilação

O Unity recarrega os scripts após cada alteração de código e ao entrar no modo Play. O plugin se desconecta antes da recarga e se reconecta depois, então um breve "Disconnected" ou "Connecting..." é normal. Uma chamada de ferramenta que estava em andamento durante a recarga pode falhar; peça ao agente para tentar novamente.

Erros de compilação ou DLLs ausentes após a instalação

O plugin baixa suas dependências .NET do NuGet para Assets/Plugins/NuGet.

  • Erros sobre tipos ausentes de McpPlugin, ReflectorNet ou SignalR. Aguarde a primeira importação terminar e use Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs.
  • "Path too long" no Windows. O runtime do Unity não consegue abrir DLLs além do limite de 260 caracteres de caminho do Windows, mesmo com caminhos longos habilitados. Mova o projeto para uma pasta mais curta, como C:/Projects/MyGame.
  • Reinstalação limpa. Feche o Unity, exclua Assets/Plugins/NuGet e seu arquivo .meta e reabra o projeto.

Caminho do projeto com espaços

Se o Console mostrar "The project path contains spaces", mova o projeto para uma pasta sem espaços. O plugin avisa porque esses caminhos podem causar problemas durante o uso.

As chamadas de ferramentas falham ou expiram

  • Erros como "object not found". Peça ao agente para consultar primeiro (por exemplo com rql-query) em vez de adivinhar nomes ou caminhos. Caminhos de assets começam com Assets/.
  • Operações longas expiram. Aumente Tool timeout (ms) na janela (padrão 300000) para bakes lentos ou execuções de teste grandes.
  • As capturas de tela falham no modo batch. Um Editor iniciado com -nographics não tem dispositivo gráfico. Inicie em modo headless sem -nographics; unity-mcp-cli open --headless já faz isso.
  • Uma ferramenta personalizada lança erros de thread. Envolva as chamadas da API do Unity em MainThread.Instance.Run. Veja Ferramentas personalizadas.

Problemas com unity-mcp-cli

  • open para em "Enter Safe Mode?" A CLI clica em Ignore automaticamente. No macOS, conceda permissão de Acessibilidade ao seu terminal; no Linux, instale xdotool.
  • exec espera e depois desiste. O projeto está aberto em um Editor que a CLI não iniciou, e o plugin dele não está respondendo localmente (por exemplo, está conectado à nuvem). Conecte o plugin, mude-o para Custom ou passe --url.
  • setup-skills falha. Ele precisa de um Editor em execução com o plugin conectado. Execute open e wait-for-ready primeiro.
  • Use --verbose em qualquer comando para obter logs detalhados.

Redefinição completa

  1. Feche o Unity.
  2. Exclua Library/mcp-server/ no projeto.
  3. Reabra o Unity e escolha Tools > AI Game Developer > Reset Config.
  4. Faça login novamente (Cloud) ou inicie o servidor (Custom) e clique em Configure para o seu agente.
  5. Reinicie seu cliente de IA.

Obtendo ajuda

Use Help / Talk (Discord) ou Bug Report (issues do GitHub) na parte inferior da janela do AI Game Developer. Inclua sua versão do Unity, o sistema operacional, a versão do plugin (mostrada na janela), o erro do Console e os passos para reproduzir. Você também pode consultar o FAQ ou o FAQ do site.