MCP Reference: cloudcli.googleapis.com

O servidor MCP da CLI do Cloud oferece ferramentas para executar comandos da CLI do Cloud em um ambiente de sandbox remoto.

Um servidor do Protocolo de Contexto de Modelo (MCP, na sigla em inglês) atua como um proxy entre um serviço externo que fornece contexto, dados ou recursos para um modelo de linguagem grande (LLM) ou um aplicativo de IA. Os servidores MCP conectam aplicativos de IA a sistemas externos, como bancos de dados e serviços da Web, traduzindo as respostas em um formato que o aplicativo de IA possa entender.

Configuração do servidor

É necessário ativar os servidores MCP e configurar a autenticação antes do uso. Para mais informações sobre como usar servidores MCP remotos do Google e do Google Cloud, consulte Visão geral dos servidores MCP do Google Cloud.

Endpoints do servidor

Um endpoint de serviço do MCP é o endereço de rede e a interface de comunicação (geralmente um URL) do servidor MCP que um aplicativo de IA (o host do cliente MCP) usa para estabelecer uma conexão segura e padronizada. É o ponto de contato para o LLM solicitar contexto, chamar uma ferramenta ou acessar um recurso. Os endpoints do MCP do Google podem ser globais ou regionais.

O servidor MCP da API Cloud CLI Execution tem o seguinte endpoint global do MCP:

  • https://cloudcli.googleapis.com/mcp

Ferramentas do MCP

Uma ferramenta do MCP é uma função ou capacidade executável que um servidor MCP expõe a um LLM ou aplicativo de IA para realizar uma ação no mundo real.

Ferramentas

O servidor MCP cloudcli.googleapis.com tem a seguinte ferramenta:

Ferramentas do MCP
run_gcloud_command

Executa um único comando da CLI gcloud no projeto na nuvem do Google Cloud do usuário. AVISO DE SEGURANÇA CRÍTICO (POTENCIALMENTE DESTRUTIVO): essa ferramenta pode criar, atualizar ou excluir recursos do GCP (por exemplo, gcloud compute instances delete). Ela NÃO é restrita a comandos somente leitura. Use com extrema cautela. COMANDOS PROIBIDOS: um agente NÃO PODE executar os seguintes comandos gcloud (incluindo as variantes alfa/beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey. REGRAS DE EXECUÇÃO ESTRICTAS:

  1. É necessário fornecer o parâmetro "project" (ou seja, project="projects/PROJECT_ID") ao usar essa ferramenta. Ele é usado para a verificação de ativação da API Cloud CLI Execution, faturamento, cota etc. Isso NÃO é o mesmo que a flag --project em comandos gcloud usados para especificar o projeto em que a gcloud opera.
  2. Formatação de flags: é necessário sempre usar um sinal "=" para separar as chaves de flag dos valores de todas as opções longas. Correto: --zone=us-central1-a ou --project=my-project. Incorreto: --zone us-central1-a ou --project my-project.
  3. Projeto de faturamento: não é possível assumir nenhuma configuração de projeto ou faturamento pré-configurada no ambiente de execução. Para comandos não relacionados ao projeto (por exemplo, no nível da pasta ou da organização) ou cenários específicos, como o Requester Pays do Cloud Storage, é necessário transmitir a flag --billing-project=PROJECT. Para comandos com escopo de projeto, também é possível especificar --billing-project=PROJECT para substituir o projeto de cota, que entrará em vigor para APIs do GCP que não oferecem suporte à substituição de projeto de recurso.
  4. Escopo do projeto: é necessário SEMPRE transmitir a flag --project=PROJECT_ID para comandos com escopo de projeto. Não use para comandos no nível da organização ou da pasta. Se você não fornecer uma flag --project para um comando com escopo de projeto, o projeto de recurso será definido como o projeto definido na flag --billing-project.
  5. Se você especificar a flag --billing-project no comando gcloud, verifique se o valor é um ID do projeto ou um número do projeto. O valor NÃO pode ser um valor especial (ou seja, LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. Pelo menos um de --project ou --billing-project precisa ser especificado na string de comando.
  7. Operações assíncronas: para operações síncronas de longa duração (por exemplo, criar uma VM ou um banco de dados), é necessário SEMPRE transmitir a flag --async para evitar tempos limite do agente.
  8. Limitação da taxa de registros: ao usar gcloud logging read, é necessário SEMPRE incluir uma flag --limit (por exemplo, --limit=100) para evitar tempos limite de credenciais e conexões.
  9. Autocorreção: se um comando retornar um erro, analise o stderr, corrija a sintaxe ou as flags e tente novamente na próxima iteração.
  10. input_files: (opcional) uma lista de arquivos a serem criados no ambiente antes de executar o comando. Cada arquivo precisa ter um "caminho" (relativo ao diretório atual) e "conteúdo". O "conteúdo" precisa ser texto sem formatação que representa o conteúdo do arquivo. Isso é útil para comandos que leem arquivos (por exemplo, gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Exemplos de comandos/padrões gcloud:

  1. Ler registros de instâncias do GCE com gravidade>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Observe o uso de aspas para a expressão de filtro.
  2. Listar todos os endpoints do PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Descrever um endpoint do PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Observe o uso de "=" para a flag --region.
  4. Listar todos os clusters: gcloud container clusters list --project=PROJECT_ID
  5. Descrever um cluster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Listar instâncias de computação: gcloud compute instances list --project=PROJECT_ID
  7. Receber a política do IAM de um projeto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

As strings de resposta são formatadas para saída de terminal por padrão (stdout ou stderr). Use a flag --format para mudar o formato.

Receber especificações de ferramentas do MCP

Para receber as especificações de ferramentas do MCP de todas as ferramentas em um servidor MCP, use o método tools/list. O exemplo a seguir demonstra como usar curl para listar todas as ferramentas e especificações disponíveis no momento no servidor MCP.

Solicitação curl 
                      
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'