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) atua como um proxy entre um serviço externo que fornece contexto, dados ou recursos a um modelo de linguagem grande (LLM) ou 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

É preciso ativar os servidores MCP e configurar a autenticação antes de usar. 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 de 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 do 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 Google MCP 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 as seguintes ferramentas:

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. Tenha muito cuidado. 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. Você PRECISA fornecer o parâmetro "project" (ou seja, project="projects/PROJECT_ID") ao usar essa ferramenta. Ele é usado para verificação de ativação da API Cloud CLI Execution, faturamento, cota etc. Não é o mesmo que a flag "--project" nos comandos gcloud usados para especificar o projeto em que a gcloud opera.
  2. Formatação de flags: você SEMPRE precisa usar um sinal de "=" para separar as chaves de flags dos valores em 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 presumir configurações de projeto ou faturamento pré-configuradas no ambiente de execução. Para comandos que não são do escopo do 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 no escopo do projeto, você PODE especificar --billing-project=PROJECT para substituir o projeto de cota, o que vai entrar em vigor para APIs do GCP que não oferecem suporte à substituição de projeto de recurso.
  4. Escopo do projeto: SEMPRE transmita 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 no escopo do projeto, o projeto de recurso será definido como padrão para 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 especial (por exemplo, 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), SEMPRE transmita a flag --async para evitar tempos limite do agente.
  8. Limitação da taxa de registros: ao usar gcloud logging read, SEMPRE inclua uma flag --limit (por exemplo, --limit=100) para evitar tempos limite de credenciais e de conexão.
  9. Autocorreção: se um comando retornar um erro, analise o stderr, corrija a sintaxe ou as flags e tente de novo 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 "path" (relativo ao diretório atual) e "contents". O "conteúdo" precisa ser texto sem formatação representando 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 da gcloud:

  1. Leia os 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 na expressão de filtro.
  2. Liste todos os endpoints do PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Descreva 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

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

Executa um único comando da CLI do BigQuery (bq). Com essa ferramenta, é possível executar qualquer comando bq no projeto do usuário, incluindo aqueles que criam, atualizam ou excluem recursos do GCP (ou seja, mutações). AVISO DE SEGURANÇA CRÍTICO (POTENCIALMENTE DESTRUTIVO): essa ferramenta pode criar, atualizar ou excluir recursos do BigQuery (por exemplo, bq rm, bq cancel, bq query). Ela NÃO é restrita a comandos somente leitura. Tenha muito cuidado. COMANDOS PROIBIDOS: um agente NÃO PODE executar os seguintes comandos bq: bq init, bq load, bq pyshell, bq shell. REGRAS DE EXECUÇÃO ESTRICTAS:

  1. Pelo menos um dos parâmetros --project_id ou --quota_project_id PRECISA ser especificado na string de comando.
  2. ID do projeto x projeto de cota: a flag "--project_id" especifica o projeto de recurso em que o comando opera (reflete a flag "--project" do gcloud). A flag --quota_project_id especifica o projeto cobrado pelo faturamento/cota da chamada de API BigQuery downstream (reflete a flag --billing-project da gcloud). Se --project_id for especificado no comando, ele será usado como o projeto de faturamento/cota. Se --project_id não for especificado OU --quota_project_id também for especificado, o projeto de faturamento/cota será o definido na flag --quota_project_id.
  3. Formatação de flags: você SEMPRE precisa usar um sinal de "=" para separar as chaves de flags dos valores em todas as opções longas. Correto: "--project_id=my-project" ou "--location=us". Incorreto: "--project_id my-project" ou "--location us". Não use espaços entre flags e valores.
  4. Sem padrões de configuração: o comando bq é executado sem estado. Ele não carrega arquivos de configuração locais, como .bigqueryrc. Portanto, para todas as operações regionais (por exemplo, criar um conjunto de dados ou consultar um conjunto de dados regional), é necessário especificar explicitamente a flag --location (por exemplo, --location=us ou --location=EU).
  5. Operações assíncronas: alguns comandos iniciam operações síncronas de longa duração (por exemplo, execução de jobs de consulta). SEMPRE transmita a flag --nosync para esses comandos para evitar tempos limite do agente.
  6. Restrições de comando: NÃO use os seguintes comandos bq: bq init, bq pyshell, bq shell. Não é possível encadear ou redirecionar comandos.
  7. Autocorreção: se um comando retornar um erro, analise o stderr, corrija a sintaxe ou as flags e tente de novo na próxima iteração.

Exemplos de comandos bq mutantes incluem: bq mk, bq rm, bq update, bq insert, bq query (sem --dry_run) etc. Uso: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) Você PRECISA fornecer o comando bq completo como uma única string no parâmetro "command". Você PRECISA fornecer o parâmetro "project" (formato: projects/PROJECT_ID) como o projeto de execução da API para faturamento, ativação da API e verificações de consumo de cota.

Exemplos de comandos/padrões bq:

  1. Execute uma consulta: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROM project.dataset.table LIMIT 10'
  2. Crie um conjunto de dados: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Crie uma tabela: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Remover um conjunto de dados: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Remover uma tabela: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Atualizar a descrição da tabela: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Listar conjuntos de dados em um projeto: bq ls --datasets=true --project_id=PROJECT_ID

Receber especificações da ferramenta MCP

Para receber as especificações 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 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
}'