Connettiti a un agente per i dati utilizzando MCP

In qualità di amministratore di una piattaforma agentica di terze parti (come Claude Code, Claude Cowork o ChatGPT) o gestita da Google (come Gemini Enterprise), puoi configurare una connessione Model Context Protocol (MCP) personalizzata al server MCP remoto dell'API Analisi conversazionale (https://geminidataanalytics.googleapis.com/mcp). La connessione della tua piattaforma agentica a questo server consente all'agente root della tua piattaforma di scoprire ed eseguire query su agenti per i dati specializzati per conto degli utenti aziendali.

Il server MCP remoto dell'API Analisi conversazionale utilizza un flusso OAuth 2.0 a tre vie per propagare le credenziali dell'utente finale (EUC) a BigQuery. Questa propagazione garantisce che le richieste di discovery dell'agente e le query BigQuery vengano eseguite con l'identità dell'utente autenticato e rispettino le autorizzazioni di Identity and Access Management (IAM) e le policy di governance dei dati esistenti. Gli agenti per i dati basati su Looker non ricevono le credenziali dell'utente finale; le query richiedono invece credenziali client API Looker separate (consulta Autenticazione per gli agenti per i dati basati su Looker).

Per una panoramica dell'architettura di come gli agenti root, ovvero l'agente di orchestrazione principale che riceve le richieste degli utenti, comunicano con il server MCP remoto, consulta Server MCP remoto dell'API Analisi conversazionale.

Prima di iniziare

Prima di configurare la connessione MCP nella tua piattaforma agentica, completa i seguenti prerequisiti:

  1. Nel tuo progetto Google Cloud , abilita le API richieste per l'API Analisi conversazionale e BigQuery.
  2. Assicurati che gli operatori dei dati abbiano creato e configurato uno o più agenti per i datinel tuo progetto Google Cloud , incluse descrizioni chiare delle origini dati a cui ogni agente può accedere e delle domande a cui può rispondere.
  3. Verifica che gli utenti aziendali che eseguiranno l'autenticazione tramite la connessione MCP dispongano dei ruoli IAM richiesti e dell'accesso in lettura ai set di dati di destinazione e all'agente.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per autenticarti tramite il server MCP remoto ed eseguire query sugli agenti per i dati, chiedi all'amministratore di concederti i seguenti ruoli IAM:

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

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura le credenziali e gli ambiti OAuth 2.0

Per consentire alla tua piattaforma agentica di autenticare gli utenti e inoltrare le loro credenziali al server MCP remoto dell'API Analisi conversazionale, devi creare credenziali OAuth 2.0 (un ID client e un client secret) nel tuo progetto Google Cloud .

Segui i passaggi standard descritti in Utilizzare OAuth 2.0 per accedere alle API di Google per configurare la schermata per il consenso OAuth e creare un ID client OAuth 2.0 nella pagina Credenziali della consoleGoogle Cloud . Quando configuri le credenziali, applica le seguenti impostazioni specifiche per l'integrazione dell'MCP dell'API Analisi conversazionale:

  1. Pubblico: se la tua organizzazione utilizza Google Workspace, seleziona Interno. Questa selezione limita l'accesso agli utenti della tua organizzazione, evita la necessità di verifica app OAuth per gli ambiti sensibili e garantisce che le policy di controllo dell'accesso alle app di Google Workspace non impediscano l'autenticazione degli utenti.
  2. Tipo di applicazione e URI di reindirizzamento: seleziona Applicazione web come tipo di applicazione e aggiungi l'URI di reindirizzamento autorizzato richiesto dalla tua piattaforma agentica (ad esempio, https://vertexaisearch.cloud.google.com/oauth-redirect quando configuri un connettore MCP personalizzato in Gemini Enterprise).
  3. Ambiti OAuth: configura la schermata per il consenso OAuth e il client in modo che richiedano entrambi i seguenti ambiti, in modo che l'agente principale disponga dell'autorizzazione per chiamare gli strumenti dell'API Analisi conversazionale ed eseguire query BigQuery di sola lettura per conto dell'utente:
    • Ambito di Gemini Data Analytics: https://www.googleapis.com/auth/geminidataanalytics
    • Ambito di sola lettura di BigQuery: https://www.googleapis.com/auth/bigquery.readonly
  4. Copia e archivia in modo sicuro l'ID client e il client secret generati.

Configura la connessione MCP personalizzata

