MCP Reference: geminicloudassist.googleapis.com

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 di AI a sistemi esterni come database e servizi web, traducendo le loro risposte in un formato che l'applicazione di 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.

Il server Gemini Cloud Assist MCP fornisce assistenza automatizzata per Google Cloud Platform, consentendo la risoluzione intelligente dei problemi, l'ottimizzazione dei costi, la progettazione e il provisioning dell'infrastruttura e le operazioni cloud. Prerequisiti:

  • API obbligatorie:
    • geminicloudassist.googleapis.com
    • designcenter.googleapis.com
    • apphub.googleapis.com
    • cloudasset.googleapis.com
    • appoptimize.googleapis.com
  • API consigliate (facoltative per un'esperienza completa):
    • logging.googleapis.com
    • monitoring.googleapis.com
    • apptopology.googleapis.com
    • recommender.googleapis.com
  • Ruoli richiesti:
    • roles/geminicloudassist.viewer (per attività di sola lettura)
    • roles/geminicloudassist.user (per l'utilizzo generale)
    • roles/geminicloudassist.admin (per le modifiche alle impostazioni di amministrazione)

Endpoint server

Un endpoint di servizio MCP è l'indirizzo di rete e l'interfaccia di comunicazione (di solito 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 Google MCP possono essere globali o regionali.

Il server MCP geminicloudassist.googleapis.com ha il seguente endpoint MCP:

  • https://geminicloudassist.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.

Il server MCP geminicloudassist.googleapis.com dispone dei seguenti strumenti:

Strumenti MCP
ask_cloud_assist

L'interfaccia principale per l'assistenza Google Cloud Platform. Utilizza questo strumento per interagire con l'agente root GCA per la risoluzione dei problemi generali, l'analisi dei log o le richieste generali sul cloud. Agisce come agente di orchestrazione centrale che indirizza le richieste degli utenti a sub-agenti esperti o le gestisce direttamente utilizzando strumenti per uso generico.

Funzionalità:

  • Domande generali: risposte a domande generali su servizi, concetti e documentazione di Google Cloud.
  • Query di stato:recupera lo stato e l'inventario delle risorse attuali (ad es. "Elenca le mie VM attive", "Mostrami la configurazione di questo pod").
  • Direttive:esegue direttive o controlli di stato specifici e di bassa complessità.
  • Triage e routing:gestisce intent complessi o ambigui (ad es. "Qualcosa non va con la mia app") per identificare l'ambito del problema prima di passare potenzialmente la richiesta ad agenti specializzati.
  • Esecuzione sicura:coordina le azioni mutative (ad es. "Riavvia questa VM", "Scala questo cluster") utilizzando un flusso di lavoro Human-in-the-Loop (HITL) sicuro. Verifica il consenso dell'utente prima di eseguire i comandi gcloud.

Linee guida per l'utilizzo:

  • Scelta predefinita:seleziona questo strumento quando l'intento dell'utente è ampio, ambiguo, esplorativo, puramente informativo o riguarda la pianificazione.
  • Triage:utilizza questo strumento per la segnalazione iniziale dei problemi quando il dominio specifico non è ancora chiaro.
  • Esecuzione diretta:utilizza questo strumento quando l'utente richiede una modifica specifica e prevista al proprio ambiente (ad es. "Riavvia l'istanza X", "Scala questo cluster", "Aggiorna la regola firewall").
  • Esclusioni:
    • Se l'utente chiede esplicitamente di progettare, creare l'architettura o eseguire il deployment dell'infrastruttura, utilizza design_infra.
    • Se l'utente chiede esplicitamente un'analisi approfondita della causa principale, il debug o la correzione di un errore noto, utilizza investigate_issue.
    • Se l'utente chiede esplicitamente informazioni su costi, fatturazione o risorse inattive, utilizza optimize_costs.

Gestione delle sessioni:

  • Questo strumento restituisce un contextId nell'output.
  • Per continuare una conversazione (multi-turn), DEVI includere contextId.
  • Ometti contextId per avviare una nuova attività indipendente.
investigate_issue

L'agente di orchestrazione delle indagini è l'agente principale per la risoluzione dei problemi e la diagnostica per Google Cloud. Funge da "SRE in a box" specializzato in grado di navigare tra infrastrutture complesse, codice dell'applicazione e dati di osservabilità per risolvere gli incidenti.

Funzionalità e architettura principali:

  • Ragionamento avanzato e indagini interattive:utilizza algoritmi di pianificazione sofisticati per eseguire la valutazione parallela delle ipotesi, consentendo di controllare più scenari di errore contemporaneamente anziché in sequenza.
  • Strategia di indagine rapida e approfondita:
    • Modalità Express:per insight rapidi, rilevamento di anomalie nei log/nelle metriche e controlli dello stato in tempo reale.
    • Modalità Ricerca avanzata: per l'analisi delle cause principali complessa. Sfrutta l'esperienza nel dominio integrandosi con agenti di database e analisi specializzati tramite l'agente Cloud Assist Planner.
  • Runbook di diagnostica:possono selezionare ed eseguire automaticamente playbook di diagnostica predefiniti per la risoluzione dei problemi standardizzata.
  • Topologia basata sulle tracce:genera mappe dell'architettura dinamiche derivate da tracce di traffico reali, non solo dalla configurazione statica.
  • Approfondimenti sul codice sorgente:analizza la logica dell'applicazione per trovare le cause principali all'interno del codice stesso (ad es. pool di connessioni, query).
  • Spiegazione basata sull'AI: fornisce spiegazioni in linguaggio semplice per i log degli errori oscuri e le anomalie delle metriche.

Quando eseguire il routing a questo agente:

  • Richieste degli utenti di analisi delle cause principali (RCA) o assistenza in caso di interruzione/arresto anomalo.
  • L'utente chiede di analizzare log, metriche o tracce per rilevare anomalie.
  • L'utente deve comprendere le dipendenze o ragionare sul grafico della topologia.
  • L'utente chiede informazioni sui problemi relativi al codice sorgente che causano errori dell'infrastruttura.
  • L'utente vuole eseguire diagnostiche o controlli di integrità specifici.

Competenze e capacità dettagliate:

  • Deep Research e analisi delle cause principali (RCA): avvia un'indagine completa in più passaggi utilizzando il ragionamento avanzato e la pianificazione. Esegue la valutazione parallela delle ipotesi, sfruttando agenti specifici del dominio (database, analisi) per trovare le cause principali definitive. Utilizzalo per problemi complessi e aperti.

    • Esempi: "La latenza della mia applicazione è aumentata fino a 5 secondi, trova la causa principale", "Indaga sul motivo per cui il servizio chatter genera errori 503 durante il test di carico". "Perché i pod su ClusterABC non sono pianificabili?" "Analizza i colli di bottiglia nel mio flusso di pagamento." "Esegui un'analisi approfondita della contesa di blocco del database."

  • Runbook e playbook diagnostici:esegue runbook diagnostici deterministici e procedure operative standard (SOP). Questa skill si integra con l'agente Cloud Assist Planner per eseguire controlli convalidati per problemi noti e modalità di errore comuni.

    • Esempi: "Esegui la diagnostica di connettività per il servizio frontend", "Execute the standard controllo di integrità runbook.", "Controlla la presenza di problemi di configurazione noti utilizzando il playbook di diagnostica". "Esiste un runbook per verificare la raggiungibilità della rete?"

  • Diagnostica rapida e rilevamento di anomalie:esegue "controlli rapidi" e rilevamento automatico di anomalie su log e metriche. Utilizzalo per identificare immediatamente valori anomali, picchi o pattern di errore senza attendere un'indagine completa.

    • Esempi: "Rileva eventuali anomalie delle metriche per il servizio di pagamento", "Mostrami il livello di traffico e la latenza per il servizio chatter-frontend". "Ci sono valori anomali nell'utilizzo della CPU?" "Quali sono gli errori più comuni per il servizio di elaborazione dello store in questo momento?" "Scansiona i log per individuare picchi di errori recenti."

  • Ragionamento su log ed errori basato sull'AI: utilizza l'AI per ragionare su e interpretare log degli errori complessi, stack trace e pattern delle metriche. Oltre a una semplice spiegazione, deduce il significato tecnico e il potenziale impatto dei dati di osservabilità.

    • Esempi: "Analizza questa analisi dello stack e spiega perché si verifica l'arresto anomalo", "Reason about this 'Connection Reset' error in the context of high load.", "Interpret this obscure database error code." (interpreta questo oscuro codice di errore del database) "Perché visualizzo ripetutamente questo log degli errori specifico?"

  • Grafico della topologia basato sulle tracce:genera un grafico della topologia dinamico derivato dalle tracce reali dell'applicazione (OneGraph). Visualizza e motiva i percorsi e le dipendenze del traffico effettivo, sovrapponendo i segnali di latenza ed errore ai nodi del grafico.

    • Esempi: "Mostrami la topologia basata sulle tracce per il servizio di pagamento". "Visualizza il flusso di traffico effettivo tra i microservizi". "Mappa le dipendenze in base alle tracce delle richieste recenti". "Genera un grafico che mostri dove viene introdotta la latenza nello stack."

  • Source Code Insights:analizza in dettaglio il codice sorgente dell'applicazione e i file di configurazione (tramite DevConnect). Collega i sintomi dell'infrastruttura a righe di codice specifiche, identificando problemi come query errate, timeout aggressivi o bug logici.

    • Esempi: "Analizza il codice sorgente per query di database inefficienti", "Un commit recente ha modificato le impostazioni del pool di connessioni?" "Controlla la logica dell'app per potenziali race condition". "Controlla la presenza di errori nei file di configurazione del repository."

  • Risoluzione e correzione della causa principale:sintetizza i risultati dell'indagine per identificare la causa principale definitiva e genera un piano di correzione attuabile corrispondente (ad es. comandi CLI, patch di codice) per risolvere il problema.

    • Esempi: "Trova la causa principale del timeout del database e genera un piano per risolverlo", "Identifica il motivo per cui l'istanza si arresta in modo anomalo e crea un comando gcloud per ridimensionarla.", "Determina la causa degli errori di connessione e suggerisci modifiche al codice". "Qual è la correzione consigliata per questo errore?"

  • Risoluzione interattiva dei problemi multi-turno:supporta l'interattività stateful e multi-turno. Consente all'utente di guidare l'indagine, porre domande aggiuntive, perfezionare l'ambito e ripetere i risultati in modo conversazionale.

    • Esempi: "Non ha funzionato, cosa dovremmo controllare dopo?", "Puoi esaminare i log del database?" "Concentriamoci ora sul servizio di frontend.", "Approfondisci la seconda ipotesi."

Gestione delle sessioni:

  • Questo strumento restituisce un contextId nell'output.
  • Per continuare una conversazione (multi-turn), DEVI includere contextId.
  • Ometti contextId per avviare una nuova attività indipendente.
optimize_costs

L'agente Optimize aiuta gli utenti ad analizzare, monitorare e ottimizzare i costi di Google Cloud. Fornisce suddivisioni dettagliate della spesa e identifica le opportunità di efficienza dei costi individuando le risorse inattive o sottoutilizzate.

Funzionalità principali:

  • Analisi dei costi:suddivide la spesa per progetto, applicazione, prodotto, risorsa o località per rispondere alla domanda "Quanto ho speso?".
  • Principali fattori di costo: identifica le risorse o i servizi più costosi che determinano la fattura.
  • Tendenze di costo:analizza come sono cambiati i costi nel tempo (ad es. aumenti di mese in mese).
  • Efficienza e dimensionamento corretto:identifica le risorse inattive, con provisioning eccessivo o sottoutilizzate in modo specifico per evidenziare le opportunità di risparmio sui costi.

Limitazioni importanti per il routing:

  • INOLTRA le domande relative alle risorse "sottoutilizzate" o "inattive" se il contesto è il risparmio di denaro (ad es. "Mostrami il costo delle mie risorse più sottoutilizzate").
  • NON indirizzare domande generali sull'utilizzo non correlate ai costi (ad es. "Quante vCPU ha utilizzato la risorsa X?").
  • Questo agente non prevede i costi futuri.
  • Questo agente non esegue alcuna azione per ridurre i costi (analisi di sola lettura).

Quando eseguire il routing a questo agente:

  • L'utente chiede: "Quanto ho speso per Compute Engine il mese scorso?"
  • L'utente chiede "Quali sono le mie risorse più costose?"
  • L'utente chiede: "Quali risorse sono inattive e mi costano?"
  • L'utente chiede: "Perché la mia fattura è aumentata rispetto al mese scorso?"

Gestione delle sessioni:

  • Questo strumento restituisce un contextId nell'output.
  • Per continuare una conversazione (multi-turn), DEVI includere contextId.
  • Ometti contextId per avviare una nuova attività indipendente.
invoke_operation

Richiama l'agente Operations per le attività di Suite operativa di Google Cloud.

L'agente Operations è in grado di gestire varie operazioni cloud, indagini e attività di gestione.

user_query è un oggetto JSON convertito in stringa che definisce l'operazione esatta. Il codice JSON DEVE contenere una chiave operation_type con uno dei due valori: GKE_APPLY, GKE_PATCH. In base a operation_type, fornisci esattamente uno degli oggetti corrispondenti:

  • Se GKE_APPLY: fornisci un oggetto gke_apply contenente:

    • target_cluster (stringa, obbligatorio): nome completo della risorsa, ad esempio projects/{p}/locations/{l}/clusters/{c}.
    • yaml_manifest (stringa, obbligatorio): la stringa YAML non elaborata. Assicurati che i caratteri di nuova riga siano codificati.
    • namespace (stringa, facoltativo): esegue l'override dello spazio dei nomi.
    • force_conflicts (booleano, facoltativo): se è true, forza la risoluzione dei conflitti durante l'applicazione. Ciò corrisponde a kubectl apply --server-side --force-conflicts. Utilizza questo campo per assicurarti che lo stato previsto venga applicato anche se un altro gestore di campi è attualmente proprietario dei campi di destinazione.

  • Se GKE_PATCH: fornisci un oggetto gke_patch contenente:

    • target_cluster (stringa, obbligatorio): nome completo della risorsa.
    • resource_type (stringa, obbligatorio): ad es. deployments.
    • resource_name (stringa, obbligatorio): il nome della risorsa k8s.
    • patch_json (stringa, obbligatorio): la stringa di patch JSON. È scappato correttamente.
    • namespace (stringa, facoltativo): lo spazio dei nomi della risorsa.

Esempi:

  • Esempio 1 (GKE_APPLY):

    {
  "operation_type": "GKE_APPLY",
  "gke_apply": {
    "target_cluster": "projects/my-company/locations/us-central1/clusters/my-cluster",
    "yaml_manifest": "apiVersion: v1 | kind: ConfigMap | metadata: name: my-config | data: key: value",
    "namespace": "default"
  }
}

  • Esempio 2 (GKE_PATCH):

    {
  "operation_type": "GKE_PATCH",
  "gke_patch": {
    "target_cluster": "projects/my-company/locations/us-central1/clusters/my-cluster",
    "resource_type": "deployments",
    "resource_name": "my-app",
    "patch_json": "{'spec': {'replicas': 5}}",
    "namespace": "default"
  }
}

  • Esempio 3 (GKE_APPLY con force_conflicts per ignorare i gestori dei campi esistenti):

    {
  "operation_type": "GKE_APPLY",
  "gke_apply": {
    "target_cluster": "projects/my-company/locations/us-central1/clusters/my-cluster",
    "yaml_manifest": "apiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web-backend\nspec:\n  replicas: 5\n  template:\n    spec:\n      containers:\n      - name: app\n        image: my-repo/web-backend:v2.0.1",
    "namespace": "default",
    "force_conflicts": true
  }
}

Args:

  • project: il progetto cloud Google con formato projects/{project_id}.
  • userQuery: un oggetto JSON convertito in stringa che definisce l'operazione esatta.
  • contextId: l'ID contesto della risposta precedente dell'agente.

Gestione delle sessioni:

  • Questo strumento restituisce un contextId nell'output.
  • Per continuare una conversazione (multi-turn), DEVI includere contextId nella richiesta successiva.
  • Ometti contextId per avviare una nuova attività indipendente.
design_infra

Design Agent aiuta gli utenti a gestire l'intero ciclo di vita dell'infrastruttura delle applicazioni su Google Cloud Platform. Fornisce un insieme di subagenti specializzati per gestire diversi aspetti della progettazione e della generazione dell'infrastruttura.

Comandi supportati e informazioni obbligatorie:

  • manage_app_design: progetta e realizza l'infrastruttura su Google Cloud Platform necessaria per gli intent di progettazione dell'infrastruttura applicativa.

    • Descrizione:
      • Questo comando può generare l'architettura Google Cloud, quindi eseguire il rendering del diagramma Mermaid e generare il codice Terraform.
      • Questo comando potrebbe accettare anche Infrastructure as Code (IaC) durante l'iterazione di una progettazione (ad es. importa il codice Terraform nel template di applicazione esistente).
      • Questo comando può essere utilizzato anche per recuperare il codice Terraform per un modello di applicazione o un design di app esistente.
    • Design Session:
      • Ogni sessione di progettazione è associata a un modello di applicazione di App Design Center (ADC) (identificato da applicationTemplateURI).
      • L'agente manterrà lo stato dei progetti di applicazione e dei relativi artefatti Terraform.
      • Per eseguire l'iterazione di un progetto, DEVI fornire l'ID modello di applicazione nel formato projects/{projectid}/locations/{region}/spaces/{spaceid}/applicationTemplates/{templateid}.
      • Per creare un nuovo design, non fornire l'ID del modello di applicazione.
    • Query utente:deve descrivere l'architettura, i requisiti e i vincoli dell'applicazione di alto livello. Puoi specificare variabili di ambiente, porta e così via. Oppure una richiesta specifica per l'importazione di IaC o il recupero del codice Terraform.
      • Esempio: "Progetta un'app web a tre livelli con un bilanciatore del carico, frontend, backend e un database".
      • Esempio: "Importa la progettazione dell'applicazione da IaC, ecco i miei file Terraform: - main.tf terraform\n<main.tf file content>\n, - variables.tf terraform\n<variables file content>\n ..."
      • Esempio: "Mostrami il codice Terraform per il modello di applicazione projects/.../applicationTemplates/test-app"
    • Linee guida importanti
      • Iterazione del design: se l'utente vuole modificare o aggiornare un design esistente, DEVE fornire application_template_id nella query.
        • Esempio: "Aggiorna progetto projects/{projectid}/locations/{region}/spaces/{spaceid}/applicationTemplates/{templateid}: aggiungi un'istanza Cloud SQL".
      • L'input project deve essere formattato come projects/{projectid}.
    • Obiettivo:genera un progetto completo utilizzando i concetti di App Design Center (ADC) o importa un progetto di applicazione da IaC.
    • Restituisce:una stringa in formato XML contenente uno o più dei seguenti elementi: Message, serializedDesign, applicationTemplateURI, terraformCode, mermaidCode e Instructions.

  • generate_terraform: genera configurazioni Terraform per una singola risorsa.

    • Query utente:richiesta specifica di codice Terraform.
      • Esempio: "Genera Terraform per un cluster GKE con un pool di nodi spot".
    • Suggerimento: se l'utente vuole generare Terraform per un modello di applicazione ADC, DEVE utilizzare manage_app_design.
      • Esempio: "Generate Terraform for application template tmpl_12345" (genera Terraform per il modello di applicazione tmpl_12345) deve essere indirizzato a manage_app_design.
    • Obiettivo:produce codice HCL Terraform valido e implementabile.

  • generate_gcloud: genera comandi gcloud.

    • Query utente:una richiesta di esecuzione di un'azione utilizzando Google Cloud CLI.
      • Esempio: "Dammi il comando gcloud per creare un argomento Pub/Sub."
    • Obiettivo:genera una sequenza di comandi gcloud eseguibili.

  • generate_bigquery: genera comandi BigQuery.

    • Query utente:una richiesta di comandi BigQuery.
      • Esempio: "Dammi il comando bq per creare un set di dati."
    • Obiettivo:genera una sequenza di comandi bq eseguibili.

  • generate_kubernetes_yaml: genera il file YAML di Kubernetes.

    • Query utente:una richiesta di manifest Kubernetes.
      • Esempio: "Crea un deployment Kubernetes per Nginx con 3 repliche".
    • Obiettivo:produce manifest YAML di Kubernetes validi.

  • debug_deployment: esegui il debug dell'errore di deployment nell'applicazione ADC.

    • Query utente:una richiesta di debug di un errore di deployment nell'applicazione ADC. Deve contenere una frase di aiuto come "Aiutami a eseguire il debug di questa applicazione" e solo l'URI dell'applicazione e nessun'altra informazione.
      • Esempio: "Aiutami a eseguire il debug di questa applicazione - projects/test-project/locations/us-central1/spaces/test-space/applicationTemplates/test-app"
    • Obiettivo:esegue la diagnosi dei problemi di implementazione e restituisce le istruzioni per risolverli.
    • Azioni di follow-up:
      • Se l'output contiene comandi gcloud, segui le istruzioni ed esegui il comando gcloud per risolvere il problema.
      • Se l'output descrive una modifica alla progettazione dell'infrastruttura, chiama lo strumento manage_app_design per applicare le modifiche consigliate all'infrastruttura.

Utilizzo:

Per utilizzare questo strumento, il chiamante deve specificare l'argomento command corrispondente al sub-agente desiderato e fornire l'user_query con l'intent specifico.

Ottenere le specifiche dello strumento MCP

Per ottenere le specifiche dello strumento MCP per tutti gli strumenti di 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.

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