Utilizza il server MCP remoto di Cloud CLI

Questo documento mostra come utilizzare il server Model Context Protocol (MCP) remoto di Cloud CLI per connettersi ad applicazioni AI, tra cui Gemini CLI, ChatGPT, Claude e applicazioni personalizzate che stai sviluppando.

Il server MCP remoto di Cloud CLI fornisce un ambiente sicuro che ti consente di inviare prompt in linguaggio naturale alla tua applicazione AI per eseguire comandi dell'interfaccia a riga di comando (CLI) per tuo conto. Sono supportati i comandi gcloud e bq.

L'API per questa funzionalità si chiama Cloud CLI Execution.

Il server MCP remoto di Cloud CLI viene abilitato quando abiliti l'API Cloud CLI Execution.

Il Model Context Protocol (MCP) standardizza il modo in cui i modelli linguistici di grandi dimensioni (LLM) e le applicazioni o agenti AI si connettono a origini dati esterne. I server MCP ti consentono di utilizzare i loro strumenti, risorse e prompt per eseguire azioni e ottenere dati aggiornati dal loro servizio di backend.

Qual è la differenza tra i server MCP locali e remoti?

Server MCP locali
In genere vengono eseguiti sulla macchina locale e utilizzano i flussi di input e output standard (stdio) per la comunicazione tra i servizi sullo stesso dispositivo.
Server MCP remoti
Viene eseguito sull'infrastruttura del servizio e offre un endpoint HTTP alle applicazioni AI per la comunicazione tra il client AI MCP e il server MCP. Per maggiori informazioni sull'architettura MCP, consulta la sezione Architettura MCP.

Google e server MCP Google Cloud remoti

Google e Google Cloud i server MCP remoti hanno le seguenti funzionalità e vantaggi:

  • Individuazione semplificata e centralizzata
  • Endpoint HTTP globali o regionali gestiti
  • Autorizzazione granulare
  • Sicurezza facoltativa di prompt e risposte con la protezione Model Armor
  • Audit log centralizzato

Per informazioni su altri server MCP e sui controlli di sicurezza e governance disponibili per i server MCP di Google Cloud, consulta la panoramica dei server MCP di Google Cloud.

Restrizioni e linee guida

Prima di iniziare a utilizzare il server MCP remoto di Cloud CLI, esamina le seguenti limitazioni e linee guida:

Comandi supportati

Il server Cloud CLI MCP non supporta determinati comandi gcloud e bq (incluse le varianti alpha o beta per gcloud) a causa degli standard di sicurezza e dell'inapplicabilità.

Il seguente elenco mostra alcuni esempi di comandi gcloud non supportati. Questo elenco non è esaustivo ed è soggetto all'aggiunta o alla rimozione di comandi senza preavviso:

  • gcloud auth
  • gcloud config
  • gcloud iam service-accounts
  • gcloud init
  • gcloud survey

Di seguito è riportato un elenco completo dei comandi di bq non supportati:

  • bq init
  • bq pyshell
  • bq shell

Applicazione dei criteri dell'organizzazione

I comandi eseguiti tramite il server MCP remoto vengono eseguiti con le autorizzazioni dell'identità del chiamante autenticata. Le autorizzazioni IAM standard e i vincoli del servizio criteri dell'organizzazione vengono applicati rigorosamente alle risorse di destinazione downstream.

Linee guida per gli sviluppatori di agenti

  • Entità e autorizzazioni IAM: l'entità che interagisce con l'API Cloud CLI Execution è la stessa che interagisce con le API Google Cloud durante l'esecuzione dei comandi gcloud o bq. Poiché il server MCP di Cloud CLI può chiamare molte Google Cloud API, ti consigliamo di seguire il principio del privilegio minimo e assegnare all'utente, all'identità dell'agente o al account di servizio che chiama il server MCP di Cloud CLI le autorizzazioni minime richieste per il tuo caso d'uso.

  • Selezione dei progetti: project è un parametro obbligatorio per le richieste del server MCP Cloud CLI e rappresenta il progetto utilizzato per interagire con l'API Cloud CLI Execution. Tieni presente che il parametro project non è correlato ai flag --project o --billing-project impostati nel comando gcloud effettivo o ai flag --project_id e --quota_project_id per i comandi bq eseguiti dall'API Cloud CLI Execution.

    Ti consigliamo di aggiornare i prompt o le competenze di sistema per l'agente in modo che selezioni il progetto corretto per l'esecuzione delle richieste del server Cloud CLI MCP.

