Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare il server MCP remoto BigQuery

Questo documento descrive come utilizzare il server BigQuery Remote Model Context Protocol (MCP) per connettersi a BigQuery da applicazioni AI come Gemini CLI, modalità agente in Gemini Code Assist, Claude Code o in applicazioni AI che stai sviluppando.

Il Model Context Protocol (MCP) standardizza il modo in cui i modelli linguistici di grandi dimensioni (LLM) e le applicazioni o gli 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.

I 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. I server MCP remoti vengono eseguiti sull'infrastruttura del servizio e offrono un endpoint HTTPS alle applicazioni AI per la comunicazione tra il client AI MCP e il server MCP. Per saperne di più sull'architettura MCP, consulta la pagina Architettura MCP.

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

Rilevamento semplificato e centralizzato
Endpoint HTTPS globali o regionali gestiti
Autorizzazione granulare
Sicurezza facoltativa di prompt e risposte con la protezione Model Armor
Audit logging 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.

Potresti utilizzare il server MCP locale di BigQuery per i seguenti motivi:

Devi creare uno strumento personalizzato su una query SQL con parametri.
Non disponi delle autorizzazioni per abilitare o utilizzare il server MCP remoto nel tuo progetto.

Per saperne di più su come utilizzare il nostro server MCP locale, consulta Connettere i LLM a BigQuery con MCP. Le sezioni seguenti si applicano solo al server MCP remoto BigQuery.

Prima di iniziare

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.

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

Enable the BigQuery API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API

Per i nuovi progetti, l'API BigQuery viene abilitata automaticamente.
(Facoltativo) Abilita la fatturazione per il progetto. Se non vuoi attivare la fatturazione o fornire una carta di credito, i passaggi descritti in questo documento funzionano comunque. BigQuery ti offre una sandbox per eseguire i passaggi. Per saperne di più, vedi Attiva la sandbox di BigQuery.
Nota:se il tuo progetto ha un account di fatturazione e vuoi utilizzare la sandbox di BigQuery, allora disattiva la fatturazione per il tuo progetto.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per abilitare il server BigQuery MCP, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto in cui vuoi abilitare il server BigQuery MCP:

Abilita le API e i server MCP nel progetto: Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin)
Effettua chiamate allo strumento MCP: Utente dello strumento MCP (roles/mcp.toolUser)
Esegui job BigQuery: Utente job BigQuery (roles/bigquery.jobUser)
Esegui query sui dati BigQuery: Visualizzatore dati BigQuery (roles/bigquery.dataViewer)

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 attivare il server BigQuery MCP. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per abilitare il server BigQuery MCP sono necessarie le seguenti autorizzazioni:

Abilita i server MCP in un progetto:
- serviceusage.mcppolicy.get
- serviceusage.mcppolicy.update
Effettua chiamate allo strumento MCP: mcp.tools.call
Esegui job BigQuery: bigquery.jobs.create
Esegui query sui dati BigQuery: bigquery.tables.getData

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

Attivare o disattivare il server MCP BigQuery

Puoi attivare o disattivare il server BigQuery MCP in un progetto con il comando gcloud beta services mcp enable. Per saperne di più, consulta le sezioni seguenti.

Abilitare il server MCP BigQuery in un progetto

Se utilizzi progetti diversi per le credenziali client, ad esempio chiavi del service account, ID client OAuth o chiavi API, e per l'hosting delle risorse, devi abilitare il servizio BigQuery e il server MCP remoto BigQuery in entrambi i progetti.

Per attivare il server BigQuery MCP nel tuo progetto Google Cloud , esegui il seguente comando:

gcloud beta services mcp enable SERVICE \
    --project=PROJECT_ID

Sostituisci quanto segue:

PROJECT_ID: l' Google Cloud ID progetto
SERVICE: bigquery.googleapis.com (il nome del servizio globale per BigQuery)

Il server MCP remoto BigQuery è abilitato per l'utilizzo nel tuo progettoGoogle Cloud . Se il servizio BigQuery non è abilitato per il tuo progetto Google Cloud , ti viene chiesto di abilitarlo prima di abilitare il server MCP remoto BigQuery.

Come best practice di sicurezza, ti consigliamo di abilitare i server MCP solo per i servizi necessari per il funzionamento della tua applicazione di AI.

Disattivare il server MCP BigQuery in un progetto

