Servidores MCP no Gemini CLI: como adicionar e configurar

O Gemini CLI é útil assim que você o instala. Ele fica muito mais útil quando consegue acessar seu rastreador de problemas, seu banco de dados ou uma pasta de arquivos de design sem que você precise colar nada no prompt. A ponte é o Model Context Protocol, e cada ponte é um servidor MCP. O Gemini CLI consegue se comunicar com servidores que rodam como processos locais, com servidores atrás de um endpoint HTTP simples e com endpoints de streaming SSE mais antigos. Ele oferece duas formas de registrá-los: um comando gemini mcp add ou algumas linhas em settings.json.

Este artigo percorre as duas formas com comandos reais e depois trata das partes que costumam dar errado: escopos, segredos, filtragem de ferramentas, OAuth e o temido status Disconnected. Todas as flags e campos abaixo vêm da documentação oficial do MCP do Gemini CLI e, quando o comportamento muda entre versões, eu informo.

💡 Resposta rápida: execute gemini mcp add -s user <name> <command-or-url> e depois digite /mcp dentro da CLI. O servidor deve aparecer como conectado e listar as ferramentas dele.

O que os servidores MCP acrescentam ao Gemini CLI

Ao iniciar, o Gemini CLI lê os servidores configurados, se conecta a cada um e pergunta o que ele oferece. O servidor responde com uma lista de ferramentas, e cada ferramenta tem um nome, uma descrição e um esquema JSON para as entradas. O modelo vê essas ferramentas junto com as nativas (leitura de arquivos, comandos de shell, busca na web) e as chama quando um prompt precisa delas.

Ferramentas, prompts e recursos

Um servidor pode expor três tipos de coisas:

• Ferramentas são ações: consultar uma tabela, abrir uma issue, redimensionar uma imagem.
• Prompts são modelos reutilizáveis que podem aparecer como comandos de barra.
• Recursos são dados legíveis, como arquivos ou registros.

A maioria dos servidores traz apenas ferramentas, e é nelas que o esforço de configuração compensa. Tudo o que vem abaixo trata de conectar essas ferramentas com segurança.

Escolha um transporte

Cada entrada de servidor usa exatamente um de três transportes. O campo que você define determina qual deles a CLI usa.

No stdio, a CLI inicia o processo e se comunica com ele pela entrada e saída padrão. Isso significa que um servidor nunca deve imprimir texto solto no stdout. Os logs devem ir para o stderr, senão o fluxo do protocolo quebra e o servidor cai.

Em geral, a escolha já vem decidida. Se o servidor é um pacote ou um script na sua máquina, use stdio. Se ele fica em uma URL e o fornecedor oferece HTTP e SSE, escolha HTTP, já que SSE é o transporte mais antigo e existe principalmente para servidores que ainda não migraram.

Adicione um servidor com um comando

Se gemini ainda não estiver no seu PATH, instale-o com npm install -g @google/gemini-cli. Depois disso, o comando add é o caminho mais rápido.

A sintaxe de gemini mcp add

gemini mcp add [options] <name> <commandOrUrl> [args...]

Copiar prompt

O nome vem primeiro, depois o executável ou a URL e, por fim, os argumentos que o servidor exigir. As opções que você mais vai usar:

Exemplos locais em stdio e remotos

Um script local, salvo para o seu usuário para funcionar em todas as pastas:

gemini mcp add -s user -e ISSUES_TOKEN='$ISSUES_TOKEN' issues node /home/me/mcp/issues-server.js

Copiar prompt

Um servidor hospedado por HTTP streamable, com um cabeçalho bearer:

gemini mcp add --transport http --header "Authorization: Bearer abc123" docs-search https://mcp.example.com/mcp

Copiar prompt

Um endpoint SSE mais antigo:

gemini mcp add --transport sse legacy-events http://localhost:8080/sse

Copiar prompt

O gerenciamento do dia a dia usa a mesma família de comandos:

gemini mcp list
gemini mcp disable issues --session
gemini mcp enable issues
gemini mcp remove issues -s user

Copiar prompt

A flag --session em enable e disable altera o estado apenas para a sessão atual. Sem ela, a escolha é salva em ~/.gemini/mcp-server-enablement.json.

💡 Cuidado com as aspas. No primeiro exemplo, as aspas simples mantêm $ISSUES_TOKEN como um placeholder. Com aspas duplas, o shell expande a variável antes e o token real acaba em settings.json. Abra o arquivo depois de adicionar um servidor e confira.

💡 Argumentos que começam com hífen, como npx -y, podem ser confundidos com opções da CLI pelo analisador de flags. Para servidores iniciados dessa forma, escreva a entrada em settings.json.

Edite o settings.json à mão

O comando add escreve o JSON para você. Editar esse JSON diretamente dá acesso a todos os campos, mantém sua configuração revisável em um pull request e facilita copiar um bloco que funciona para um colega.

Escopo do usuário ou escopo do projeto

