Como criar um servidor MCP com a CLI do Gemini e o Go

1. Introdução

Neste codelab, você vai aprender a criar e implantar um servidor de Protocolo de Contexto de Modelo (MCP) para ampliar os recursos da CLI do Gemini. Você vai criar o godoctor, um servidor baseado em Go que fornece ferramentas personalizadas para desenvolvimento. Com isso, a CLI do Gemini deixa de ser um assistente de programação de uso geral e passa a atuar como um especialista em desenvolvimento em Go.

Este codelab usa uma abordagem orientada por comandos. Você vai atuar como líder técnico e fornecer comandos para o assistente de IA, a CLI do Gemini. O objetivo é aprender a transformar os requisitos do projeto em comandos eficazes e deixar que a IA cuide dos detalhes da implementação.

O Protocolo de Contexto de Modelo (MCP) é a parte essencial deste projeto. O MCP é um protocolo de código aberto que padroniza como os modelos de linguagem grandes (LLMs), como o Gemini, se comunicam com ferramentas e serviços externos. Como ele atua como uma ponte, a IA acessa informações do mundo real e realiza ações além do conhecimento integrado. O servidor MCP criado atua como um plug-in personalizado que a CLI do Gemini pode integrar e usar, o que vai ensinar novas habilidades a ela.

O que você vai aprender

• Como instalar e configurar a CLI do Gemini
• Como elaborar comandos eficazes para orientar um assistente de IA no desenvolvimento de software
• Como fornecer contexto e diretrizes para um assistente de IA
• Como criar e configurar um servidor MCP para aumentar os recursos da CLI do Gemini
• Como conteinerizar e implantar um aplicativo Go no Google Cloud Run

O que é necessário

Este workshop pode ser feito inteiramente no Google Cloud Shell, que já vem com todas as dependências necessárias (CLI gcloud, Go, Docker, CLI do Gemini) pré-instaladas.

Como alternativa, se você preferir trabalhar na sua própria máquina, vai precisar do seguinte:

• Node.js 20 ou mais recente
• O SDK do Google Cloud (CLI gcloud) instalado e inicializado
• Go 1.24 ou mais recente instalado no seu sistema
• O Docker está instalado no sistema.

Principais tecnologias

Confira mais informações sobre as tecnologias que vamos usar:

• CLI do Gemini: a interface de linha de comando com tecnologia de IA que vamos estender
• Protocolo de Contexto de Modelo (MCP): o protocolo de código aberto que a CLI do Gemini usa para se comunicar com nossa ferramenta personalizada
• SDK Go para MCP: a biblioteca Go que vamos usar para implementar nosso servidor MCP

Dicas para um codelab de sucesso

Trabalhar com um assistente de IA é uma nova forma de desenvolver software. Confira algumas dicas para ter uma experiência tranquila e bem-sucedida:

1. Não tenha medo de apertar ESC. Às vezes, a IA vai propor ações ou códigos, mas você não vai concordar com eles. Pressione a tecla ESC para cancelar a ação proposta e insira um novo comando que a direcione de forma mais adequada. Você está no controle.
2. Incentive o uso de ferramentas. Incentive a IA a usar as ferramentas disponíveis, se ela parecer confusa ou inventar informações. Comandos como "Você pode usar a Pesquisa Google para verificar isso?" ou "Use a ferramenta 'read_file' para entender o código antes de fazer alterações" podem ser muito eficazes.
3. Não faça alterações manuais. A IA deve realizar todo o trabalho. Essa é a habilidade principal que você está praticando. No entanto, se você precisar fazer uma alteração manual, informe a IA em seguida. Um comando como "Atualizei manualmente o arquivo README.md. Leia de novo para atualizar seu conhecimento" vai ajudar a IA a ficar sincronizada com o projeto.
4. Você já tentou desligar e ligar novamente? Em casos raros, a IA pode tentar forçar um caminho específico contra seu comando. Isso pode acontecer devido à degradação do contexto, às vezes chamada de "context rot". Nesse caso, use o comando "/compress" da CLI do Gemini para reduzir o ruído do contexto. Em casos extremos, use o comando "/clear" para limpar todo o histórico da sessão.