Prima di iniziare

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Cloud CLI Execution API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Cloud CLI Execution API.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    10.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare il server MCP di Cloud CLI, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto in cui vuoi utilizzare il server MCP di Cloud CLI:

  • Effettua chiamate allo strumento MCP: MCP Tool User (roles/mcp.toolUser)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per utilizzare il server MCP Cloud CLI. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per utilizzare il server Cloud CLI MCP sono necessarie le seguenti autorizzazioni:

  • Effettua chiamate allo strumento MCP: mcp.tools.call

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Autenticazione e autorizzazione

Il server MCP remoto Cloud CLI utilizza il protocollo OAuth 2.0 con Identity and Access Management (IAM) per l'autenticazione e l'autorizzazione. Tutte le Google Cloud identità sono supportate per l'autenticazione ai server MCP.

Il server MCP remoto di Cloud CLI non accetta chiavi API.

Ti consigliamo di creare un'identità separata per gli agenti che utilizzano gli strumenti MCP in modo che l'accesso alle risorse possa essere controllato e monitorato. Per saperne di più sull'autenticazione, consulta Autenticarsi sui server MCP.

Ambiti OAuth di Cloud CLI

OAuth 2.0 utilizza ambiti e credenziali per determinare se un principal autenticato è autorizzato a eseguire un'azione specifica su una risorsa. Per saperne di più sugli ambiti OAuth 2.0 in Google, vedi Utilizzare OAuth 2.0 per accedere alle API di Google.

Il server MCP remoto Cloud CLI ha i seguenti ambiti OAuth:

URI ambito Descrizione
https://www.googleapis.com/auth/cloud-platform Visualizzare e gestire i tuoi dati nei servizi Google Cloud .

Configura un client MCP per utilizzare il server MCP remoto Cloud CLI

Le applicazioni e gli agenti AI, come Claude o Antigravity, possono creare un'istanza di un client MCP che si connette a un singolo server MCP. Un'applicazione AI può avere più client che si connettono a server MCP diversi. Se la tua applicazione non è elencata nelle indicazioni specifiche per il client, puoi utilizzare le seguenti informazioni per connetterti dalla maggior parte delle applicazioni.

Nella tua applicazione AI, cerca un modo per aggiungere o connetterti a un server MCP remoto. Per il server MCP remoto di Cloud CLI, inserisci le seguenti informazioni in base alle necessità:

  • Nome server: server MCP remoto di Cloud CLI
  • URL del server o endpoint: https://cloudcli.googleapis.com/mcp
  • Trasporto: HTTP
  • Dettagli di autenticazione: le tue Google Cloud credenziali, il tuo ID client e il tuo client secret OAuth oppure l'identità e le credenziali di un agente

URI di reindirizzamento

Per le applicazioni basate sul web e alcune applicazioni desktop, devi inserire nell'allowlist un URI di reindirizzamento quando crei un ID client e un client secret per l'autenticazione. Gli URI di reindirizzamento vengono utilizzati dal server di autorizzazione per inviare token alla tua applicazione. La documentazione dell'applicazione deve specificare l'URI di reindirizzamento da utilizzare. Gli URI di reindirizzamento personalizzati non sono supportati.

Per indicazioni specifiche dell'applicazione sulla configurazione e la connessione al server MCP, vedi Indicazioni specifiche per il client.

Per indicazioni più generali, consulta le seguenti risorse:

Strumenti disponibili

Il server MCP remoto di Cloud CLI espone i seguenti strumenti:

  • run_gcloud_command
  • run_bq_command

Per visualizzare i dettagli degli strumenti MCP disponibili e le relative descrizioni per il server MCP di Cloud CLI, consulta il riferimento a Google Cloud SDK MCP.

Differenze tra run_bq_command e il server MCP BigQuery

