Guia · Cerca de 3 minutos

Como conectar o Onplana ao Gemini CLI e ao Code Assist

Instalação em uma linha. O Onplana traz um manifesto de extensão do Gemini na raiz do repositório, então toda a configuração é:gemini extensions install <repo>.

Depois você pode pedir ao Gemini coisas como "resuma minhas tarefas atrasadas do Onplana", "crie um plano de projeto para o lançamento do Q3 com 5 marcos semanais" ou "liste os membros da minha equipe no projeto da plataforma de dados", e o Gemini executa direto no Onplana.

Abrir o Onplana → Configurações → Agentes Gemini CLI no GitHub

Resumo: três comandos

# 1. Set your Onplana token
export ONPLANA_PAT=pat_paste-your-token-here

# 2. Install the extension
gemini extensions install https://github.com/Onplana/onplana-mcp-server

# 3. Restart and verify
gemini
> list my Onplana projects via the onplana tool

Os passos detalhados estão abaixo.

Os cinco passos em detalhe

  1. 1

    Instalar o Gemini CLI (se ainda não tiver)

    No macOS / Linux: npm install -g @google/gemini-cli. No Windows: o mesmo comando num terminal com Node. Confira com `gemini --version`. Se você usa o Gemini Code Assist no VS Code ou no JetBrains, já tem o que precisa: o Code Assist compartilha o arquivo de configuração com a CLI.

  2. 2

    Gerar um token de conexão do Onplana

    Entre no Onplana em app.onplana.com. Vá em Configurações → Agentes → Conectar agente, escolha o bloco Gemini CLI + Code Assist, depois Token de acesso pessoal e então Gerar token + mostrar trecho de conexão. Copie o token de acesso pessoal (ele começa com `pat_`). Defina-o como variável de ambiente: export ONPLANA_PAT=pat_your-token-here (acrescente a linha ao ~/.bashrc ou ao ~/.zshrc para mantê-la).

  3. 3

    Instalar a extensão do Gemini do Onplana (um comando)

    Rode: gemini extensions install https://github.com/Onplana/onplana-mcp-server. O repositório do Onplana traz na raiz um manifesto gemini-extension.json, que o Gemini CLI lê para configurar sozinho a conexão com o servidor MCP. Alternativa: edite o ~/.gemini/settings.json à mão; o formato está documentado em developers.google.com/gemini-code-assist/docs.

  4. 4

    Reiniciar o Gemini CLI ou recarregar o editor

    No Gemini CLI: saia e abra o `gemini` de novo. No Gemini Code Assist no VS Code: Cmd/Ctrl+Shift+P → "Developer: Reload Window". No JetBrains: reinicie o IDE. As ferramentas do Onplana aparecem no seletor /mcp depois de reiniciar.

  5. 5

    Conferir a conexão

    Numa sessão nova do Gemini, pergunte: "list my Onplana projects via the onplana tool". O Gemini chama a ferramenta list_projects do Onplana e mostra o resultado. Se der erro, confira se ONPLANA_PAT está definido no ambiente que o Gemini usa e se o manifesto da extensão foi instalado direito, com `gemini extensions list`.

Ou configure à mão

Se preferir não instalar a extensão, edite~/.gemini/settings.json(ou .gemini/settings.json na raiz do espaço de trabalho) diretamente:

{
  "mcpServers": {
    "onplana": {
      "httpUrl": "https://mcp.onplana.com/mcp",
      "headers": {
        "Authorization": "Bearer pat_paste-your-token-here"
      },
      "timeout": 5000
    }
  }
}

Repare que a chave é httpUrl, não url. O Gemini CLI usa httpUrl para servidores Streamable HTTP como o Onplana e reserva url para servidores SSE. O token bearer em headers.Authorization autentica cada requisição.

Como conferir que está funcionando

Abra uma sessão nova do Gemini e tente qualquer uma destas:

  • "Pela ferramenta onplana, liste meus projetos."
  • "Mostre as tarefas atrasadas do Onplana atribuídas a mim."
  • "Crie uma tarefa do Onplana no projeto X chamada ‘Migrar Postgres para Aurora’."
  • "Procure nas minhas páginas do Onplana anotações sobre a migração da API."

