MCP Reference: cloudcli.googleapis.com

Il server MCP di Cloud CLI fornisce strumenti per eseguire i comandi di Cloud CLI in un ambiente sandbox remoto.

Un server Model Context Protocol (MCP) funge da proxy tra un servizio esterno che fornisce contesto, dati o funzionalità a un modello linguistico di grandi dimensioni (LLM) o a un'applicazione AI. I server MCP collegano le applicazioni AI a sistemi esterni come database e servizi web, traducendo le loro risposte in un formato che l'applicazione AI può comprendere.

Configurazione del server

Prima dell'uso, devi abilitare i server MCP e configurare l'autenticazione. Per saperne di più sull'utilizzo dei server MCP remoti di Google e Google Cloud, consulta la panoramica dei server MCP di Google Cloud.

Endpoint server

Un endpoint del servizio MCP è l'indirizzo di rete e l'interfaccia di comunicazione (in genere un URL) del server MCP che un'applicazione AI (l'host per il client MCP) utilizza per stabilire una connessione sicura e standardizzata. È il punto di contatto per l'LLM per richiedere il contesto, chiamare uno strumento o accedere a una risorsa. Gli endpoint MCP di Google possono essere globali o regionali.

Il server MCP dell'API Cloud CLI Execution ha il seguente endpoint MCP globale:

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

Strumenti MCP

Uno strumento MCP è una funzione o una funzionalità eseguibile che un server MCP espone a un LLM o a un'applicazione AI per eseguire un'azione nel mondo reale.

Strumenti

Il server MCP cloudcli.googleapis.com ha il seguente strumento:

Strumenti MCP
run_gcloud_command

Esegue un singolo comando gcloud CLI all'interno del progetto Google Cloud dell'utente. AVVISO DI SICUREZZA CRITICO (POTENZIALMENTE DISTRUTTIVO): questo strumento può creare, aggiornare o eliminare risorse Google Cloud (ad es. gcloud compute instances delete). NON è limitato ai comandi di sola lettura. Utilizzalo con estrema cautela. COMANDI VIETATI: un agente NON DEVE eseguire i seguenti comandi gcloud (incluse le varianti alpha/beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey. REGOLE DI ESECUZIONE RIGIDE:

  1. Quando utilizzi questo strumento, DEVI fornire il parametro "project" (ovvero project="projects/PROJECT_ID") (viene utilizzato per il controllo dell'abilitazione dell'API Cloud CLI Execution, la fatturazione, la quota e così via). NON è lo stesso del flag --project nei comandi gcloud utilizzati per specificare il progetto su cui opera gcloud.
  2. Formattazione dei flag: DEVI sempre utilizzare il segno "=" per separare le chiavi dei flag dai relativi valori per tutte le opzioni lunghe. Corretto: --zone=us-central1-a o --project=my-project. Non corretto: --zone us-central1-a o --project my-project.
  3. Progetto di fatturazione: non puoi presupporre alcuna impostazione di progetto o di fatturazione preconfigurata nell'ambiente di esecuzione. Per i comandi non limitati al progetto (ad es. a livello di cartella o organizzazione) o per scenari specifici come Cloud Storage Requester Pays, DEVI passare il flag --billing-project=PROJECT. Per i comandi limitati al progetto, PUOI anche specificare --billing-project=PROJECT per sostituire il progetto di quota, che avrà effetto per le API Google Cloud che non supportano l'override del progetto di risorse.
  4. Ambito del progetto: DEVI SEMPRE passare il flag --project=PROJECT_ID per i comandi limitati al progetto. Non utilizzarlo per i comandi a livello di organizzazione o cartella. Se non fornisci un flag --project per un comando limitato al progetto, il progetto di risorse utilizzerà per impostazione predefinita il progetto impostato nel flag --billing-project.
  5. Se specifichi il flag --billing-project nel comando gcloud, assicurati che il valore sia un ID progetto o un numero di progetto. Il valore NON DEVE essere un valore speciale (ad es. LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. Nella stringa di comando DEVE essere specificato almeno uno tra --project o --billing-project.
  7. Operazioni asincrone: per le operazioni sincrone a lunga esecuzione (ad es. la creazione di una VM o di un database), DEVI SEMPRE passare il flag --async per evitare timeout dell'agente.
  8. Limitazione della frequenza dei log: quando utilizzi gcloud logging read, DEVI SEMPRE includere un flag --limit (ad es. --limit=100) per evitare timeout delle credenziali e della connessione.
  9. Autocorrezione: se un comando restituisce un errore, analizza stderr, correggi la sintassi o i flag e riprova nell'iterazione successiva.
  10. input_files: (facoltativo) un elenco di file da creare nell'ambiente prima di eseguire il comando. Ogni file deve avere un "path" (relativo alla directory corrente) e "contents". Il campo "contents" deve essere in formato di testo normale che rappresenta il contenuto del file. Questo è utile per i comandi che leggono dai file (ad es. gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Esempi di comandi/pattern gcloud:

  1. Leggi i log delle istanze GCE con gravità>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Tieni presente l'utilizzo delle virgolette per l'espressione di filtro.
  2. Elenca tutti gli endpoint PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Descrivi un endpoint PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Tieni presente l'utilizzo di "=" per il flag --region.
  4. Elenca tutti i cluster: gcloud container clusters list --project=PROJECT_ID
  5. Descrivi un cluster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Elenca le istanze Compute: gcloud compute instances list --project=PROJECT_ID
  7. Recupera il policy IAM per un progetto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

Per impostazione predefinita, le stringhe di risposta sono formattate per l'output del terminale (stdout o stderr). Utilizza il flag --format per modificare il formato.

Recupera le specifiche degli strumenti MCP

Per recuperare le specifiche degli strumenti MCP per tutti gli strumenti in un server MCP, utilizza il metodo tools/list. L'esempio seguente mostra come utilizzare curl per elencare tutti gli strumenti e le relative specifiche attualmente disponibili nel server MCP.

Richiesta 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
}'