Per disattivare il server BigQuery MCP nel tuo progetto Google Cloud , esegui il seguente comando:

gcloud beta services mcp disable SERVICE \
    --project=PROJECT_ID

Il server BigQuery MCP è disabilitato per l'utilizzo nel tuo progettoGoogle Cloud .

Autenticazione e autorizzazione

I server BigQuery MCP utilizzano 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 BigQuery non accetta chiavi API.

Ambiti OAuth di BigQuery MCP

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, leggi Utilizzare OAuth 2.0 per accedere alle API di Google.

BigQuery ha i seguenti ambiti OAuth dello strumento MCP:

URI dell'ambito per gcloud CLI	Descrizione
`https://www.googleapis.com/auth/bigquery`	Visualizzare e gestire i tuoi dati in BigQuery, nonché vedere l'indirizzo email del tuo Account Google.

Potrebbero essere necessari ambiti aggiuntivi per le risorse a cui si accede durante una chiamata di strumenti. Per visualizzare un elenco degli ambiti richiesti per BigQuery, consulta Ambiti OAuth 2.0 per l'API BigQuery v2.

Configurare un client MCP per utilizzare il server MCP BigQuery

I programmi host, come Claude o Gemini CLI, possono creare istanze di client MCP che si connettono a un singolo server MCP. Un programma host può avere più client che si connettono a server MCP diversi. Per connettersi a un server MCP remoto, il client MCP deve conoscere almeno l'URL del server MCP remoto.

Nell'host, cerca un modo per connetterti a un server MCP remoto. Ti viene chiesto di inserire i dettagli del server, come nome e URL.

Per il server BigQuery MCP, inserisci quanto segue come richiesto:

Nome server: server BigQuery MCP
URL server o Endpoint: bigquery.googleapis.com/mcp
Trasporto: HTTP
Dettagli di autenticazione: le tue Google Cloud credenziali, il tuo ID client OAuth e il tuo client secret OAuth oppure un'identità e credenziali dell'agente

I dettagli di autenticazione che scegli dipendono dal metodo di autenticazione che vuoi utilizzare. Per maggiori informazioni, consulta Eseguire l'autenticazione nei server MCP.

Per indicazioni specifiche per l'host, consulta quanto segue:

Per indicazioni più generali, vedi Connettersi ai server MCP remoti.

Strumenti disponibili

Gli strumenti MCP di sola lettura hanno l'attributo MCP mcp.tool.isReadOnly impostato su true. Potresti voler consentire solo strumenti di sola lettura in determinati ambienti tramite i criteri dell'organizzazione.

Per visualizzare i dettagli degli strumenti MCP disponibili e le relative descrizioni per il server MCP BigQuery, consulta le informazioni di riferimento su MCP BigQuery.

Strumenti per le liste

Utilizza lo strumento di analisi MCP per elencare gli strumenti o invia una richiesta HTTP tools/list direttamente al server MCP remoto di BigQuery. Il metodo tools/list non richiede l'autenticazione.

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

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

Esempi di casi d'uso

Di seguito sono riportati alcuni casi d'uso di esempio per il server BigQuery MCP:

Crea flussi di lavoro che utilizzano gli approfondimenti dei dati BigQuery per attivare determinate azioni, come la creazione di problemi e la composizione di email.
Utilizza le funzionalità avanzate di BigQuery, come la previsione, per ottenere approfondimenti di ordine superiore.
Crea un'esperienza conversazionale per i tuoi utenti con istruzioni personalizzate per l'agente.

Prompt di esempio

Puoi utilizzare i seguenti prompt di esempio per ottenere informazioni sulle risorse BigQuery, ricavare approfondimenti e analizzare i dati BigQuery:

Elenca i set di dati nel progetto PROJECT_ID.
Trova tutte le query che ho eseguito nel progetto PROJECT_ID utilizzando il server MCP nella regione REGION. Utilizza il tag goog-mcp-server:true per identificare i job di query eseguiti tramite il server MCP.
Trova gli ordini con il volume più alto di DATASET_ID nel progetto PROJECT_ID. Identifica le tabelle appropriate, trova lo schema corretto e mostra i risultati.
Crea una previsione nella tabella PROJECT_ID.DATASET_ID.TABLE_ID per gli anni futuri. Utilizza COLUMN_NAME come colonna dei dati e COLUMN_NAME come colonna dei timestamp. Mostra le prime 10 previsioni.

