Configuração do Unity MCP

Entenda a ponte do editor

CoplayDev/unity-mcp conecta um cliente MCP a um servidor e a um pacote do lado do editor. O serviço de modelo é uma dependência separada. O projeto documenta ferramentas para trabalhar com cenas, scripts, ativos e testes, mas uma capacidade listada não é evidência de que funcione no seu projeto.

Registre qual processo possui cada parte da conexão. Isso importa ao diagnosticar um cliente que alcança o servidor mas não consegue operar o editor. Mantenha credenciais da conta, licença do editor, compatibilidade do pacote e disponibilidade do modelo como verificações de configuração separadas. Uma mudança de modelo não corrige incompatibilidade da instância do editor.

Revise o caminho de instalação e a política de fixação

O guia de instalação do projeto documenta a adição do pacote pelo Unity Package Manager e o uso da interface de configuração para ajustar servidor e cliente. Revise os pré-requisitos declarados de Unity, Python e uv para a revisão escolhida antes de instalar qualquer coisa.

Para reprodutibilidade, preserve a revisão resolvida do pacote, versão do editor, versão do servidor e registros de dependências após a configuração. Uma URL de branch móvel é um caminho de descoberta, não uma identidade imutável de experimento. Revise downloads e mudanças de pacote antes de aplicá-los a um jogo existente e retenha o estado funcional anterior para que o experimento de conexão seja reversível.

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Associe o endpoint HTTP local ao cliente

O guia de instalação mantido documenta o exemplo HTTP local abaixo. Ele presume que o servidor já está rodando nesse endereço. Confirme o transporte e o endereço realmente configurados na interface de configuração do editor antes de usá-lo. A URL MCP não é uma base URL de API LLM.

Use o formato de configuração documentado do seu cliente. Alguns clientes usam chaves raiz ou declarações de transporte diferentes, portanto este exemplo genérico mcpServers não é um arquivo universal para colar em todo agente. Mantenha o servidor local salvo se uma configuração remota revisada separadamente for necessária e não adicione credenciais de modelo a uma conexão de editor não relacionada.

{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Comprove qual instância do editor recebe o trabalho

Abra o projeto pretendido e inspecione o estado da conexão pela interface do pacote. Depois use as operações de leitura descobertas pelo cliente para obter contexto do projeto e da cena. Compare essa informação com o projeto local antes de aprovar uma edição. Vários projetos abertos tornam esse portão especialmente importante.

Registre recursos reais e esquemas de ferramentas da versão instalada. Não invente uma chamada de ferramenta a partir de um nome lembrado de outra release. Um primeiro resultado útil identifica a cena esperada e seus objetos existentes sem alterá-los. Se o estado retornado estiver antigo ou ambíguo, pare e resolva o roteamento em vez de tentar uma mutação visível para descobrir o alvo.

Use uma edição reversível como primeiro minifluxo

Escolha uma cena descartável própria, registre seu estado inicial e peça uma alteração simples com consequência visível. Inspecione a cena salva e o diff do arquivo, aguarde o editor ficar pronto e exercite a cena. Preserve comportamento observado e erros de console.

Depois reabra a cena para confirmar que a alteração pretendida persistiu. Isso distingue um efeito em memória do editor de uma alteração salva no projeto. Mantenha o fluxo pequeno o suficiente para diagnosticar a falha em um limite: roteamento, mutação, compilação, execução ou persistência. Restaure a cena descartável após a revisão e use a configuração funcional registrada na próxima tarefa.

Solucione o transporte antes do jogo

Quando o cliente não conseguir conectar, verifique a URL configurada e se o servidor local está rodando. Quando o servidor iniciar mas o editor estiver ausente, inspecione a conexão do pacote e os logs do editor. Quando o editor pretendido estiver conectado mas uma ferramenta faltar, inspecione os grupos de ferramentas expostos pela versão instalada.

Somente depois que esse limite funcionar você deve diagnosticar compilação ou jogabilidade. Mantenha trechos de log separados para inicialização do cliente, roteamento do servidor, prontidão do editor e ação de cena falha. Isso permite explicar onde a execução parou, em vez de atribuir toda falha ao modelo ou reinstalar componentes repetidamente sem evidências.

Proteja o projeto contra automação ampla

Uma conexão de editor pode alterar cenas, scripts e ativos. Restrinja o experimento inicial a um diretório conhecido e exija revisão de operações que excluam recursos, alterem dependências ou toquem cenas não relacionadas. Preserve um estado de trabalho recuperável antes da primeira mudança.

Não exponha publicamente um serviço de desenvolvimento local apenas para resolver um problema de configuração do cliente. Trate conteúdo de ativos de terceiros e resultados de ferramentas como entradas não confiáveis e mantenha credenciais fora de logs compartilhados. Uma conexão bem-sucedida não é permissão para enviar compilações ou alterar registros da loja. Publicação continua sendo um fluxo separado com uma fronteira de autorização separada.

Transmita um registro de conexão reproduzível

Registre revisões do editor, projeto, pacote e servidor, versão do cliente, transporte, superfície observada das ferramentas e minifluxo concluído. Mantenha o diff exato da cena e o resultado de runtime. Declare se compilação, comportamento PlayMode, testes e exportação-alvo foram examinados ou continuam pendentes.

Esta configuração segue a documentação mantida do projeto; verifique-a contra o pacote e cliente instalados. Para produção de jogos, avance ao guia do fluxo Unity e teste o loop completo. Mantenha limitações conhecidas na passagem para que outro desenvolvedor consiga distinguir um problema de conexão de um problema do projeto e reproduzir a mesma configuração funcional.

Perguntas frequentes