run_bq_command espone la superficie della CLI BigQuery (bq) all'interno del server MCP remoto di Cloud CLI. Lo strumento può eseguire comandi SQL di BigQuery e consentire l'esecuzione di attività amministrative e operative tramite prompt in linguaggio naturale. BigQuery fornisce anche un server MCP separato per l'analisi dei dati standard. Ogni superficie dello strumento è progettata per casi d'uso distinti:

  • run_bq_command: utilizza run_bq_command quando crei agenti AI per workflow amministrativi e operativi avanzati, ad esempio la gestione delle prenotazioni di slot, le query di pianificazione, la gestione degli snapshot delle tabelle o la risoluzione dei problemi e l'annullamento dei job.
  • Server MCP BigQuery: utilizza il server MCP BigQuery quando crei agenti AI che utilizzano strumenti di esecuzione SQL standard per guidare l'analisi dei dati, l'individuazione dei metadati e la modifica dei dati.

La seguente tabella mostra ulteriori differenze tra le due interfacce degli strumenti:

Funzionalità BigQuery MCP Server run_bq_command
Disponibilità In disponibilità generale Anteprima
Utilizzo Analisi e modifica dei dati Amministrazione avanzata di lavori e risorse
Utenti target Analisti aziendali, data scientist, sviluppatori SQL Amministratori BigQuery, DBA, ingegneri della piattaforma di dati e DevOps
Operazioni principali Esecuzione di SQL standard (SELECT, INSERT, UPDATE, DELETE), esplorazione dello schema, ispezione dei metadati Pianificazione delle query (utilizzando DTS), annullamento dei job non controllati, gestione di slot e prenotazioni, criteri IAM per i set di dati, operazioni di snapshot/clonazione delle tabelle

Strumenti per le liste

Utilizza MCP Inspector per elencare gli strumenti o invia una richiesta HTTP tools/list direttamente al server MCP remoto di Cloud CLI. Il metodo tools/list non richiede l'autenticazione.

POST /mcp HTTP/1.1
Host: cloudcli.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

Esempi di casi d'uso per run_gcloud_command

Di seguito sono riportati alcuni casi d'uso di esempio per run_gcloud_command nel server MCP remoto di Cloud CLI:

Provisioning delle risorse

Quando un utente invia un prompt in linguaggio naturale all'agente, quest'ultimo genera un comando utilizzando lo strumento MCP corrispondente (run_gcloud_command per i comandi gcloud o run_bq_command per i comandi bq). Cloud CLI esegue il comando.

Prompt di esempio:

"Crea una nuova rete VPC denominata my-network nel progetto projects/my-project. Poi, crea una regola firewall che consenta il traffico TCP interno sulla porta 8080."

Workflow:

  1. L'agente chiama lo strumento run_gcloud_command con il comando "gcloud compute networks create my-network --project=projects/my-project --subnet-mode=auto", "project": "projects/my-project".

  2. L'agente chiama lo strumento run_gcloud_command con il comando "gcloud compute firewall-rules create allow-internal-8080 --project=projects/my-project --network=my-network --allow=tcp:8080 --source-ranges=10.0.0.0/8.

Osservabilità e diagnostica

Un agente può esaminare lo stato dell'ambiente ed eseguire query sui log errori recenti per aiutarti a risolvere i problemi.

Prompt di esempio: "Trova gli ultimi 5 log degli errori per l'istanza Compute Engine my-web-server nel progetto projects/my-project."

Workflow:

L'agente chiama lo strumento run_gcloud_command con il comando "gcloud logging read \"resource.type=gce_instance AND severity>=ERROR\" --limit=5 --order=DESC", project: "my-project".

Esempi di casi d'uso per run_bq_command

Di seguito sono riportati alcuni casi d'uso di esempio per run_bq_command nel server MCP remoto di Cloud CLI:

Gestire i set di dati in BigQuery

Puoi anche utilizzare il server MCP per eseguire query e gestire i set di dati in BigQuery.

Prompt di esempio: "Elenca tutti i set di dati nel progetto projects/my-project, quindi crea un nuovo set di dati denominato my_new_dataset nella località Stati Uniti".

Workflow:

  1. L'agente chiama lo strumento run_bq_command con il comando "bq ls --datasets=true --project_id=my-project", "project": "projects/my-project".

  2. L'agente chiama lo strumento run_bq_command con il comando "bq mk --dataset --location=us --project_id=my-project my_new_dataset", "project": "projects/my-project".

Risolvere i problemi e annullare i job a lunga esecuzione

