Ligar o Gemini CLI ao seu estúdio

O que é

O Gemini CLI é o Gemini da Google que é executado no terminal do computador. Com o conector de IA, consulta os dados do seu estúdio (vendas, clientes, agenda, financeiro) quando faz uma pergunta, com as permissões do utilizador associado à chave. Só consulta os dados: não altera nada no sistema.

Quando usar

Já utiliza o Gemini no terminal e quer perguntar sobre a atividade do estúdio sem abrir o sistema.
Quer cruzar números do sistema com outras tarefas que o Gemini faz por si.

Antes de começar

Tenha à mão o endereço do conector, copiado conforme as instruções do artigo Ligar a sua IA, e uma chave de API com «Permitir utilização como conector de IA». O Gemini CLI tem de estar instalado no computador. Também aceita o início de sessão no sistema: sem o cabeçalho da chave, escreva /mcp auth heya no Gemini CLI e inicie sessão no ecrã que abrir.

Passo a passo

Passo 1 — Adicionar o conector

No terminal, execute o comando abaixo, substituindo o endereço pelo que copiou em Copiar endereço e hk_... pela sua chave:

gemini mcp add --transport http --header "Authorization: Bearer hk_..." heya https://seu-dominio/mcp

Para utilizar o conector em todas as pastas do computador, acrescente -s user. Se preferir editar o ficheiro de configuração (~/.gemini/settings.json), o conteúdo é este:

{
  "mcpServers": {
    "heya": {
      "httpUrl": "https://seu-dominio/mcp",
      "headers": { "Authorization": "Bearer hk_..." }
    }
  }
}

Utilize httpUrl, e não url: no Gemini CLI, url é o formato de ligação antigo e não funciona com o conector.

Passo 2 — Verificar a ligação

Abra o Gemini CLI e escreva /mcp. O conector heya deve aparecer como CONNECTED, com as ferramentas listar_areas, buscar_ferramentas e executar_consulta.

Passo 3 — Fazer uma pergunta

Por exemplo, pergunte: «Que despesas vencem esta semana no estúdio?».

O que acontece depois

O Gemini procura a consulta adequada à pergunta, executa-a e responde com os números do sistema.
A chave aparece no separador API Key com o Último uso atualizado.
Para retirar o acesso, revogue a chave no separador API Key: o Gemini deixa de ter acesso no prazo de 30 segundos.

Erros comuns e dúvidas

P: Funciona no Gemini do navegador (gemini.google.com)? R: Ainda não. O Gemini do navegador pede um início de sessão próprio em vez da chave de API. Utilize o Gemini CLI.

P: O /mcp mostra DISCONNECTED. O que devo fazer? R: Verifique se utilizou httpUrl (e não url), se o endereço termina em /mcp e se copiou a chave completa, incluindo Bearer e um espaço a seguir.

P: O Gemini diz que a chave tem de ter «Permitir utilização como conector de IA». Porquê? R: A chave foi criada sem essa opção. Edite a chave no separador API Key e selecione Permitir utilização como conector de IA.

P: O meu Gemini CLI passou a chamar-se Antigravity CLI. Estas instruções continuam válidas? R: A Google substituiu o Gemini CLI pelo Antigravity CLI em algumas contas. Procure a opção para adicionar um servidor MCP por HTTP com cabeçalho: o endereço e o cabeçalho Authorization: Bearer hk_... são os mesmos.

P: Posso guardar a chave num ficheiro do projeto? R: Evite fazê-lo. O ficheiro .gemini/settings.json da pasta do projeto costuma ser incluído no controlo de versões, o que deixaria a chave exposta. Prefira o ficheiro do seu utilizador (~/.gemini/settings.json).