Dopo aver generato l'ID client e il client secret OAuth 2.0, registra una connessione MCP personalizzata (o un connettore MCP personalizzato) nelle impostazioni di amministrazione della tua piattaforma agentica:

  1. Nella tua piattaforma agentica, crea una nuova connessione al server MCP personalizzata e specifica i seguenti valori di configurazione:

    Impostazione Valore
    URL server MCP https://geminidataanalytics.googleapis.com/mcp
    Metodo di autenticazione OAuth 2.0
    URL di autorizzazione https://accounts.google.com/o/oauth2/v2/auth
    Parametri URL di autorizzazione

    &access_type=offline&prompt=consent

    Utilizza questa stringa di parametri se la tua piattaforma richiede token di aggiornamento offline per le sessioni utente.
    URL del token https://oauth2.googleapis.com/token
    Ambiti

    https://www.googleapis.com/auth/geminidataanalytics

    https://www.googleapis.com/auth/bigquery.readonly

    Se la tua piattaforma prevede una singola stringa separata da spazi, inserisci:

    https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly
    ID client CLIENT_ID (l'ID client OAuth 2.0 che hai creato nella sezione precedente)
    Client secret CLIENT_SECRET (il client secret OAuth 2.0 che hai creato nella sezione precedente)

  2. Se richiesto, verifica la connessione OAuth nella tua piattaforma. Quando si apre la schermata per il consenso di Google, accedi e conferma che l'applicazione richiede l'accesso di sola lettura sia a Gemini Data Analytics sia a BigQuery.

  3. Sincronizza o ricarica gli strumenti (azioni) per la connessione MCP nella tua piattaforma, in modo che il client MCP chiami tools/list su https://geminidataanalytics.googleapis.com/mcp per importare gli schemi degli strumenti (come list_data_agents, get_data_agent e chat) e verifica che gli strumenti importati siano abilitati.

Configura le istruzioni del prompt per l'agente principale

Gli strumenti MCP dell'API Analisi conversazionale, list_data_agents, get_data_agent e chat, richiedono un ID progetto Google Cloud e una località di destinazione (ad esempio, projects/PROJECT_ID/locations/LOCATION). Poiché gli utenti aziendali in genere non sanno quale ID progetto Google Cloud ospita gli agenti per i dati della tua organizzazione, fornisci l'ID progetto e la località di destinazione nelle istruzioni di sistema personalizzate o nella configurazione delle skill dell'agente root. In questo modo, l'agente principale non chiederà agli utenti aziendali di fornire un ID progetto quando pongono una domanda sui dati.

Aggiungi istruzioni di sistema per il routing e il rilevamento degli agenti

Aggiungi le seguenti istruzioni al prompt di sistema o alle istruzioni personalizzate dell'agente root, sostituendo PROJECT_ID con l'ID progetto Google Cloude LOCATION con la località delle risorse (ad esempio global, us o eu):

When answering questions about enterprise data using the Conversational
Analytics MCP tools, always use the Google Cloud project ID
"PROJECT_ID" and location "LOCATION" (resource path
"projects/PROJECT_ID/locations/LOCATION"). Do not ask the user to
provide a Google Cloud project ID or location.

To answer a user's data question:
1. Call list_data_agents for "projects/PROJECT_ID/locations/LOCATION"
   to discover the available data agents and review their descriptions.
2. If you need additional context about a candidate agent's connected tables or
   verified queries, call get_data_agent for that agent.
3. Call the chat tool passing parent ("projects/PROJECT_ID/locations/LOCATION"),
   dataAgentContext with the full agent resource name
   ("projects/PROJECT_ID/locations/LOCATION/dataAgents/<var>AGENT_ID</var>"),
   and the user's question in messages.

Autenticazione per gli agenti per i dati basati su Looker

Se gli agenti per i dati si connettono alle esplorazioni di Looker, le richieste allo strumento chat devono includere un blocco credentials contenente le credenziali dell'API Looker (un ID client e un client secret), perché Looker gestisce l'autenticazione indipendentemente da IAM.

Quando configuri la tua piattaforma agentica per gli agenti per i dati basati su Looker, applica le seguenti best practice:

  • Non chiedere agli utenti informazioni sensibili: configura l'agente principale in modo che non chieda mai agli utenti finali di incollare o fornire le credenziali dell'API Looker nella chat.
  • Utilizza un account utente dell'API Looker dedicato: crea un utente dell'API Looker dedicato con autorizzazioni con privilegio minimo limitate solo ai modelli e alle esplorazioni di cui l'agente per i dati ha bisogno.
  • Inserisci le credenziali al di fuori del contesto del modello: configura la tua piattaforma, il middleware del client MCP o il livello proxy per inserire le credenziali dell'API Looker nel payload della richiesta chat a livello di trasporto o di esecuzione dello strumento. Non inserire il client secret nelle istruzioni del prompt o nella cronologia delle conversazioni dell'agente principale.

Pattern di inserimento delle credenziali per le piattaforme agentiche

Per tenere i secret fuori dalla finestra di contesto del modello, le piattaforme in genere inseriscono le credenziali di Looker utilizzando uno dei seguenti approcci:

  • Intercettazione del proxy o del middleware del client MCP: nelle piattaforme che supportano il middleware delle richieste, gli API Gateway o gli hook di intercettazione degli strumenti, l'agente principale genera la chiamata allo strumento chat contenente solo i parametri semantici (parent, dataAgentContext e messages). Il livello middleware intercetta la richiesta JSON-RPC in uscita prima che raggiunga https://geminidataanalytics.googleapis.com/mcp, legge le credenziali da un archivio di secret sicuro o da variabili di ambiente e compila l'oggetto credentials.
  • Definizioni degli strumenti con wrapper: nei framework degli agenti personalizzati (come l'Agent Development Kit (ADK) o gli orchestratori Python personalizzati), esponi all'agente root una versione con wrapper dello strumento chat che omette il parametro credentials dallo schema dello strumento. Il gestore dell'esecuzione del wrapper collega il blocco credentials in modo programmatico da una configurazione sicura prima di inoltrare la chiamata al server MCP dell'API Analisi conversazionale.

L'esempio seguente mostra il payload completo della richiesta JSON-RPC che il client MCP invia al server MCP remoto per lo strumento chat. Mentre il modello genera i parametri parent, dataAgentContext e messages, la piattaforma host o il middleware del client MCP compila l'oggetto credentials prima di inviare la richiesta:

{
  "parent": "projects/PROJECT_ID/locations/LOCATION",
  "dataAgentContext": {
    "dataAgent": "projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID"
  },
  "credentials": {
    "oauth": {
      "secret": {
        "clientId": "LOOKER_CLIENT_ID",
        "clientSecret": "LOOKER_CLIENT_SECRET"
      }
    }
  },
  "messages": [
    {
      "userMessage": {
        "text": "USER_QUESTION"
      }
    }
  ]
}

Sostituisci i valori di esempio come segue:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud
  • LOCATION: la località delle risorse dell'API Analisi conversazionale (ad esempio, global)
  • AGENT_ID: l'ID dell'agente per i dati basato su Looker
  • LOOKER_CLIENT_ID: l'ID client dell'utente dell'API Looker
  • LOOKER_CLIENT_SECRET: il client secret per l'utente dell'API Looker
  • USER_QUESTION: il prompt o la domanda da inviare all'agente per i dati

Verifica la connessione con un prompt di test

Dopo aver collegato la connessione MCP personalizzata alla tua applicazione agente, apri l'interfaccia di chat della tua piattaforma, autorizza la sessione utente quando richiesto e invia un prompt di test per confermare che l'agente principale può richiamare gli strumenti MCP dell'API Analisi conversazionale ed eseguire query su BigQuery utilizzando le tue credenziali delegate.

Se hai configurato le istruzioni di sistema nella sezione precedente, puoi porre una domanda direttamente agli agenti per i dati o eseguire una query di test su un set di dati pubblico BigQuery specificando il progetto, la località e il set di dati nel prompt:

What are the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales?

Puoi anche indicare esplicitamente all'agente principale di chiamare lo strumento chat dal connettore MCP (CONNECTOR_NAME):

Use the chat tool from CONNECTOR_NAME to find the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales.

Sostituisci i valori di esempio come segue:

  • PROJECT_ID: l'ID del progettoGoogle Cloud in cui hai abilitato l'API Analisi conversazionale
  • LOCATION: la località delle risorse dell'API Analisi conversazionale (ad esempio, global)
  • CONNECTOR_NAME: il nome che hai assegnato alla connessione MCP personalizzata nella tua piattaforma agentica (ad esempio, ca-mcp-prod)

Passaggi successivi