Un agente ispeziona i job BigQuery in esecuzione per identificare i colli di bottiglia delle risorse, diagnosticare le query non riuscite, annullare i job a esecuzione prolungata ed estrarre i dettagli di esecuzione per i consigli sulle prestazioni.

Prompt di esempio:

"Controlla se nel progetto my-data-project sono attualmente in esecuzione query a esecuzione prolungata o che richiedono molte risorse. Se bqujob_12345 è in esecuzione da più di 30 minuti, annullala e mostra i dettagli."

Workflow:

  1. L'agente chiama run_bq_command con il comando "bq ls -j --all --project_id=my-data-project", "project": "projects/my-data-project".

  2. L'agente esamina l'elenco dei job e chiama run_bq_command con il comando: "bq show -j bqujob_12345 --project_id=my-data-project", "project": "projects/my-data-project".

  3. L'agente chiama run_bq_command con il comando: "bq cancel bqujob_12345 --project_id=my-data-project", "project": "projects/my-data-project".

Pianificare le query

Un agente configura le esecuzioni di query pianificate tramite l'integrazione di BigQuery Data Transfer Service nella CLI BigQuery per automatizzare gli aggiornamenti dei dati.

Prompt di esempio:

"Pianifica una query giornaliera alle 06:00 UTC per aggiornare la tabella daily_sales_summary in dataset sales_ds per il progetto my-data-project."

Workflow:

  1. L'agente chiama run_bq_command con il comando: "bq query --project_id=my-data-project --use_legacy_sql=false --destination_table=sales_ds.daily_sales_summary --display_name='Daily Sales Refresh' --schedule='every 24 hours' 'SELECT date, SUM(amount) as total FROM sales_ds.transactions GROUP BY date'", "project": "projects/my-data-project".

Analisi della capacità e aggiustamento delle prenotazioni

Un agente analizza le prenotazioni di slot esistenti nei progetti con il maggior consumo e aggiorna le assegnazioni di slot per gestire la capacità di calcolo.

Prompt di esempio:

"Elenca tutte le prenotazioni BigQuery nella regione us-central1 per il progetto my-admin-project e aggiorna l'allocazione degli slot per la prenotazione prod-analytics a 500 slot."

Workflow:

  1. L'agente chiama run_bq_command con il comando: "bq ls --reservation --project_id=my-admin-project --location=us-central1", "project": "projects/my-admin-project".

  2. L'agente chiama run_bq_command con il comando: "bq update --project_id=my-admin-project --reservation --slots=500 prod-analytics --location=us-central1", "project": "projects/my-admin-project".

Gestire snapshot e cloni delle tabelle

Un agente crea snapshot point-in-time delle tabelle di produzione critiche o esegue il provisioning dei cloni delle tabelle per lo sviluppo e il test.

Prompt di esempio:

"Crea uno snapshot della tabella production_db.orders denominato production_db.orders_snapshot_20260720 nel progetto my-data-project."

Workflow:

L'agente chiama run_bq_command con il comando: "bq cp --project_id=my-data-project --snapshot production_db.orders production_db.orders_snapshot_20260720", "project": "projects/my-data-project".

Controllo dell'accesso ai set di dati e delle autorizzazioni IAM

Un agente esamina i controlli dell'accesso al set di dati e aggiorna le autorizzazioni del set di dati per concedere o revocare l'accesso per le entità specificate.

Prompt di esempio:

"Mostra la configurazione di accesso attuale per il set di dati finance_ds nel progetto my-data-project."

Workflow:

  1. L'agente chiama run_bq_command con il comando: "bq show --format=prettyjson my-data-project:finance_ds", "project": "projects/my-data-project".

  2. L'agente aggiorna la definizione JSON di accesso e chiama run_bq_command con il comando: "bq update --source=access_update.json my-data-project:finance_ds", "project": "projects/my-data-project".

Configurazioni di sicurezza facoltative

MCP introduce nuovi rischi e considerazioni sulla sicurezza a causa dell'ampia varietà di azioni che puoi eseguire con gli strumenti MCP. Per ridurre al minimo e gestire questi rischi, Google Cloud offre impostazioni predefinite e policy personalizzabili per controllare l'utilizzo degli strumenti MCP nella tua organizzazione o nel tuo progetto Google Cloud.

Per saperne di più sulla sicurezza e sulla governance di MCP, consulta Sicurezza e protezione dell'AI.

Utilizzare Model Armor