• Escopo do usuário: ~/.gemini/settings.json. Ele acompanha você em todas as pastas.
• Escopo do projeto: .gemini/settings.json dentro do repositório. Faça commit dele e toda a equipe recebe os mesmos servidores.

O arquivo do projeto é lido depois do arquivo do usuário, então ele prevalece quando os dois definem o mesmo nome de servidor. Lembre-se de que gemini mcp add grava no escopo do projeto, a menos que você passe -s user.

Um arquivo funcional com vários servidores

Este arquivo registra um servidor por transporte:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"],
      "timeout": 30000
    },
    "issues": {
      "command": "node",
      "args": ["./mcp/issues-server.js"],
      "cwd": "/home/me/work/tracker",
      "env": { "ISSUES_TOKEN": "$ISSUES_TOKEN" },
      "includeTools": ["search_issues", "get_issue"]
    },
    "docs-search": {
      "httpUrl": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer abc123" },
      "timeout": 15000
    },
    "legacy-events": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Copiar prompt

Veja o que cada campo faz:

Mantenha os segredos fora do arquivo

Dentro do bloco env, o Gemini CLI expande $NAME e ${NAME} em todas as plataformas, e %NAME% no Windows. Uma variável que não está definida vira uma string vazia, sem nenhum aviso. O resultado é um servidor que inicia e depois falha na autenticação, o que parece um bug do servidor quando na verdade é um erro de digitação no nome de uma variável.

Um arquivo de projeto costuma ser versionado, então referencie variáveis e nunca cole um segredo nele. A expansão está documentada para o bloco env, então, se você quiser um token em headers, confirme que a sua versão da CLI expande o valor, ou mantenha essa entrada no escopo do usuário, onde ela nunca chega ao controle de versão.

Limite o acesso e trate a autenticação

Conectar um servidor entrega ao modelo um novo conjunto de capacidades. Decida quanto disso você quer antes do primeiro prompt.

Filtre ferramentas por servidor

Digamos que um servidor exponha search_issues, get_issue e delete_issue. Você quer as duas primeiras e nunca a terceira:

"issues": {
  "command": "node",
  "args": ["./mcp/issues-server.js"],
  "includeTools": ["search_issues", "get_issue"],
  "excludeTools": ["delete_issue"]
}

Copiar prompt

excludeTools tem prioridade, então uma ferramenta listada nas duas está desligada. Você também pode filtrar servidores inteiros no nível superior de settings.json:

"mcp": {
  "allowed": ["issues", "filesystem"],
  "excluded": ["experimental-server"]
}

Copiar prompt

Quando mcp.allowed está definido, só os servidores citados ali se conectam. mcp.excluded bloqueia os que você listar.

Use a confiança com moderação

Por padrão, o Gemini CLI pede permissão antes de executar uma ferramenta. Definir "trust": true, ou passar --trust ao adicionar um servidor, desliga todas as confirmações para esse servidor. Isso é razoável para um servidor somente leitura que você mesmo escreveu. É uma má ideia para qualquer coisa que possa gravar arquivos, enviar mensagens ou executar comandos, porque um prompt ruim poderia acioná-lo sem que você visse antes.

OAuth com /mcp auth

Muitos servidores hospedados exigem login. Dentro da CLI, execute /mcp auth para listar os servidores que oferecem suporte a OAuth e depois autentique um deles pelo nome:

/mcp auth docs-search

Copiar prompt

A CLI abre o navegador, conclui o fluxo e guarda o token em ~/.gemini/mcp-oauth-tokens.json. Tokens expirados são renovados automaticamente. Quando um servidor não publica os detalhes do OAuth, adicione você mesmo um bloco oauth:

"oauth": {
  "enabled": true,
  "clientId": "gemini-cli-client",
  "authorizationUrl": "https://auth.example.com/oauth/authorize",
  "tokenUrl": "https://auth.example.com/oauth/token",
  "scopes": ["mcp:read"]
}

Copiar prompt

Cabeçalhos estáticos e credenciais do Google

Nem todo servidor usa OAuth. Um token bearer fixo vai em headers, como mostrado antes. Para serviços do Google Cloud, o campo authProviderType aceita google_credentials, além de service_account_impersonation junto com targetServiceAccount. Para servidores atrás do Identity-Aware Proxy, adicione targetAudience com o ID do cliente OAuth. O provedor padrão funciona para a maioria dos outros servidores, então deixe o campo de lado, a menos que precise de um desses casos.

Confira se tudo funciona

Edite o arquivo e depois execute /mcp reload. Se a CLI ainda mostrar as configurações antigas, reinicie a sessão.

Verifique com os comandos /mcp

Fora de uma sessão, gemini mcp list mostra o mesmo panorama de conexões direto do shell.

Como os nomes das ferramentas aparecem

Versões recentes mostram as ferramentas MCP com um nome totalmente qualificado no formato mcp_<server>_<tool>. Uma ferramenta search_issues em um servidor chamado issues vira mcp_issues_search_issues. Textos mais antigos descrevem um prefixo server__tool, usado quando dois servidores expõem uma ferramenta com o mesmo nome. Se você vê um estilo em um tutorial e o outro na sua tela, provavelmente está em uma versão diferente.

