Configuração MCP do Antigravity: local do arquivo, loja e erros comuns

Você cola um novo servidor no Antigravity, clica em Refresh e a lista de ferramentas continua vazia. Muitas vezes o servidor está bem. O problema está no arquivo: qual mcp_config.json o app lê, onde ele fica no seu disco e se o JSON usa os nomes de campo que o Antigravity espera. As páginas do próprio Google apontam para dois caminhos diferentes, posts de fóruns mostram pessoas editando a cópia errada, e as mensagens de erro são curtas a ponto de parecerem enigmas.

Este artigo esclarece os fatos. Você recebe o local exato do arquivo no Windows, macOS e Linux, três formas de abri-lo a partir do app, um tour pela MCP Store, uma configuração que funciona e uma solução direta para cada erro comum. Quando as fontes divergem, o texto diz isso em vez de chutar.

Onde fica o mcp_config.json

O Antigravity guarda todas as definições de servidores MCP em um único arquivo JSON chamado mcp_config.json. A página oficial de MCP lista um arquivo global, que vale para todos os projetos, e um arquivo do workspace, que vale para um único repositório.

Caminho global por sistema operacional

No Windows, %USERPROFILE% se expande para algo como C:\Users\YourName. A pasta .gemini começa com um ponto, então o Finder e a maioria dos gerenciadores de arquivos do Linux a escondem. No Finder, pressione Cmd+Shift+. para mostrar itens ocultos; no gerenciador de arquivos do Windows, marque Hidden items no menu View; ou pule a navegação e cole o caminho completo na barra de endereços ou na caixa Go to Folder.

Config do workspace para um projeto

Dentro de um repositório, a documentação indica .agents/mcp_config.json como o local do workspace. Ele serve para servidores que só fazem sentido para uma base de código, como um servidor de banco de dados apontado para o schema de desenvolvimento desse projeto. Um relato de solução de problemas em japonês diz que as configurações do workspace podem sobrepor o arquivo global, então verifique esse caminho primeiro quando um servidor se comportar de forma diferente dentro de um repositório.

💡 Dica: Se um arquivo do workspace contiver tokens, adicione .agents/mcp_config.json a .gitignore antes do seu próximo commit.

Por que a documentação diverge sobre o caminho

A documentação atual e a página de configuração do CloudBees Unify usam ~/.gemini/config/mcp_config.json. Tutoriais mais antigos, muitos READMEs de servidores e o relato de bug de PATH no macOS usam ~/.gemini/antigravity/mcp_config.json. O arquivo de token OAuth também fica na pasta antigravity, o que ajuda a explicar por que esse nome de pasta continua aparecendo.

Nenhuma página diz qual arquivo prevalece quando os dois existem. Resolva com um teste: adicione uma entrada inofensiva a um dos arquivos, clique em Refresh e veja se ela aparece na lista de servidores. Se não aparecer, você editou o arquivo errado. Depois mantenha um único arquivo ativo e renomeie a cópia avulsa para mcp_config.json.bak, para que os dois nunca saiam de sincronia. Abrir o arquivo por View raw config na IDE é a forma mais rápida de ver qual deles sua versão usa.

Três formas de abrir o arquivo

Você não precisa procurar em pastas ocultas. Cada superfície do Antigravity tem sua própria porta de entrada para a mesma configuração.

Pelo painel do agente na IDE

Na IDE do Antigravity, clique no menu … no topo do painel lateral do agente, depois escolha MCP Servers, depois Manage MCP Servers e então View raw config. O arquivo abre no editor. Salve, volte para a tela Manage MCP Servers e clique em Refresh. Esse último clique é o passo que os fóruns de solução de problemas recomendam repetidamente.

Pelas configurações do Antigravity 2.0

No Antigravity 2.0, o caminho é Settings (canto inferior esquerdo), depois Customizations e então Installed MCP Servers. Cada servidor tem um interruptor, uma lixeira e um botão Refresh compartilhado. A ferramenta de linha de comando tem sua própria porta de entrada: digite /mcp no painel de prompt para abrir o MCP Manager interativo. Ele também mostra logs de conexão, incluindo códigos de resposta como 401, 403 e 404 e timeouts, o que o torna o melhor lugar para ler o que deu errado de fato.

Como funciona a MCP Store

A MCP Store é uma lista pesquisável de servidores prontos. A documentação descreve 76 ou mais integrações em bancos de dados, ferramentas para desenvolvedores, plataformas de design, segurança e analytics. Você chega a ela por Installed MCP Servers clicando em Add MCP, ou pelo menu MCP Servers no painel do agente da IDE.

Adicione um servidor pela loja