Model Armor è un servizioGoogle Cloud progettato per migliorare la sicurezza delle tue applicazioni di AI. Funziona analizzando in modo proattivo i prompt e le risposte degli LLM, proteggendo da vari rischi e supportando pratiche di AI responsabile. Che tu stia implementando l'AI nel tuo ambiente cloud o in provider cloud esterni, Model Armor può aiutarti a prevenire input dannosi, verificare la sicurezza dei contenuti, proteggere i dati sensibili, mantenere la conformità e applicare in modo coerente le tue norme di sicurezza dell'AI nel tuo panorama AI diversificato.

Quando Model Armor è abilitato con il logging abilitato, Model Armor registra l'intero payload. Ciò potrebbe esporre informazioni sensibili nei log.

Routing delle richieste MCP a Model Armor

Model Armor è disponibile in alcune regioni. Quando Model Armor è abilitato e utilizzi un server MCP in una giurisdizione che Model Armor non supporta, il comportamento di routing della chiamata potrebbe essere diverso per i diversi server MCP e potrebbe violare la conformità alla residenza dei dati per i dati in uso e in transito. Per saperne di più sul comportamento dei singoli server MCP, consulta Prodotti supportati da Model Armor.

Abilita Model Armor

Prima di poter utilizzare Model Armor, devi abilitare le API Model Armor.

Console

  1. Abilita l'API Model Armor.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  2. Seleziona il progetto in cui vuoi attivare Model Armor.

gcloud

Prima di iniziare, segui questi passaggi utilizzando Google Cloud CLI con l'API Model Armor:

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  2. Esegui questo comando per impostare l'endpoint API per il servizio Model Armor.

    gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

    Sostituisci LOCATION con la regione in cui vuoi utilizzare Model Armor.

Configurare la protezione per i server MCP remoti di Google e Google Cloud

Per proteggere le chiamate e le risposte degli strumenti MCP, puoi utilizzare le impostazioni di base di Model Armor. Un'impostazione di base definisce i filtri di sicurezza minimi che vengono applicati al progetto. Questa configurazione applica un insieme coerente di filtri a tutte le chiamate e le risposte dello strumento MCP all'interno del progetto.

Configura un'impostazione di base di Model Armor con la sanificazione MCP attivata. Per saperne di più, consulta Configurare le impostazioni di base di Model Armor.

Vedi il seguente comando di esempio:

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-floor-setting-enforcement=TRUE \
--add-integrated-services=GOOGLE_MCP_SERVER \
--google-mcp-server-enforcement-type=INSPECT_AND_BLOCK \
--enable-google-mcp-server-cloud-logging \
--malicious-uri-filter-settings-enforcement=ENABLED \
--add-rai-settings-filters='[{"confidenceLevel": "MEDIUM_AND_ABOVE", "filterType": "DANGEROUS"}]'

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Tieni presente le seguenti impostazioni:

  • INSPECT_AND_BLOCK: il tipo di applicazione che ispeziona i contenuti per il server MCP di Google e blocca i prompt e le risposte che corrispondono ai filtri.
  • ENABLED: l'impostazione che attiva un filtro o l'applicazione.
  • MEDIUM_AND_ABOVE: il livello di confidenza per le impostazioni del filtro AI responsabile - Pericoloso. Puoi modificare questa impostazione, anche se valori più bassi potrebbero generare più falsi positivi. Per saperne di più, consulta Livelli di confidenza di Model Armor.

Disabilita l'analisi del traffico MCP con Model Armor

Per impedire a Model Armor di analizzare automaticamente il traffico da e verso i server MCP di Google in base alle impostazioni di base del progetto, esegui questo comando:

gcloud model-armor floorsettings update \
  --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
  --remove-integrated-services=GOOGLE_MCP_SERVER

Sostituisci PROJECT_ID con l'ID progetto Google Cloud . Model Armor non applica automaticamente le regole definite nelle impostazioni di base di questo progetto al traffico dei server MCP Google.

Le impostazioni di base di Model Armor e la configurazione generale possono influire su più di un semplice MCP. Poiché Model Armor si integra con servizi come Vertex AI, qualsiasi modifica apportata alle impostazioni di base può influire sulla scansione del traffico e sui comportamenti di sicurezza in tutti i servizi integrati, non solo in MCP.

Passaggi successivi