Über MCP eine Verbindung zu einem Daten-Agenten herstellen

Als Administrator einer Drittanbieter-Plattform (z. B. Claude Code, Claude Cowork oder ChatGPT) oder einer von Google verwalteten agentischen Plattform (z. B. Gemini Enterprise) können Sie eine benutzerdefinierte Model Context Protocol (MCP)-Verbindung zum Remote-MCP-Server der konversationellen Analyse-API (https://geminidataanalytics.googleapis.com/mcp) konfigurieren. Wenn Sie Ihre agentische Plattform mit diesem Server verbinden, kann der Root-Agent Ihrer Plattform im Namen von geschäftlichen Nutzern spezialisierte Daten-Agenten finden und abfragen.

Der Remote-MCP-Server der konversationellen Analyse-API verwendet einen dreistufigen OAuth 2.0-Vorgang, um Endnutzer-Anmeldedaten an BigQuery weiterzugeben. Durch diese Weitergabe wird sichergestellt, dass Agent-Erkennungsanfragen und BigQuery-Abfragen unter der Identität des authentifizierten Nutzers ausgeführt werden und vorhandene IAM-Berechtigungen (Identity and Access Management) sowie Data-Governance-Richtlinien berücksichtigt werden. Looker-basierte Daten-Agenten erhalten keine Anmeldedaten von Endnutzern. Stattdessen sind für Abfragen separate Looker API-Client-Anmeldedaten erforderlich (siehe „Authentifizierung für Looker-basierte Daten-Agenten“).

Eine Übersicht über die Architektur, die zeigt, wie Root-Agenten (die primären Orchestrierungsagenten, die Nutzeranfragen empfangen) mit dem Remote-MCP-Server kommunizieren, finden Sie unter Remote-MCP-Server der konversationellen Analyse-API.

Hinweis

Bevor Sie die MCP-Verbindung in Ihrer agentischen Plattform konfigurieren, müssen die folgenden Voraussetzungen erfüllt sein:

  1. Aktivieren Sie in Ihrem Google Cloud Projekt die erforderlichen APIs für die konversationelle Analyse API und BigQuery.
  2. Achten Sie darauf, dass Datenoperatoren in Ihrem Google Cloud -Projekt einen oder mehrere Daten-Agents erstellt und konfiguriert haben, einschließlich klarer Beschreibungen der Datenquellen, auf die jeder Agent zugreifen kann, und der Fragen, die er beantworten kann.
  3. Prüfen Sie, ob geschäftliche Nutzer, die sich über die MCP-Verbindung authentifizieren, die erforderlichen IAM-Rollen und Lesezugriff auf die Ziel-Datasets sowie Zugriff auf den Agenten haben.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Authentifizieren über den Remote-MCP-Server und zum Abfragen von Daten-Agents benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

OAuth 2.0-Anmeldedaten und -Bereiche konfigurieren

Damit Ihre KI-Agentenplattform Nutzer authentifizieren und ihre Anmeldedaten an den Remote-MCP-Server der konversationellen Analyse-API weiterleiten kann, müssen Sie in Ihrem Google Cloud Projekt OAuth 2.0-Anmeldedaten (eine Client-ID und einen Clientschlüssel) erstellen.

Folgen Sie den Standardschritten unter OAuth 2.0 für den Zugriff auf Google APIs verwenden, um den OAuth-Zustimmungsbildschirm zu konfigurieren und eine OAuth 2.0-Client-ID auf der Seite „Anmeldedaten“ derGoogle Cloud Console zu erstellen. Wenden Sie beim Konfigurieren Ihrer Anmeldedaten die folgenden Einstellungen an, die für die MCP-Integration der konversationellen Analyse-API spezifisch sind:

  1. Zielgruppe: Wenn Ihre Organisation Google Workspace verwendet, wählen Sie Intern aus. Diese Auswahl beschränkt den Zugriff auf Nutzer innerhalb Ihrer Organisation, vermeidet die Notwendigkeit einer OAuth-App-Überprüfung für sensible Bereiche und sorgt dafür, dass Nutzer nicht durch die Richtlinien für die Zugriffssteuerung von Google Workspace-Apps an der Authentifizierung gehindert werden.
  2. Anwendungstyp und Weiterleitungs-URI: Wählen Sie Webanwendung als Anwendungstyp aus und fügen Sie die Autorisierte Weiterleitungs-URI hinzu, die von Ihrer agentischen Plattform benötigt wird (z. B. https://vertexaisearch.cloud.google.com/oauth-redirect, wenn Sie einen benutzerdefinierten MCP-Connector in Gemini Enterprise konfigurieren).
  3. OAuth-Bereiche: Konfigurieren Sie Ihren OAuth-Zustimmungsbildschirm und ‑Client so, dass beide der folgenden Bereiche angefordert werden, damit der Root-Agent die Berechtigung hat, konversationelle Analyse API-Tools aufzurufen und schreibgeschützte BigQuery-Abfragen im Namen des Nutzers auszuführen:
    • Gemini Data Analytics-Bereich: https://www.googleapis.com/auth/geminidataanalytics
    • BigQuery-Lesezugriffsbereich: https://www.googleapis.com/auth/bigquery.readonly
  4. Kopieren Sie die generierte Client-ID und den Clientschlüssel und speichern Sie sie an einem sicheren Ort.

Benutzerdefinierte MCP-Verbindung konfigurieren

Nachdem Sie Ihre OAuth 2.0-Client-ID und Ihren Clientschlüssel generiert haben, registrieren Sie eine benutzerdefinierte MCP-Verbindung (oder einen benutzerdefinierten MCP-Connector) in den Verwaltungseinstellungen Ihrer agentischen Plattform:

  1. Erstellen Sie in Ihrer agentischen Plattform eine neue benutzerdefinierte MCP-Serververbindung und geben Sie die folgenden Konfigurationswerte an:

    Einstellung Wert
    MCP-Server-URL https://geminidataanalytics.googleapis.com/mcp
    Authentifizierungsmethode oauth 2.0
    Autorisierungs-URL https://accounts.google.com/o/oauth2/v2/auth
    Autorisierungs-URL-Parameter

    &access_type=offline&prompt=consent

    Verwenden Sie diesen Parameterstring, wenn Ihre Plattform Offline-Aktualisierungstokens für Nutzersitzungen erfordert.
    Token-URL https://oauth2.googleapis.com/token
    Bereiche

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

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

    Wenn Ihre Plattform einen einzelnen String mit Leerzeichen erwartet, geben Sie Folgendes ein:

    https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly
    Client-ID CLIENT_ID (die OAuth 2.0-Client-ID, die Sie im vorherigen Abschnitt erstellt haben)
    Clientschlüssel CLIENT_SECRET (der OAuth 2.0-Clientschlüssel, den Sie im vorherigen Abschnitt erstellt haben)

  2. Bestätigen Sie die OAuth-Verbindung auf Ihrer Plattform, wenn Sie dazu aufgefordert werden. Wenn der Google-Zustimmungsbildschirm geöffnet wird, melden Sie sich an und bestätigen Sie, dass die Anwendung sowohl Lesezugriff auf Gemini Data Analytics als auch auf BigQuery anfordert.

  3. Synchronisieren Sie die Tools (Aktionen) für die MCP-Verbindung in Ihrer Plattform oder laden Sie sie neu, damit der MCP-Client tools/list auf https://geminidataanalytics.googleapis.com/mcp aufruft, um die Toolschemas (z. B. list_data_agents, get_data_agent und chat) zu importieren. Prüfen Sie, ob die importierten Tools aktiviert sind.

Prompt-Anweisungen für den Root-Agenten konfigurieren

Die MCP-Tools der konversationellen Analyse API (list_data_agents, get_data_agent und chat) erfordern eine Ziel-Projekt-ID von Google Cloud und einen Standort (z. B. projects/PROJECT_ID/locations/LOCATION). Da geschäftliche Nutzer in der Regel nicht wissen, welche Projekt-ID von Google Cloud die Daten-Agents Ihrer Organisation hostet, geben Sie die Ziel-Projekt-ID und den Standort in den benutzerdefinierten Systemanweisungen oder der Skill-Konfiguration Ihres Stamm-Agents an. Dadurch wird verhindert, dass der Root-Agent geschäftliche Nutzer auffordert, eine Projekt-ID anzugeben, wenn sie eine Datenfrage stellen.

Systemanweisungen für die Agenten-Erkennung und das Routing hinzufügen

Fügen Sie dem System-Prompt oder den benutzerdefinierten Anweisungen Ihres Root-Agenten die folgenden Anweisungen hinzu. Ersetzen Sie dabei PROJECT_ID durch Ihre Projekt-ID in Google Cloudund LOCATION durch Ihren Ressourcenstandort (z. B. global, us oder 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.

Authentifizierung für Looker-basierte Daten-Agents

Wenn Ihre KI-Datenagenten eine Verbindung zu Looker-Explores herstellen, müssen Anfragen an das chat-Tool einen credentials-Block mit Looker API-Anmeldedaten (Client-ID und Clientschlüssel) enthalten, da Looker die Authentifizierung unabhängig von IAM verwaltet.

Beachten Sie beim Konfigurieren Ihrer agentischen Plattform für Looker-basierte Daten-Agents die folgenden Best Practices:

  • Nutzer nicht nach Secrets fragen: Konfigurieren Sie den Root-Agenten so, dass er Endnutzer niemals auffordert, Looker API-Anmeldedaten im Chat einzufügen oder anzugeben.
  • Dediziertes Looker API-Nutzerkonto verwenden: Erstellen Sie einen dedizierten Looker API-Nutzer mit geringsten Berechtigungen, die nur für die Modelle und Explores gelten, die der KI-Datenagent benötigt.
  • Anmeldedaten außerhalb des Modellkontexts einfügen: Konfigurieren Sie Ihre Plattform, die MCP-Client-Middleware oder die Proxy-Ebene so, dass Looker API-Anmeldedaten auf der Transport- oder Toolausführungsebene in die chat-Anfragenutzlast eingefügt werden. Fügen Sie den Clientschlüssel nicht in die Prompt-Anweisungen oder den Unterhaltungsverlauf des Stamm-Agenten ein.

Muster für die Injektion von Anmeldedaten für agentische Plattformen

Damit Secrets nicht im Modellkontextfenster angezeigt werden, fügen Plattformen Looker-Anmeldedaten in der Regel mit einem der folgenden Ansätze ein:

  • MCP-Client-Middleware oder Proxy-Interception: Auf Plattformen, die Anfrage-Middleware, API-Gateways oder Tool-Interception-Hooks unterstützen, generiert der Root-Agent den Toolaufruf chat, der nur die semantischen Parameter (parent, dataAgentContext und messages) enthält. Die Middleware-Ebene fängt die ausgehende JSON-RPC-Anfrage ab, bevor sie https://geminidataanalytics.googleapis.com/mcp erreicht, liest die Anmeldedaten aus einem sicheren Secret-Speicher oder aus Umgebungsvariablen und füllt das Objekt credentials.
  • Verpackte Tooldefinitionen: In benutzerdefinierten Agenten-Frameworks (z. B. dem Agent Development Kit (ADK) oder benutzerdefinierten Python-Orchestratoren) stellen Sie dem Root-Agenten eine verpackte Version des chat-Tools zur Verfügung, bei der der Parameter credentials aus dem Toolschema weggelassen wird. Der Ausführungshandler des Wrappers hängt den credentials-Block programmatisch aus einer sicheren Konfiguration an, bevor er den Aufruf an den MCP-Server der konversationellen Analyse-API weiterleitet.

Das folgende Beispiel zeigt die vollständige JSON-RPC-Anfragenutzlast, die der MCP-Client für das chat-Tool an den Remote-MCP-Server sendet. Während das Modell die Parameter parent, dataAgentContext und messages generiert, füllt die Hostplattform oder die MCP-Client-Middleware das Objekt credentials, bevor die Anfrage gesendet wird:

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

Ersetzen Sie die Beispielwerte so:

  • PROJECT_ID: die ID Ihres Projekts in Google Cloud
  • LOCATION: der Standort Ihrer Conversational Analytics API-Ressourcen (z. B. global)
  • AGENT_ID: die ID Ihres Looker-basierten Daten-Agenten
  • LOOKER_CLIENT_ID: die Client-ID für Ihren Looker API-Nutzer
  • LOOKER_CLIENT_SECRET: der Clientschlüssel für Ihren Looker API-Nutzer
  • USER_QUESTION: der Prompt oder die Frage, die an den KI-Datenagenten gesendet werden soll.

Verbindung mit einem Test-Prompt prüfen

Nachdem Sie die benutzerdefinierte MCP-Verbindung mit Ihrer KI-Agenten-Anwendung verknüpft haben, öffnen Sie die Chat-Oberfläche Ihrer Plattform, autorisieren Sie Ihre Nutzersitzung, wenn Sie dazu aufgefordert werden, und senden Sie einen Test-Prompt, um zu bestätigen, dass der Root-Agent die MCP-Tools der konversationellen Analyse-API aufrufen und BigQuery mit Ihren delegierten Anmeldedaten abfragen kann.

Wenn Sie die Systemanweisungen im vorherigen Abschnitt konfiguriert haben, können Sie eine Frage direkt an Ihre Daten-Agents stellen oder eine Testabfrage für ein öffentliches BigQuery-Dataset ausführen. Geben Sie dazu das Projekt, den Standort und das Dataset in Ihrem Prompt an:

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

Sie können den Root-Agenten auch explizit anweisen, das Tool chat von Ihrem MCP-Connector (CONNECTOR_NAME) aufzurufen:

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.

Ersetzen Sie die Beispielwerte so:

  • PROJECT_ID: die ID desGoogle Cloud -Projekts, in dem Sie die konversationelle Analyse API aktiviert haben
  • LOCATION: der Standort Ihrer konversationellen Analyse API-Ressourcen (z. B. global)
  • CONNECTOR_NAME: Der Name, den Sie der benutzerdefinierten MCP-Verbindung in Ihrer agentischen Plattform zugewiesen haben (z. B. ca-mcp-prod).

Nächste Schritte