1. Abra Settings, depois Customizations e então Installed MCP Servers.
2. Clique em Add MCP para abrir a loja.
3. Pesquise ou role até o servidor que você quer e clique em Add.
4. Conclua o login se o servidor pedir.
5. Confira se o interruptor está ligado e depois clique em Refresh.

Abra a config bruta uma vez depois da sua primeira instalação pela loja. A entrada que a loja gravou é um modelo pronto para as entradas que você escrever à mão depois.

💡 Dica: Use a loja para servidores que exigem OAuth, porque ela cuida da tela de login. Use JSON escrito à mão para scripts locais, servidores privados e qualquer coisa que precise de headers personalizados.

Onde os tokens OAuth acabam

Segundo a documentação, os tokens OAuth são salvos em ~/.gemini/antigravity/mcp_oauth_tokens.json. Trate esse arquivo como um cofre de senhas: mantenha-o fora de repositórios de dotfiles e de pastas de sincronização na nuvem. Quando um login continuar falhando, use primeiro o botão Sign out na IDE ou verifique o status Authed na visualização da CLI /mcp. Apagar o arquivo de token é último recurso, e pode desconectar você de todos os servidores remotos de uma vez.

Uma configuração que realmente funciona

O arquivo tem um objeto de nível superior, mcpServers, e cada servidor é uma entrada com nome dentro dele. Os nomes não devem ter espaços. Um tópico de fórum sobre o servidor do Figma descobriu que um nome sugerido como "Figma Desktop" precisou virar FigmaDesktop, e que o campo de URL precisava ser serverUrl, e não url.

Servidores locais com command e args

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/you/projects"],
      "env": { "NODE_ENV": "production" },
      "cwd": "C:/Users/you/projects"
    }
  }
}

Copiar prompt

No Windows, escreva os caminhos com barras normais ou duplique as barras invertidas (C:\\Users\\you), porque uma barra invertida simples é um caractere de escape no JSON. Veja o que cada campo faz:

Servidores remotos com serverUrl