Rode gemini extensions list para confirmar que a extensão do Onplana está instalada. Depois de uma instalação bem-sucedida, o seletor /mcp deve mostrar a lista completa de ferramentas do Onplana.

Perguntas frequentes

Funciona com o Gemini Code Assist no VS Code?

Sim. O Gemini CLI e o Gemini Code Assist compartilham o mesmo arquivo de configuração (~/.gemini/settings.json para todo o usuário, ou .gemini/settings.json num espaço de trabalho). Uma instalação com `gemini extensions install` cobre os dois. Depois, recarregue a janela do VS Code (Cmd/Ctrl+Shift+P → "Developer: Reload Window") para o Code Assist pegar a nova configuração.

E o app do Gemini em gemini.google.com?

O gemini.google.com ainda não aceita servidores MCP personalizados em maio de 2026. O Google orienta quem quer se conectar a servidores MCP de terceiros a usar o Gemini CLI ou o Gemini Code Assist. Acompanhamos isso; se o app ganhar suporte a MCP, a instalação será de um clique por uma interface de conectores parecida com a do Claude.ai.

E o Gemini Enterprise / Vertex AI Agent Builder?

O Gemini Enterprise tem outra configuração, diferente do Gemini CLI: um administrador adiciona o Onplana no console do Google Cloud como repositório de dados Custom MCP Server, com um ID de cliente OAuth e um segredo. Está em acesso antecipado e é gerenciado pelo administrador, não é autoatendimento: o Onplana emite o cliente para a sua organização sob pedido. O guia em docs.onplana.com/ai-agents/connect-onplana-to-gemini-enterprise/ traz as configurações, as 20 ações para ligar primeiro e o link para pedir acesso.

Qual plano do Onplana inclui o MCP?

O MCP está incluído em todos os planos, inclusive o gratuito. O número de conexões simultâneas de agentes cresce com o plano (Free 2, Professional 3, Business 5, Enterprise 10, Enterprise+ ilimitadas), e o seu saldo de tokens de IA (uma cota mensal nos planos pagos, um bônus único no Free, mais o crédito comprado) é o que limita o uso real de IA. Você troca de plano quando quiser em app.onplana.com/billing.

Qual a diferença entre instalar pelo gemini-extension.json e editar o settings.json diretamente?

Na prática, nenhuma. A instalação da extensão é um comando e usa um manifesto na raiz do repositório, então é reproduzível. Editar o settings.json à mão serve quando você quer colocar o Onplana junto de vários servidores MCP (por exemplo, um para o Onplana, um para o Linear, um para uma API interna) no mesmo objeto `mcpServers`. Os dois funcionam e compartilham a mesma configuração.

Por que a chave se chama httpUrl e não url?

O Gemini CLI distingue servidores MCP via stdio (chave: command), via SSE (chave: url) e via Streamable HTTP (chave: httpUrl). O servidor MCP do Onplana usa Streamable HTTP, o padrão de transporte mais novo, que trata requisição e resposta em HTTPS simples sem SSE. A chave `url` nas configurações do Claude Desktop, do Cursor e do ChatGPT é a equivalente.

Posso revogar a conexão?

Sim, de duas formas: (1) Onplana → Configurações → Agentes → Conexões → Revogar na linha do token. (2) Remova ONPLANA_PAT do seu ambiente E rode `gemini extensions uninstall onplana`. As duas valem na hora; a próxima chamada de ferramenta do Gemini retorna 401.

A quais ferramentas o Gemini tem acesso?

346 ferramentas, as mesmas que o Claude Desktop, o Cursor e o ChatGPT recebem: leitura (list_projects, list_my_tasks, get_task, search_org_knowledge etc.) e escrita (create_task, update_task, assign_task, create_milestone etc.), além das áreas de governança, controle de mudanças, conformidade, documentos e fluxos de trabalho. O catálogo de ferramentas é o mesmo qualquer que seja o cliente conectado. O plano libera algumas ferramentas; o catálogo completo está em onplana.com/mcp.

Veja também