Conectando clientes de IA

Esta página explica como um cliente de IA chega ao Unity Editor, qual endpoint e login ele usa, e como configurar cada agente suportado a partir da janela do AI Game Developer, do unity-mcp-cli, ou manualmente.

Duas formas de conectar#

Seu cliente de IA nunca fala diretamente com o Unity. Ambos se conectam a um servidor MCP, e o servidor encaminha as chamadas de ferramentas ao Editor por uma conexão SignalR.

Escolha o modo com o seletor Connection (Custom / Cloud) na janela do AI Game Developer. Configuração cobre as configurações do servidor local.

URLs fixadas#

O endpoint base https://ai-game.dev/mcp encaminha para um dos seus editores conectados por fallback. Isso funciona bem com um único projeto aberto, mas é ambíguo com vários.

Uma URL fixada, https://ai-game.dev/mcp/p/<pin>, sempre encaminha para o Editor de um projeto. O pin é derivado da identidade do projeto. O botão Configure da janela e unity-mcp-cli setup-mcp gravam a URL fixada por padrão; setup-mcp --no-pin grava a URL base. Para o transporte stdio, o pin é passado como um argumento project=<pin>.

Fazendo login#

O Editor, a CLI e o aplicativo desktop compartilham um único login por máquina em ~/.ai-game-dev/credentials.json. Faça login uma vez em qualquer um deles:

• Na janela: modo Cloud, depois Authorize, depois aprove o código no navegador.
• Em um terminal: unity-mcp-cli login.
• No aplicativo AI Game Dev: Sign in.

Os tokens são renovados em segundo plano. Revoke na janela desconecta todas as ferramentas do AI Game Dev na máquina (todos os plugins de engine, as CLIs e o aplicativo desktop) e revoga os tokens no servidor.

Como o próprio cliente de IA se autentica depende da configuração gravada:

• Chave de projeto (padrão para Cloud HTTP quando você está conectado). A configuração carrega Authorization: Bearer agd_pk_…, uma chave que não expira e pode ser revogada, vinculada apenas a este projeto. As chaves ficam em ~/.ai-game-dev/project-keys.json. Regenerate key na janela, ou setup-mcp --regenerate-key, substitui a chave e revoga a antiga.
• OAuth (somente URL). Nenhuma credencial no arquivo; o cliente abre um login no navegador na primeira vez que se conecta. Você obtém isso quando não está conectado, ou com setup-mcp --oauth.
• Personal Access Token. Para CI ou clientes que não conseguem fazer login pelo navegador, crie um token na sua conta ai-game.dev (veja Autenticação) e passe-o com setup-mcp --token <token>.

Trate chaves de projeto e tokens como senhas. Arquivos como .mcp.json ficam na pasta do projeto, então verifique seu .gitignore antes de commitá-los. Autenticação explica o lado da conta.

Agentes de IA suportados#

O menu suspenso AI agent da janela lista estes configuradores. Configure grava o arquivo mostrado; Remove retira a entrada novamente.

Caminhos relativos são dentro do seu projeto Unity. A entrada do servidor é sempre chamada ai-game-developer. Execute unity-mcp-cli setup-mcp --list para ver os ids que a sua versão da CLI suporta.

Configurar com unity-mcp-cli#

setup-mcp grava a mesma saída do botão Configure da janela, sem abrir o Unity:

unity-mcp-cli setup-mcp claude-code ./MyUnityProject
unity-mcp-cli setup-mcp cursor ./MyUnityProject --transport stdio
unity-mcp-cli setup-mcp claude-code ./MyUnityProject --no-pin

O transporte padrão é http. Com --transport stdio, a configuração inicia o binário do servidor local. Todas as flags estão na referência da CLI.

Configurar manualmente#

Qualquer cliente MCP compatível com HTTP pode usar o endpoint hospedado. Exemplo com Claude Code:

claude mcp add --transport http ai-game-developer https://ai-game.dev/mcp

Uma configuração JSON genérica de mcpServers:

{
  "mcpServers": {
    "ai-game-developer": {
      "url": "https://ai-game.dev/mcp"
    }
  }
}

Substitua a URL pela URL fixada do seu projeto (mostrada nas etapas de configuração manual da janela) para direcionar a um projeto específico. A página do endpoint MCP tem snippets para todos os clientes, incluindo o formato servers do VS Code e um cabeçalho PAT.

Servidor local via HTTP#

No modo Custom com o transporte HTTP, aponte o cliente para o servidor local. A porta é a que aparece em Server URL na janela; as etapas de configuração manual mostradas para o seu agente na janela contêm a URL exata, incluindo o pin do projeto:

{
  "mcpServers": {
    "ai-game-developer": {
      "url": "http://localhost:<port>"
    }
  }
}

Servidor local via stdio#

Com o transporte stdio, o cliente inicia o próprio binário do servidor. No Windows:

claude mcp add ai-game-developer "<project>/Library/mcp-server/win-x64/gamedev-mcp-server.exe" port=<port> plugin-timeout=10000 client-transport=stdio

Use osx-arm64, osx-x64, linux-x64, linux-arm64, win-x86 ou win-arm64 para outras plataformas (sem .exe fora do Windows). Substitua <project> pelo caminho completo do projeto e <port> pela porta indicada na janela. Apenas um agente pode usar um servidor stdio por vez, e o botão Start/Stop da janela fica desativado porque o agente é o dono do processo. Prefira HTTP, a menos que seu cliente não tenha suporte a HTTP.

Depois de configurar#

Reinicie o cliente de IA, ou reconecte o servidor MCP dele, para que leia a nova configuração. Depois, siga os Primeiros passos para verificar a conexão. Se o cliente não mostrar ferramentas, consulte a Solução de problemas.