Nei prompt, sostituisci quanto segue:

PROJECT_ID: l' Google Cloud ID progetto
REGION: il nome della regione
DATASET_ID: il nome del set di dati
TABLE_ID: il nome della tabella
COLUMN_NAME: il nome della colonna

Configurazioni di sicurezza e protezione facoltative

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

Per ulteriori informazioni sulla sicurezza e sulla governance di MCP, vedi Sicurezza dell'AI.

Model Armor

Model Armor è un servizio Google Cloud progettato per migliorare la sicurezza delle tue applicazioni AI. Funziona controllando in modo proattivo i prompt e le risposte dei LLM, proteggendo da vari rischi e supportando pratiche di AI responsabile. Che tu esegua il deployment dell'AI nel tuo ambiente cloud o su 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.

Model Armor è disponibile solo in località regionali specifiche. Se Model Armor è abilitato per un progetto e una chiamata a questo progetto proviene da una regione non supportata, Model Armor effettua una chiamata tra regioni. Per saperne di più, consulta Località di Model Armor.

Abilita Model Armor

Per attivare Model Armor, completa i seguenti passaggi:

Abilita Model Armor nel tuo progetto Google Cloud .
```
gcloud services enable modelarmor.googleapis.com \
    --project=PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Configura le impostazioni di base consigliate per Model Armor.

gcloud model-armor floorsettings update \
    --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
    --mcp-sanitization=ENABLED \
    --malicious-uri-filter-settings-enforcement=ENABLED \
    --pi-and-jailbreak-filter-settings-enforcement=ENABLED \
    --pi-and-jailbreak-filter-settings-confidence-level=MEDIUM_AND_ABOVE

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Model Armor è configurato per eseguire la scansione alla ricerca di URL dannosi e tentativi di prompt injection e jailbreak.

Per saperne di più sui filtri Model Armor configurabili, consulta Filtri Model Armor.

Aggiungi Model Armor come fornitore di sicurezza dei contenuti per i servizi MCP.
```
gcloud beta services mcp content-security add modelarmor.googleapis.com \
    --project=PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .
Verifica che il traffico MCP venga inviato a Model Armor.
```
gcloud beta services mcp content-security get \
    --project=PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Logging di Model Armor

Per informazioni sui log di controllo e della piattaforma Model Armor, vedi Log di controllo Model Armor.

Disabilitare Model Armor in un progetto

Per disattivare Model Armor in un progetto Google Cloud , esegui questo comando:

gcloud beta services mcp content-security remove modelarmor.googleapis.com \
    --project=PROJECT_ID

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Il traffico MCP su Google Cloud non viene analizzato da Model Armor per il progetto specificato.

Disattivare l'analisi del traffico MCP con Model Armor

Se vuoi comunque utilizzare Model Armor in un progetto, ma vuoi interrompere la scansione del traffico MCP con Model Armor, esegui il seguente comando:

gcloud model-armor floorsettings update \
    --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
    --mcp-sanitization=DISABLED

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Model Armor non esegue la scansione del traffico MCP su Google Cloud.

Controllo MCP a livello di organizzazione

Puoi creare policy dell'organizzazione personalizzate per controllare l'utilizzo dei server MCP nella tua organizzazione Google Cloud utilizzando il vincologcp.managed.allowedMCPService. Per ulteriori informazioni ed esempi di utilizzo, consulta Controllo dell'accesso con IAM.

Quote e limiti

Il server MCP remoto BigQuery non ha quote proprie. Non esiste un limite al numero di chiamate che possono essere effettuate al server MCP.

Sei comunque soggetto alle quote applicate dalle API chiamate dagli strumenti server MCP. I seguenti metodi API vengono chiamati dagli strumenti del server MCP:

Strumento	Metodo API	Quote
`list_dataset_ids`	`datasets.list`	Quote e limiti dei set di dati
`list_table_ids`	`tables.list`	Quote e limiti delle tabelle
`get_dataset_info`	`datasets.get`	Quote e limiti dei set di dati
`get_table_info`	`tables.get`	Quote e limiti delle tabelle
`execute_sql`	`jobs.Query`	Quote e limiti dei job di query

Per saperne di più sulle quote di BigQuery, consulta Quote e limiti.

Passaggi successivi

Leggi la documentazione di riferimento di BigQuery MCP.
Scopri di più sui server MCP di Google Cloud.
Consulta i prodotti supportati da MCP.