{
  "mcpServers": {
    "remote-example": {
      "serverUrl": "https://api.example.com/mcp/",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Copiar prompt

A documentação diz que os campos simples url não são compatíveis com servidores remotos, então um trecho copiado de outro editor precisa dessa renomeação. Servidores que usam OAuth recebem um bloco oauth no lugar de um header: a página da CloudBees mostra "oauth": { "clientId": "public-mcp-client" }. Para servidores do Google Workspace, você cria um cliente OAuth do tipo Web application no Google Cloud Console, adiciona https://antigravity.google/oauth-callback como URI de redirecionamento e coloca o clientId e o clientSecret na seção oauth. Servidores que aceitam as credenciais padrão de aplicação do Google usam "authProviderType": "google_credentials".

Antes de salvar, confira três coisas que quebram o JSON com mais frequência do que qualquer bug do Antigravity: vírgulas sobrando no fim, comentários (o JSON não aceita nenhum) e aspas curvas coladas de uma página web.

Erros comuns e soluções

Context deadline exceeded

Isso aparece na inicialização, junto com a mensagem de socket ENOENT, quando um servidor não termina de inicializar a tempo. A solução relatada é simples: abra Manage MCP Servers e clique em Refresh. Se o erro voltar a cada reinício, um contorno prático é instalar o pacote do servidor globalmente e apontar command para o binário instalado, assim nada precisa ser baixado enquanto a IDE está inicializando.

Executable not found in PATH

Mensagens como exec: "npx": executable file not found in $PATH aparecem quando o Antigravity é iniciado pelo Dock ou pelo Spotlight no macOS. O app herda o PATH enxuto do sistema (/usr/bin:/bin:/usr/sbin:/sbin) em vez do que vem do perfil do seu shell. O tópico relata o problema na versão 1.22.2 e lista estas soluções alternativas:

• Inicie o app a partir de um terminal com o comando agy.
• Coloque o caminho absoluto em command. Execute which npx e cole o resultado, por exemplo /opt/homebrew/bin/npx em uma configuração típica do Homebrew em Apple Silicon.
• Crie um pequeno script wrapper que carregue seu gerenciador de versões do Node antes de iniciar o servidor.

Usuários do Windows devem executar where npx em um terminal antes. Se ele não imprimir nada, o problema está na instalação do Node, não na configuração.

Unauthorized on initialize

Um erro Unauthorized em initialize significa que um servidor remoto recebeu a primeira requisição sem um token utilizável. Atualize o Antigravity, desconecte-se do servidor e entre de novo. Se você usa um token em header, confirme se o campo se chama Authorization, se o valor começa com Bearer e se o token não expirou. O código de status nos logs da CLI /mcp ajuda a restringir: 401 indica credenciais ausentes ou inválidas, 403 indica um token sem as permissões certas, e 404 indica um caminho de URL errado.

Mais de 100 ferramentas

O Antigravity se recusa a conectar quando as ferramentas ativadas em todos os servidores passariam de 100. Servidores grandes para GitHub ou bancos de dados podem expor dezenas de ferramentas cada, então três ou quatro deles já são suficientes para bater no limite. Desative os servidores que você não usa ou oculte ferramentas individuais com a propriedade disabledTools listada na documentação.

Vale conhecer mais um padrão. Um relato no fórum de desenvolvedores do Google AI descreve um servidor do Roblox Studio, iniciado por um arquivo em lote, que falhou com a mensagem EOF no Hub 2.4.3, 2.5.0 e 2.8.0 e só voltou a funcionar depois de reverter para o Hub 2.2.1. Quando um servidor local falha desse jeito, execute o comando exato dele em um terminal. Se falhar ali também, a configuração está correta e o problema é o servidor. Se funcionar ali, suspeite de regressão de versão e consulte o fórum antes de mudar seu JSON.

Use o Gemini 3.1 Pro no PicassoIA

Quando o JSON se recusa a funcionar, um modelo de linguagem vira um revisor rápido. O Gemini 3.1 Pro roda no navegador no PicassoIA, aceita texto com até 10 imagens e permite definir o quanto ele pensa antes de responder.

Passos a seguir

1. Abra a página do Gemini 3.1 Pro no PicassoIA.
2. Substitua cada token real da sua configuração por YOUR_TOKEN antes de colar qualquer coisa.
3. Cole seu JSON no campo Prompt depois de uma instrução clara, por exemplo: "Verifique este mcp_config.json do Antigravity em busca de erros de sintaxe e nomes de campo errados. Servidores remotos devem usar serverUrl, não url. Nomes de servidores não devem conter espaços. Liste cada problema e depois retorne apenas o JSON corrigido."
4. Opcional: anexe uma captura de tela do painel de erro no campo Images (até 10 imagens, 7 MB cada).
5. Execute o modelo, copie o JSON corrigido para View raw config, salve e clique em Refresh.

Dicas de parâmetros

• thinking_level: o padrão é high. Mantenha para uma configuração longa com muitos servidores. low basta para uma verificação de sintaxe simples.
• temperature: o padrão é 1. Reduza para cerca de 0,2 para que o modelo devolva o mesmo JSON sempre, em vez de ser criativo.
• system_instruction: defina algo como "Você é um validador JSON rigoroso para arquivos de configuração MCP" para manter a resposta curta.
• max_output_tokens: o padrão é alto o suficiente para qualquer configuração que você vá escrever, então deixe como está.

O modelo não consegue ver o seu disco, então trate qualquer caminho que ele sugerir como um palpite e confira na tabela anterior neste artigo. Para uma segunda opinião sobre o mesmo prompt, rode-o também no Claude Sonnet 4.6 e compare as duas respostas.

Checklist antes de reiniciar

Percorra esta lista antes de culpar o servidor:

• O JSON é válido: sem vírgulas sobrando, sem comentários, apenas aspas retas.
• Servidores remotos usam serverUrl, e servidores locais usam command com args.
• Nomes de servidores não contêm espaços.
• O comando funciona em um terminal, ou command contém um caminho absoluto.
• Os tokens ficam em env ou headers, e o arquivo fica fora do controle de versão se contiver segredos.
• As ferramentas ativadas em todos os servidores continuam abaixo de 100.
• Você editou o arquivo que o app realmente lê, o que pode confirmar por View raw config.
• Você clicou em Refresh e depois conferiu os interruptores ou a visualização /mcp da CLI.

💡 Dica: Um servidor que funciona no seu terminal, mas falha dentro do Antigravity, geralmente aponta para uma diferença de ambiente, mais comumente o PATH. Compare a saída de which ou where com o que o app enxerga.

Experimente o Picasso IA você mesmo

Depois que seus servidores se conectarem, seu agente pode construir mais rápido, e todo projeto lançado também precisa de imagens: banners de README, cabeçalhos da documentação, cabeçalhos de blog e prévias para redes sociais. O Picasso IA reúne os modelos de imagem em um só lugar, então você pode testar um prompt, mudar a lente ou a luz e gerar de novo em segundos.

Comece com o Seedream 4.5 para cenas fotorrealistas detalhadas ou com o P-Image para rascunhos rápidos. Descreva o assunto, o cenário, a direção da luz e a lente da câmera, do mesmo jeito que você passaria um briefing a um fotógrafo. Veja a lista completa de modelos, escolha um que combine com seu próximo projeto e crie sua primeira imagem hoje mesmo.