2. Configuração do ambiente

Para créditos do Google Cloud:para ajudar você a começar, resgate seus créditos sem custo financeiro do Google Cloud usando este link. Siga as instruções aqui para ativar o crédito e criar um projeto.

Escolha uma das seguintes opções: Configuração do ambiente no seu ritmo se quiser executar este

codelab na sua própria máquina ou Iniciar o Cloud Shell se quiser executar este codelab totalmente na nuvem.

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

3. Como começar a usar a CLI do Gemini

Nesta seção, você vai aprender a instalar e configurar a CLI do Gemini no seu ambiente.

O que é a CLI do Gemini?

A CLI do Gemini é uma interface de linha de comando com tecnologia de IA que ajuda com várias tarefas de desenvolvimento. Ela entende o contexto do projeto, responde a perguntas, gera códigos e usa ferramentas externas para ampliar os recursos.

Instalação

Observação:se você estiver usando o Google Cloud Shell, a CLI do Gemini já estará instalada. Você pode pular para a próxima seção (Configuração).

Instale a CLI do Gemini globalmente usando o npm.

npm install -g @google/gemini-cli

Para confirmar se a CLI está instalada, execute:

gemini --version

Configuração

O comportamento da CLI do Gemini é controlado por arquivos de configuração e variáveis de ambiente. Há dois arquivos principais:

• GEMINI.md: esse arquivo fornece diretrizes e contexto para a IA. A CLI lê esse arquivo para entender os padrões e convenções de programação do projeto.
• .gemini/settings.json: esse arquivo controla a configuração da CLI, incluindo como se conectar a ferramentas externas. Vamos usar esse arquivo mais tarde para configurar a CLI e usar o servidor MCP que estamos criando neste laboratório.

Primeiro, vamos configurar o ambiente e criar o arquivo GEMINI.md. O arquivo settings.json será configurado em uma etapa posterior.

1. Crie e inicialize um diretório de projeto:

mkdir godoctor && cd godoctor
go mod init godoctor

2. Faça a autenticação com as credenciais padrão do aplicativo do Google Cloud:

Observação:se você estiver usando o Cloud Shell, a autenticação já estará coberta.

Faça login em uma conta que tenha acesso ao projeto do GCP que você vai usar neste codelab:

• Verifique se o SDK do Google Cloud está instalado e inicializado.
• Execute o comando a seguir para configurar as credenciais padrão do aplicativo:

gcloud auth application-default login

4. Arquivo de contexto (GEMINI.md)

Os arquivos de contexto, que usam o nome padrão GEMINI.md, são usados para fornecer contexto instrucional ao modelo Gemini. Você pode usar esses arquivos para dar instruções específicas do projeto, definir um perfil ou fornecer guias de estilo de programação para tornar as respostas da IA mais precisas e personalizadas para suas necessidades.

Para garantir que o assistente de IA gere códigos Go idiomáticos e de alta qualidade, vamos escrever um GEMINI.md com algumas práticas recomendadas comuns para desenvolvedores Go.

Objetivo: criar um arquivo GEMINI.md que vai atuar como o conjunto de regras para o assistente de IA durante este projeto.

Abra seu ambiente de desenvolvimento integrado (IDE) para criar o arquivo GEMINI.md com o conteúdo abaixo. Se você estiver usando o Cloud Shell, abra um editor com o comando abaixo:

cloudshell edit .

Tarefa: crie um arquivo chamado GEMINI.md na raiz do diretório godoctor e cole o seguinte conteúdo nele.

# Go Development Guidelines
All code contributed to this project must adhere to the following principles.

## 1. Formatting
All Go code **must** be formatted with `gofmt` before being submitted.