Duas consequências práticas seguem daí. Primeiro, dê nomes aos servidores com hífens, não com sublinhados. O nome é separado no primeiro sublinhado depois de mcp_, e um sublinhado dentro do nome de um servidor pode confundir as regras de política. Segundo, você raramente precisa do nome completo no prompt. Peça em linguagem natural, por exemplo:

Use the issues server to list open bugs labelled regression, newest first.

Copiar prompt

A CLI mostra qual ferramenta pretende chamar e pede confirmação, a menos que você defina trust.

Corrija servidores que não conectam

Comece pelas verificações básicas, porque elas resolvem a maioria dos casos:

1. Execute o command e o args exatos em um terminal normal. Se falhar ali, falha também na CLI.
2. Confirme que cwd existe e que node, npx ou python3 está no seu PATH.
3. Inicie a CLI com --debug e leia os erros de conexão.
4. Verifique o stderr do servidor em busca de stack traces.
5. Execute /mcp reload depois de cada edição e reinicie a CLI se as configurações antigas parecerem persistir.

Disconnected em pastas não confiáveis

Este caso pega as pessoas o tempo todo. Em uma pasta que você não marcou como confiável, o Gemini CLI não se conecta a nenhum servidor MCP e ignora por completo o .gemini/settings.json do projeto. O arquivo do escopo do usuário é lido, mas os servidores do projeto simplesmente não aparecem.

Execute /permissions dentro da CLI para confiar na pasta, ou responda ao diálogo de confiança na primeira vez que você a abrir. A escolha fica salva em ~/.gemini/trustedFolders.json. Para execuções sem interface, a documentação lista a flag --skip-trust e a variável GEMINI_CLI_TRUST_WORKSPACE=true.

Tempos limite e falhas silenciosas

Algumas falhas não dão erro nenhum:

• Nenhuma ferramenta listada: o servidor conectou, mas não registrou nada, ou os esquemas das ferramentas são um JSON Schema inválido. Verifique /mcp schema.
• Chamadas de ferramenta travadas: o tempo limite padrão é de dez minutos. Reduza timeout para servidores remotos instáveis, ou aumente-o para tarefas lentas, como consultas grandes.
• Erros de autenticação depois de um início limpo: procure uma variável não definida em env. Ela foi expandida para uma string vazia.
• Ferramenta ausente da lista: verifique includeTools e excludeTools, e a lista mcp.allowed no nível superior.

💡 Um teste rápido de sanidade: adicione primeiro um servidor stdio pequeno, faça-o conectar e só então adicione os servidores remotos. Cada servidor novo é mais uma coisa que pode falhar, então adicione-os um de cada vez.

Rascunhe configurações com o Gemini no Picasso IA

Você pode usar um modelo de linguagem para rascunhar as partes repetitivas de uma configuração, e o Picasso IA hospeda vários modelos Gemini que você pode abrir no navegador. Este é um fluxo de trabalho que funciona bem:

1. Abra a página do Gemini 3.5 Flash para rascunhos rápidos. Para arquivos longos com vários servidores ou autenticação complicada, experimente o Gemini 3.1 Pro. O Gemini 3 Flash é outra opção para iterar com rapidez.
2. Cole a seção de configuração do README do servidor MCP e depois acrescente suas restrições: sistema operacional, escopo e qual variável de ambiente guarda o token.
3. Peça duas saídas: a entrada settings.json e o comando gemini mcp add equivalente. Diga ao modelo para usar referências $VARIABLE em vez de segredos literais.
4. Confira a resposta com a tabela de campos acima. Exatamente um entre command, url ou httpUrl deve estar presente, e cada nome em includeTools deve coincidir com o que /mcp desc exibe.
5. Cole a entrada no seu arquivo e execute /mcp reload.

💡 Trate o rascunho como uma primeira versão. Um modelo pode inventar um campo que parece correto. As tabelas deste artigo e a documentação oficial são sua fonte de verdade.

Crie suas próprias imagens no Picasso IA

Uma boa configuração de MCP é só metade de um fluxo de trabalho de desenvolvimento bem organizado. A outra metade é o material ao redor: banners do README, ilustrações de tutoriais, cards para redes sociais e fotos para o post do blog que explica a sua configuração.

O Picasso IA permite gerar essas imagens em poucos minutos. Experimente o Seedream 4.5 para cenas fotorrealistas detalhadas, o GPT Image 2 quando precisar de texto limpo dentro da imagem, ou o Nano Banana 2 Lite para rascunhos rápidos. Escreva um prompt curto, gere algumas variações e fique com a que combina com a sua página.

Escolha um projeto que você tenha aberto hoje, escreva um prompt descrevendo o banner dele e veja o que aparece. Explore todos os modelos disponíveis em picassoia.com/en/all-models e comece por aquele que combina com o visual que você tem em mente.