Se connecter à un agent de données à l'aide de MCP

En tant qu'administrateur d'une plate-forme d'agents tiers (comme Claude Code, Claude Cowork ou ChatGPT) ou gérée par Google (comme Gemini Enterprise), vous pouvez configurer une connexion Model Context Protocol (MCP) personnalisée au serveur MCP distant de l'API Conversational Analytics (https://geminidataanalytics.googleapis.com/mcp). Connecter votre plate-forme d'agents à ce serveur permet à l'agent racine de votre plate-forme de découvrir et d'interroger des agents de données spécialisés au nom des utilisateurs professionnels.

Le serveur MCP distant de l'API Conversational Analytics utilise un flux OAuth 2.0 à trois étapes pour propager les identifiants de l'utilisateur final (EUC) vers BigQuery. Cette propagation garantit que les requêtes de découverte de l'agent et les requêtes BigQuery s'exécutent sous l'identité de l'utilisateur authentifié et respectent les autorisations IAM (Identity and Access Management) et les règles de gouvernance des données existantes. Les agents de données basés sur Looker ne reçoivent pas les identifiants de l'utilisateur final. À la place, les requêtes nécessitent des identifiants client d'API Looker distincts (voir "Authentification pour les agents de données basés sur Looker").

Pour obtenir une présentation de l'architecture de la communication entre les agents racine (l'agent d'orchestration principal qui reçoit les requêtes des utilisateurs) et le serveur MCP distant, consultez Serveur MCP distant de l'API Conversational Analytics.

Avant de commencer

Avant de configurer la connexion MCP dans votre plate-forme d'agents, remplissez les conditions préalables suivantes :

  1. Dans votre projet Google Cloud , activez les API requises pour l'API Conversational Analytics et BigQuery.
  2. Assurez-vous que les opérateurs de données ont créé et configuré un ou plusieurs agents de données dans votre projet Google Cloud , y compris des descriptions claires des sources de données auxquelles chaque agent peut accéder et des questions auxquelles il peut répondre.
  3. Vérifiez que les utilisateurs professionnels qui s'authentifieront via la connexion MCP disposent des rôles IAM requis, d'un accès en lecture aux ensembles de données cibles et d'un accès à l'agent.

Rôles requis

Pour obtenir les autorisations nécessaires pour vous authentifier via le serveur MCP distant et interroger les agents de données, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer les identifiants et les champs d'application OAuth 2.0

Pour permettre à votre plate-forme d'agents d'authentifier les utilisateurs et de transmettre leurs identifiants au serveur MCP distant de l'API Conversational Analytics, vous devez créer des identifiants OAuth 2.0 (un ID client et un code secret du client) dans votre projet Google Cloud .

Suivez les étapes standards de la section Utiliser OAuth 2.0 pour accéder aux API Google pour configurer votre écran de consentement OAuth et créer un ID client OAuth 2.0 sur la page Identifiants de la consoleGoogle Cloud . Lorsque vous configurez vos identifiants, appliquez les paramètres suivants, qui sont spécifiques à l'intégration de l'API Conversational Analytics à MCP :

  1. Audience : si votre organisation utilise Google Workspace, sélectionnez Interne. Cette sélection limite l'accès aux utilisateurs de votre organisation, évite d'avoir à valider l'application OAuth pour les champs d'application sensibles et garantit que les règles de contrôle d'accès aux applications Google Workspace ne bloquent pas l'authentification des utilisateurs.
  2. Type d'application et URI de redirection : sélectionnez Application Web comme type d'application, puis ajoutez l'URI de redirection autorisé requis par votre plate-forme d'agents (par exemple, https://vertexaisearch.cloud.google.com/oauth-redirect lors de la configuration d'un connecteur MCP personnalisé dans Gemini Enterprise).
  3. Champs d'application OAuth : configurez votre écran de consentement et votre client OAuth pour demander les deux champs d'application suivants afin que l'agent racine soit autorisé à appeler les outils de l'API Conversational Analytics et à exécuter des requêtes BigQuery en lecture seule au nom de l'utilisateur :
    • Champ d'application de Gemini Data Analytics : https://www.googleapis.com/auth/geminidataanalytics
    • Champ d'application en lecture seule BigQuery : https://www.googleapis.com/auth/bigquery.readonly
  4. Copiez et stockez de manière sécurisée l'ID client et le code secret du client générés.

Configurer la connexion MCP personnalisée

Après avoir généré votre ID client et votre code secret du client OAuth 2.0, enregistrez une connexion MCP personnalisée (ou un connecteur MCP personnalisé) dans les paramètres d'administration de votre plate-forme d'agents :

  1. Dans votre plate-forme d'agents, créez une nouvelle connexion de serveur MCP personnalisée et spécifiez les valeurs de configuration suivantes :

    Paramètre Valeur
    URL du serveur MCP https://geminidataanalytics.googleapis.com/mcp
    Méthode d'authentification OAuth 2.0
    URL d'autorisation https://accounts.google.com/o/oauth2/v2/auth
    Paramètres d'URL d'autorisation

    &access_type=offline&prompt=consent

    Utilisez cette chaîne de paramètres si votre plate-forme nécessite des jetons d'actualisation hors connexion pour les sessions utilisateur.
    URL du jeton https://oauth2.googleapis.com/token
    Champs d'application

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

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

    Si votre plate-forme attend une seule chaîne séparée par des espaces, saisissez :

    https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly
    ID client CLIENT_ID (l'ID client OAuth 2.0 que vous avez créé dans la section précédente)
    Code secret du client CLIENT_SECRET (le code secret du client OAuth 2.0 que vous avez créé dans la section précédente)

  2. Si vous y êtes invité, validez la connexion OAuth sur votre plate-forme. Lorsque l'écran de consentement Google s'ouvre, connectez-vous et confirmez que l'application demande un accès en lecture seule à Gemini Data Analytics et à BigQuery.

  3. Synchronisez ou actualisez les outils (actions) de la connexion MCP sur votre plate-forme afin que le client MCP appelle tools/list sur https://geminidataanalytics.googleapis.com/mcp pour importer les schémas d'outils (tels que list_data_agents, get_data_agent et chat), puis vérifiez que les outils importés sont activés.

Configurer les instructions du prompt pour l'agent racine

Les outils MCP de l'API Conversational Analytics (list_data_agents, get_data_agent et chat) nécessitent un ID de projet Google Cloud cible et un emplacement (par exemple, projects/PROJECT_ID/locations/LOCATION). Comme les utilisateurs professionnels ne savent généralement pas quel ID de projet Google Cloud héberge les agents de données de votre organisation, indiquez l'ID de projet cible et l'emplacement dans les instructions système personnalisées ou la configuration des compétences de votre agent racine. Cela évite que l'agent racine ne demande aux utilisateurs professionnels de fournir un ID de projet lorsqu'ils posent une question sur les données.

Ajouter des instructions système pour la découverte et le routage des agents

Ajoutez les instructions suivantes au prompt système ou aux instructions personnalisées de votre agent racine, en remplaçant PROJECT_ID par l'ID de votre projet Google Cloudet LOCATION par l'emplacement de votre ressource (par exemple, global, us ou 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.

Authentification pour les agents de données basés sur Looker

Si vos agents de données se connectent à des explorations Looker, les requêtes adressées à l'outil chat doivent inclure un bloc credentials contenant les identifiants de l'API Looker (un ID client et un code secret du client), car Looker gère l'authentification indépendamment d'IAM.

Lorsque vous configurez votre plate-forme agentique pour les agents de données basés sur Looker, appliquez les bonnes pratiques suivantes :

  • Ne demandez pas de secrets aux utilisateurs : configurez l'agent racine pour qu'il ne demande jamais aux utilisateurs finaux de coller ou de fournir des identifiants de l'API Looker dans le chat.
  • Utilisez un compte utilisateur dédié pour l'API Looker : créez un utilisateur dédié pour l'API Looker avec des autorisations de moindre privilège limitées aux modèles et aux explorations dont l'agent de données a besoin.
  • Injecter des identifiants en dehors du contexte du modèle : configurez votre plate-forme, le middleware du client MCP ou la couche proxy pour injecter les identifiants de l'API Looker dans la charge utile de la requête chat au niveau de la couche de transport ou d'exécution de l'outil. Ne placez pas le code secret du client dans les instructions de prompt ou l'historique des conversations de l'agent racine.

Modèles d'injection d'identifiants pour les plates-formes agentiques

Pour que les secrets ne soient pas inclus dans la fenêtre de contexte du modèle, les plates-formes injectent généralement les identifiants Looker à l'aide de l'une des approches suivantes :

  • Middleware client MCP ou interception de proxy : sur les plates-formes compatibles avec le middleware de requête, les API Gateway ou les hooks d'interception d'outils, l'agent racine génère l'appel d'outil chat contenant uniquement les paramètres sémantiques (parent, dataAgentContext et messages). La couche de middleware intercepte la requête JSON-RPC sortante avant qu'elle n'atteigne https://geminidataanalytics.googleapis.com/mcp, lit les identifiants à partir d'un magasin de secrets sécurisé ou de variables d'environnement, puis remplit l'objet credentials.
  • Définitions d'outils encapsulés : dans les frameworks d'agents personnalisés (comme l'Agent Development Kit (ADK) ou les orchestrateurs Python personnalisés), exposez une version encapsulée de l'outil chat à l'agent racine qui omet le paramètre credentials du schéma de l'outil. Le gestionnaire d'exécution du wrapper associe le bloc credentials de manière programmatique à partir d'une configuration sécurisée avant de transférer l'appel au serveur MCP de l'API Conversational Analytics.

L'exemple suivant montre la charge utile de requête JSON-RPC complète que le client MCP envoie au serveur MCP distant pour l'outil chat. Pendant que le modèle génère les paramètres parent, dataAgentContext et messages, la plate-forme hôte ou le middleware du client MCP remplit l'objet credentials avant d'envoyer la requête :

{
  "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"
      }
    }
  ]
}

Remplacez les exemples de valeurs comme suit :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de vos ressources de l'API Conversational Analytics (par exemple, global)
  • AGENT_ID : ID de votre agent de données basé sur Looker
  • LOOKER_CLIENT_ID : ID client de votre utilisateur de l'API Looker
  • LOOKER_CLIENT_SECRET : code secret du client pour votre utilisateur de l'API Looker
  • USER_QUESTION : requête ou question à envoyer à l'agent de données.

Vérifier la connexion avec un prompt de test

Après avoir associé la connexion MCP personnalisée à votre application d'agent, ouvrez l'interface de chat de votre plate-forme, autorisez votre session utilisateur lorsque vous y êtes invité, puis envoyez un prompt de test pour confirmer que l'agent racine peut appeler les outils MCP de l'API Conversational Analytics et interroger BigQuery à l'aide de vos identifiants délégués.

Si vous avez configuré les instructions système dans la section précédente, vous pouvez poser une question directement à vos agents de données ou exécuter une requête de test sur un ensemble de données public BigQuery en spécifiant le projet, l'emplacement et l'ensemble de données dans votre requête :

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

Vous pouvez également demander explicitement à l'agent racine d'appeler l'outil chat à partir de votre connecteur 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.

Remplacez les exemples de valeurs comme suit :

  • PROJECT_ID : ID du projetGoogle Cloud dans lequel vous avez activé l'API Conversational Analytics
  • LOCATION : emplacement de vos ressources de l'API Conversational Analytics (par exemple, global)
  • CONNECTOR_NAME : nom que vous avez attribué à la connexion MCP personnalisée dans votre plate-forme d'agents (par exemple, ca-mcp-prod)

Étapes suivantes