## 2. Naming Conventions
- **Packages:** Use short, concise, all-lowercase names.
- **Variables, Functions, and Methods:** Use `camelCase` for unexported identifiers and `PascalCase` for exported identifiers.
- **Interfaces:** Name interfaces for what they do (e.g., `io.Reader`), not with a prefix like `I`.

## 3. Error Handling
- Errors are values. Do not discard them.
- Handle errors explicitly using the `if err != nil` pattern.
- Provide context to errors using `fmt.Errorf("context: %w", err)`.

## 4. Simplicity and Clarity
- "Clear is better than clever." Write code that is easy to understand.
- Avoid unnecessary complexity and abstractions.
- Prefer returning concrete types, not interfaces.

## 5. Documentation
- All exported identifiers (`PascalCase`) **must** have a doc comment.
- Comments should explain the *why*, not the *what*.

## 6. Project structure
- cmd/ contains source code for target binaries (e.g. server, client)
- internal/ contains source code for packages not meant to be exported (e.g. internal/tools/hello)
- bin/ contains the compiled binaries
- At the root place README.md, go.mod and go.sum

Agora o ambiente de desenvolvimento está totalmente configurado.

5. O build inicial: um servidor de documentação

Sua primeira meta é criar a versão inicial do servidor godoctor. Essa versão deve ser um aplicativo mínimo que fornece uma única ferramenta chamada read_docs, para pesquisa na documentação do Go.

Objetivo: criar um servidor MCP pronto para produção que exponha o comando go doc, permitindo que um LLM consulte a documentação do Go.

Execute o comando da CLI do Gemini no shell:

gemini

Importante:se você precisar instalar ou atualizar a CLI do Gemini no Cloud Shell, use este comando: sudo env PATH=$PATH npm install -g @google/gemini-cli

Ao executar a CLI pela primeira vez, ela vai pedir para você escolher um modo de autenticação e um tema.

Se você estiver executando este codelab no Cloud Shell, escolha a opção Usar credenciais de usuário do Cloud Shell. Caso contrário, use o login com o Google para fazer login com uma Conta do Google pessoal e aproveitar o nível sem custos financeiros generoso da CLI do Gemini. A tela de seleção de autenticação será parecida com esta:

Se você precisar mudar a seleção, digite /auth e pressione Enter para abrir o menu novamente.

Em seguida, você vai precisar escolher um tema:

Assim como em /auth, também é possível mudar o tema depois com o comando /theme.

Depois de escolher o método de autenticação e o tema, você vai ser direcionado para o prompt de comando. Aqui você pode digitar seus comandos, por exemplo:

Write a hello world application in Go

Para realizar tarefas, a CLI combina o próprio raciocínio (usando um modelo do Gemini, como o Gemini Flash ou o Gemini Pro) com ferramentas. Ela usa ferramentas sempre que precisa interagir com o sistema de arquivos ou serviços externos, como APIs, bancos de dados etc. Os exemplos de ferramentas prontas para uso, ou "ferramentas internas", são read_file, write_file, web_fetch e google_search. O servidor MCP que estamos criando também vai se tornar uma ferramenta disponível para a CLI.

Na primeira vez que ele executar uma ferramenta, vai pedir sua permissão. É possível dar uma permissão única (permitir uma vez), uma aprovação geral para o resto da sessão (permitir sempre) ou negar a solicitação. Se for uma operação de edição de arquivos e você quiser fazer alguns ajustes, há a opção de usar um editor externo. Por exemplo, esta é a saída da instrução acima para criar um programa "Hello World":

Além dos prompts, também é possível usar os comandos de barra. Ao digitar "/", a CLI mostra as opções de preenchimento automático. Você digita o comando completo ou seleciona uma das opções. Os comandos /auth e /theme mencionados acima são exemplos desse tipo de comando.

Depois de se familiarizar com a interface, comece a principal tarefa desta seção, que é pedir à CLI para escrever o servidor MCP.

Como criar um servidor MCP Hello World

Uma das melhores maneiras de garantir que o modelo crie de forma mais consistente é dividir tarefas complexas em etapas incrementais. Embora o modelo consiga conceber uma tarefa complexa por conta própria, sem a configuração correta, ele vai demorar muito para determinar a implementação apropriada.

Para uma abordagem mais consistente, vamos instruir o modelo a criar um servidor MCP "Hello World" antes de implementar a funcionalidade pretendida (ler a documentação do Go).

Confira um exemplo de comando abaixo:

Create a Model Context Protocol (MCP) server that exposes a "hello_world" tool. This tool, when called, should return the message "Hello, MCP world!"

For the MCP implementation, you should use the official Go SDK for MCP (github.com/modelcontextprotocol/go-sdk/mcp) and use the stdio transport.

TODO:
- Download the dependency: `go get github.com/modelcontextprotocol/go-sdk/mcp`
- Inspect the documentation of the SDK: `go doc github.com/modelcontextprotocol/go-sdk/mcp`
- Build a `server` command that supports stdio transport only
- Build a `client` command that connects to the server over command transport to test the server

Acceptance Criteria:
- `./bin/client --list-tools` returns the list of server tools including "hello_world"
- `./bin/client --call-tool` "hello_world" returns the output "Hello, MCP world!"

O comando acima é composto por três segmentos principais:

1. A especificação do problema, incluindo o que deve ser criado e as restrições (por exemplo, usar o SDK oficial em vez de qualquer outro, transporte stdio em vez de http)
2. Detalhes das tarefas a serem realizadas (TODOs)
3. Critérios de aceitação da tarefa, que funcionam como um procedimento de teste para que o agente saiba quando ela está concluída

Com esses três componentes, o modelo alcança os resultados pretendidos de forma mais consistente.

Atenção:mesmo quando as instruções são muito precisas, às vezes, o modelo se desvia do que foi pedido. Por isso, é importante verificar o trabalho dele e ficar atento a possíveis repetições de erro e alucinações. Se o modelo ficar preso, consulte a seção "Dicas úteis" no final deste capítulo.

A implementação da ferramenta read_docs

Observação:o comando abaixo incentiva explicitamente o modelo a usar o comando shell go doc, porque o código para recuperar a documentação usando a biblioteca padrão é complexo, e o modelo pode demorar muito para descobrir por conta própria. Usar a ferramenta go doc integrada ao compilador economiza muito tempo e ajuda a focar no que é importante, que é a implementação do MCP.

Depois da configuração inicial, passe para a implementação da ferramenta "read_docs" real:

Add a new tool to our MCP server called "read_docs" that invokes the "go doc" shell command. The tool will take a mandatory "package" argument and an optional "symbol" argument.

TODO:
- create a package `./internal/tools/docs`
- register the tool with the MCP server
- update the client to support the "read_docs" tool by providing arguments to the tool call

Acceptance Criteria:
- `./bin/client --tools-list` show both hello_world and read_docs
- `./bin/client --tool-call read_docs fmt` returns the documentation for the `fmt` package
- `./bin/client --tool-call read_docs fmt.Println` returns the documentation for the `fmt.Println` function
- `./bin/client --tool-call read_docs github.com/modelcontextprotocol/go-sdk/mcp` returns documentation for the `mcp` package

Observação: use esse comando ou crie o seu próprio.

Dicas úteis

Observação:a programação com LLMs não é uma experiência determinística. Nem sempre é possível ter os mesmos resultados, mesmo que dois comandos idênticos sejam executados com o mesmo ambiente. Por isso, é importante aprender a identificar quando o LLM está preso em uma repetição ou com o contexto degradado. Você está no controle e pode pressionar ESC a qualquer momento para interromper o processo.

Como o MCP é um conceito recente e o SDK para Go do MCP é uma biblioteca nova, o Gemini pode demorar muito para descobrir a implementação correta por conta própria. Para ajudar o modelo a encontrar a solução certa, tente o seguinte:

1. Se o modelo pulou a leitura da documentação em alguma etapa, pressione ESC e lembre-o de fazer isso. Se você não conhece o Go, execute "go doc" mais o nome do pacote "go doc github.com/modelcontextprotocol/go-sdk/mcp" para retornar a documentação correta.
2. O módulo de nível superior " github.com/modelcontextprotocol/go-sdk" não tem documentação (porque não tem código Go). É necessário informar ao modelo para procurar o caminho completo.
3. Por outro lado, se o modelo alucinar um pacote que não existe, por exemplo, "go doc github.com/modelcontextprotocol/go-sdk/mcp/server", basta direcionar para o pacote de nível superior.

6. Configurar o godoctor como um servidor MCP para a CLI do Gemini

Depois que o assistente de IA gerar o código para o cliente e o servidor, é possível instruí-lo a executar alguns testes manuais. Exemplo:

retrieve the documentation for the package net/http

Teste com uma dependência externa (que não está na biblioteca padrão):

retrieve the documentation for the github.com/modelcontextprotocol/go-sdk/mcp package

Quando os resultados estiverem adequados, use o comando a seguir para pedir para o assistente escrever um arquivo README.md com instruções sobre como usar e desenvolver este projeto:

Now write a detailed README.md file explaining both from a user and a developer perspective how to use and to build this project.

Agora vamos configurar o servidor para que a CLI do Gemini possa usá-lo na próxima fase de desenvolvimento.

1. Peça à CLI para atualizar o arquivo GEMINI.md e usar read_docs como o método de preferência para ler a documentação:

update the GEMINI.md file to include instructions to always use the read_docs tool to retrieve documentation about Go packages or symbols. This should be done whenever seeing an import for the first time in a session or after a new dependency is installed to the project (e.g. via `go get`)

2. Agora, reinicie a CLI do Gemini para configurar o servidor MCP. Primeiro, vamos salvar a sessão de chat para que você possa retomar de onde parou quando ela for reiniciada.

/chat save godoctor-workshop

3. Pressione Ctrl+D duas vezes ou digite o comando /quit para sair da CLI.
4. Nas etapas anteriores, o agente compilou um binário de servidor para você, mas vamos compilar o servidor novamente com um nome diferente para que ele não seja afetado quando modificarmos o código-fonte:

mkdir -p bin && go build -o ./bin/godoctor ./cmd/server

5. Configure a CLI do Gemini para a ferramenta local: crie um arquivo .gemini/settings.json na raiz do projeto e adicione uma seção mcpServers para informar à CLI do Gemini como executar o servidor compilado.

mkdir -p .gemini && touch .gemini/settings.json

6. Agora, adicione o conteúdo a seguir ao novo arquivo usando o editor do Cloud Shell ou seu ambiente de desenvolvimento integrado favorito.

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor"
    }
  }
}

7. Iniciar a CLI do Gemini com o comando gemini
8. Para verificar se a ferramenta foi carregada, digite o comando /mcp. Você também pode mostrar a descrição completa das ferramentas usando /mcp desc:

9. Teste a integração pedindo à CLI do Gemini para usar sua ferramenta com um comando como "Mostre a documentação do pacote net/http".

Você verá algo como:

Observação:se o modelo tentar ler a documentação usando run_shell_command, cancele e redirecione para usar a ferramenta que acabamos de desenvolver.

Se a ferramenta estiver funcionando corretamente, a documentação recuperada pela chamada será exibida:

Parabéns, você criou uma ferramenta de MCP. Mas ainda não acabou. Podemos deixar esse servidor um pouco mais útil.

7. Adicionar um revisor de código com tecnologia de IA

Vamos adicionar um recurso mais sofisticado com tecnologia de IA: um revisor de código que usa a API Gemini.

Agora você pode restaurar a sessão de chat anterior com o comando /chat resume godoctor-workshop.. Isso vai carregar o contexto da sessão até o ponto em que terminamos de desenvolver read_docs. Assim, o modelo terá o conhecimento necessário para criar a nova ferramenta.

Essa ferramenta precisa de acesso à Vertex AI. Portanto, primeiro ative a API. É possível executar comandos do shell sem sair da CLI do Gemini digitando um ponto de exclamação (!) em um prompt vazio. Isso vai mudar a CLI do Gemini para o modo shell.

Execute o seguinte comando no modo shell para ativar a API Vertex AI:

gcloud services enable aiplatform.googleapis.com

Quando o comando for concluído, digite a tecla Esc para voltar ao modo de solicitação.

Importante:o SDK go-genai vai usar as variáveis de ambiente definidas na etapa de configuração deste workshop: GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION.. Se tiver problemas, verifique se essas variáveis estão definidas corretamente no seu ambiente.

Não é possível mudar variáveis de ambiente no modo shell da CLI do Gemini. As mudanças não são permanentes. Portanto, saia da CLI, defina as variáveis e inicie a CLI novamente.

Objetivo: adicionar uma nova ferramenta chamada code_review ao projeto atual. Essa ferramenta vai usar a API Gemini para analisar o código Go e fornecer feedback.

Exemplo de comando:

Add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with model id gemini-2.5-pro) to analyze Go code and provide a list of improvements according to the best practices accepted by the Go community.

The tool should take the Go code content and an optional hint as input. The hint will be used to provide additional guidance for the AI reviewer, like "focus on security" or "help me simplify this code".

The tool output should be text in Markdown format.

TODO:
- add the genai SDK dependency with `go get import google.golang.org/genai`
- create the tool code in ./internal/tools/code/review.go
- create a code review prompt to be used by the tool
- use go-genai with Vertex AI authentication to call gemini-2.5-pro
- register the tool with the server
- add a flag to the server to set the Google Cloud Project ID: --project
- add a flag to the server to set the Google Cloud Location: --location
- add support to the review tool in the client CLI

NOT TO DO:
- DO NOT use the package github.com/google/generative-ai-go/genai as it is DEPRECATED
- DO NOT use the package cloud.google.com/go/vertexai/genai as it has been superseded by google.golang.org/genai

Acceptance Criteria:
- `./bin/client --tools-list` show all tools including `code_review`
- `./bin/client --tool-call code_review internal/tools/code/review.go` returns the code review for the "review.go" file

Dicas úteis

1. Assim que o modelo começar a trabalhar nisso, você poderá ver automaticamente uma solicitação para chamar a ferramenta read_docs e navegar pela documentação do pacote genai. Se não for, você sempre pode interromper o processo com a tecla "Esc" e lembrar que agora ele tem a ferramenta read_docs à disposição.
2. Se você notar que ele está tentando usar o SDK de IA generativa errado (mesmo que haja uma lista clara de "não permitido" no comando), direcione-o de volta para o SDK correto.

Testar o revisor de código

1. Salve a sessão de chat com /chat save godoctor-workshop e saia da CLI pressionando Ctrl+D duas vezes.
2. Recompile o servidor com a nova definição de ferramenta:

go build -o ./bin/godoctor ./cmd/server

3. Usando seu ambiente de desenvolvimento integrado, atualize o arquivo .gemini/settings.json para incluir a configuração de ambiente da Vertex AI:

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor",
      "env": {
        "GOOGLE_CLOUD_USE_VERTEXAI": "true",
        "GOOGLE_CLOUD_PROJECT": "<your-project-id>",
        "GOOGLE_CLOUD_LOCATION": "<your-preferred-region>"
      }
    }
  }
}

4. Inicie a CLI do Gemini novamente. Restaurar a sessão de chat com /chat resume godoctor-workshop
5. Confirme se a ferramenta está ativada digitando o comando /mcp. Você verá algo como:

6. Agora vamos testar a ferramenta code_review analisando um dos arquivos de origem dela:

Use the code_review tool to review cmd/server/main.go

    You should see something like this:

Com a ferramenta de análise de código funcionando, agora você pode sugerir que o modelo aplique algumas das melhorias encontradas para um fluxo de trabalho completo de "autoaprimoramento".

Agora você confirmou que a ferramenta code-review funciona. Na próxima seção, você vai trabalhar na implantação na nuvem. Salve a sessão atual com /chat save godoctor-workshop e saia da CLI.

8. preparar o servidor para a nuvem

O servidor MCP que desenvolvemos até agora só funciona na máquina local, o que é bom se as ferramentas forem para uso próprio. No entanto, em ambientes corporativos, muitas vezes é necessário implantar ferramentas para centenas ou até milhares de desenvolvedores usarem.

Para escalonar o servidor MCP, é necessário convertê-lo de um servidor que só usa E/S padrão para um servidor que usa HTTP e implantá-lo onde diferentes desenvolvedores possam acessá-lo. Para isso, use o modo de transporte definido como HTTP transmissível na especificação do MCP e o Cloud Run como o destino da implantação.

Objetivo: refatorar o servidor godoctor para usar o transporte HTTP transmissível.

Exemplo de comando:

The godoctor server is currently using the stdio transport. I want to prepare it to be deployed to Cloud Run, so we need to add support to use the Streamable HTTP transport.

TODO:
- Update server to enable Streamable HTTP via the -http flag.
- An optional -listen flag can be specified to set the port to listen
- If no -http flag is specified, the server defaults to stdio transport and -listen is ignored
- Update client to use Streamable HTTP via the -addr flag
- If no flag is specified, the client defaults to command transport
- Create a shell script test_server.sh to support testing

NOT TO DO:
- DO NOT use the HTTP+SSE protocol as it has been deprecated by the MCP specification

Acceptance Criteria
- Create a shell script that:
  - Runs the server in the background;
  - Runs the client connecting over HTTP and call list tools
  - Kills the background process
- The shell script should run without failures

Dicas úteis

1. O modelo pode tentar usar HTTP+SSE, que foi descontinuado. Se ele tentar seguir esse caminho, direcione-o para o HTTP transmissível.
2. A versão atual da CLI do Gemini (0.26.0) não oferece suporte à execução de processos em segundo plano. Qualquer processo iniciado com run_shell_command é encerrado quando a chamada de ferramenta retorna. Por isso, pedimos ao Gemini para automatizar o processo de teste usando um script. Esse recurso está planejado e será adicionado em breve, o que pode simplificar o processo de teste.

Opcional: testar o servidor MCP usando HTTP

Se você quiser configurar a CLI do Gemini para usar o servidor via HTTP:

1. Salve a sessão e saia da CLI
2. Edite o arquivo .gemini/settings.json e mude a configuração para apontar para o servidor local em execução.

"mcpServers": {
  "godoctor": {
    "httpUrl": "http://localhost:8080"
  }
}

3. Em um segundo terminal, execute o servidor ativado por HTTP localmente:

go build -o ./bin/godoctor ./cmd/server && ./bin/godoctor -listen=:8080

4. Reinicie a CLI do Gemini e dê um comando para testar a conexão, por exemplo: "Use a ferramenta godoctor para acessar a documentação de fmt.Println."
5. Quando terminar de testar, pare o servidor com Ctrl+C.

9. Inserir o aplicativo em um contêiner com o Docker

Agora que o servidor usa o protocolo de transporte correto, é possível conteinerizá-lo para implantação.

Objetivo: criar um Dockerfile para empacotar o servidor godoctor em uma imagem de contêiner portátil e pronta para produção.

Exemplo de comando:

Please create a multi-stage Dockerfile that compiles the Go binary and copies it into a minimal golang image like golang:1.25.6-alpine. The image should support the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI
- GOOGLE_CLOUD_PROJECT
- GOOGLE_CLOUD_LOCATION

Acceptance Criteria:
- The image builds successfully
- Create a script test_docker.sh to launch the docker image in background and test the connectivity with the client:
    - Call list_tools on the client pointing to the server running on Docker
    - Call read_docs for fmt.Println
    - Stop the server
- The script should run without failures

Opcional: testar manualmente a imagem do Docker

Depois que o Dockerfile for criado, crie a imagem e execute-a para confirmar se ela funciona corretamente.

1. Criar o contêiner:

docker build -t godoctor:latest .

2. Execute o contêiner localmente:

docker run -p 8080:8080 -e PORT=8080 godoctor:latest

3. Teste o contêiner em execução: em outro terminal, inicie a CLI do Gemini e peça para ela buscar a documentação.
4. Quando terminar de testar, pare o servidor com Ctrl+C.

10. Como implantar no Cloud Run

Agora é hora de implantar o contêiner na nuvem.

Objetivo: implantar o servidor godoctor conteinerizado no Google Cloud Run.

Exemplo de comando:

Now please deploy this image to Cloud Run and return me an URL I can use to call the MCP tool. Configure Cloud Run to use the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI: true,
- GOOGLE_CLOUD_PROJECT: <your-project-id>
- GOOGLE_CLOUD_LOCATION: <your-preferred-region>

TODO:
- Run `docker build -t gcr.io/daniela-genai-sandbox/godoctor .`
- Run `gcloud run deploy godoctor --image` with the image created above

Acceptance Criteria:
- Call list-tools with the client pointing to the CloudRun endpoint

Atenção:se esta for a primeira vez que você usa o Cloud Run neste projeto, será necessário ativar as APIs Artifact Registry e Cloud Run.

Depois que a implantação for concluída, vamos configurar a CLI do Gemini para usar a ferramenta que você acabou de implantar.

Atualize o arquivo .gemini/settings.json para mudar a configuração da ferramenta MCP e direcioná-la ao serviço implantado ou peça para a CLI do Gemini fazer isso por você:

now update the .gemini/settings.json file to use this URL for the godoctor server

A seção final mcpServers deve ser semelhante a esta. Substitua o marcador de posição pelo URL do app do Cloud Run:

"mcpServers": {
  "godoctor": {
    "httpUrl": "https://<your-cloud-run-id>.us-central1.run.app"
  }
}

Como testar a implantação do Cloud Run

Está tudo pronto para o teste final.

Reinicie a CLI do Gemini pela última vez (usando /chat save e /chat resume se quiser manter o contexto). A CLI está pronta para chamar o servidor MCP remoto. Peça a documentação de qualquer pacote.

Você também pode testar a ferramenta de revisão de código:

Use the godoctor tool to review the cmd/godoctor/main.go file

Como fazer a limpeza

Atenção:exclua a implantação do Cloud Run antes de encerrar esta sessão, principalmente se você estiver usando uma instância não autenticada do Cloud Run para evitar cobranças inesperadas na sua conta de faturamento do GCP.

Depois de concluir os testes, limpe o ambiente. Você pode pedir ao Gemini para excluir o projeto ou apenas remover a implantação do CloudRun. Exemplo de comando:

I'm done with my tests on the CloudRun server, please delete this deployment for me and revert my .gemini/settings.json to use the local version.

11. Parabéns!

Você orientou um assistente de IA a criar, conteinerizar e implantar uma ferramenta sofisticada com tecnologia de IA. E, o mais importante, você praticou a habilidade essencial do desenvolvimento de software moderno, que é transformar requisitos em comandos eficazes. Você estendeu a CLI do Gemini com uma ferramenta MCP personalizada, tornando-a um assistente de desenvolvimento Go mais avançado e especializado.

Documentos de referência

• Blog de anúncio da CLI do Gemini
• Página inicial da CLI do Gemini
• Documentação da CLI do Gemini
• Especificação do Protocolo de Contexto de Modelo
• SDK Go para MCP
• SDK Go para IA generativa do Google