Como administrador de una plataforma agéntica de terceros (como Claude Code, Claude Cowork o
ChatGPT) o administrada por Google (como
Gemini Enterprise), puedes configurar una conexión personalizada del Protocolo de contexto del modelo
(MCP) al servidor de MCP remoto de la API de Conversational Analytics (https://geminidataanalytics.googleapis.com/mcp). Conectar tu
plataforma agéntica a este servidor permite que el agente raíz de tu plataforma descubra y
consulte agentes de datos especializados en nombre de los usuarios empresariales.
El servidor de MCP remoto de la API de Conversational Analytics usa un flujo de OAuth 2.0 de 3 niveles para propagar las credenciales de usuario final (EUC) a BigQuery. Esta propagación garantiza que las solicitudes de descubrimiento de agentes y las consultas de BigQuery se ejecuten con la identidad del usuario autenticado y respeten los permisos de Identity and Access Management (IAM) y las políticas de administración de datos existentes. Los agentes de datos respaldados por Looker no reciben credenciales de usuario final. En cambio, las consultas requieren credenciales de cliente de la API de Looker independientes (consulta Autenticación para agentes de datos respaldados por Looker).
Para obtener una descripción general de la arquitectura de cómo los agentes raíz (el agente de organización principal que recibe las solicitudes de los usuarios) se comunican con el servidor de MCP remoto, consulta Servidor de MCP remoto de la API de Conversational Analytics.
Antes de comenzar
Antes de configurar la conexión de MCP en tu plataforma de agentes, completa los siguientes requisitos previos:
- En tu proyecto de Google Cloud , habilita las APIs necesarias para la API de Conversational Analytics y BigQuery.
- Asegúrate de que los operadores de datos hayan creado y configurado uno o más agentes de datos en tu proyecto de Google Cloud , incluidas descripciones claras de las fuentes de datos a las que puede acceder cada agente y las preguntas que puede responder.
- Verifica que los usuarios empresariales que se autenticarán a través de la conexión de MCP tengan los roles de IAM necesarios y acceso de lectura a los conjuntos de datos de destino y acceso al agente.
Roles obligatorios
Para obtener los permisos que necesitas para autenticarte a través del servidor de MCP remoto y consultar los agentes de datos, pídele a tu administrador que te otorgue los siguientes roles de IAM:
-
Agentes de chat con datos:
- Usuario del agente de datos de Gemini Data Analytics (
roles/geminidataanalytics.dataAgentUser) en tu proyecto - Usuario de Gemini para Google Cloud (
roles/cloudaicompanion.user) en tu proyecto
- Usuario del agente de datos de Gemini Data Analytics (
-
Ejecuta consultas de BigQuery:
Usuario de trabajo de BigQuery (
roles/bigquery.jobUser) en tu proyecto de facturación -
Lee datos de BigQuery:
Visualizador de datos de BigQuery (
roles/bigquery.dataViewer) en tu conjunto de datos o tabla
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
Configura las credenciales y los permisos de OAuth 2.0
Para permitir que tu plataforma de agentes autentique a los usuarios y reenvíe sus credenciales al servidor de MCP remoto de la API de Conversational Analytics, debes crear credenciales de OAuth 2.0 (un ID de cliente y un secreto del cliente) en tu proyecto de Google Cloud .
Sigue los pasos estándar que se indican en Usa OAuth 2.0 para acceder a las APIs de Google para configurar tu pantalla de consentimiento de OAuth y crear un ID de cliente de OAuth 2.0 en la página Credenciales de la consola deGoogle Cloud . Cuando configures tus credenciales, aplica los siguientes parámetros de configuración específicos de la integración de MCP de la API de Conversational Analytics:
- Público: Si tu organización usa Google Workspace, selecciona Interno. Esta selección restringe el acceso a los usuarios de tu organización, evita la necesidad de verificar la app de OAuth para los permisos sensibles y garantiza que las políticas de control de acceso a las apps de Google Workspace no bloqueen la autenticación de los usuarios.
- Tipo de aplicación y URI de redireccionamiento: Selecciona Aplicación web como el
tipo de aplicación y agrega el URI de redireccionamiento autorizado que requiere tu
plataforma de agentes (por ejemplo,
https://vertexaisearch.cloud.google.com/oauth-redirectcuando configuras un conector de MCP personalizado en Gemini Enterprise). - Permisos de OAuth: Configura la pantalla de consentimiento de OAuth y el cliente para solicitar
los siguientes permisos, de modo que el agente raíz tenga permiso para llamar
a las herramientas de la API de Conversational Analytics y ejecutar consultas de BigQuery de solo lectura
en nombre del usuario:
- Permiso de Gemini Data Analytics:
https://www.googleapis.com/auth/geminidataanalytics - Permiso de solo lectura de BigQuery:
https://www.googleapis.com/auth/bigquery.readonly
- Permiso de Gemini Data Analytics:
- Copia y almacena de forma segura el ID de cliente y el secreto del cliente generados.
Configura la conexión de MCP personalizada
Después de generar el ID de cliente y el secreto del cliente de OAuth 2.0, registra una conexión de MCP personalizada (o un conector de MCP personalizado) en la configuración de administración de tu plataforma de agentes:
En tu plataforma de agentes, crea una nueva conexión de servidor de MCP personalizada y especifica los siguientes valores de configuración:
Configuración Valor URL del servidor de MCP https://geminidataanalytics.googleapis.com/mcpMétodo de autenticación OAuth 2.0 URL de autorización https://accounts.google.com/o/oauth2/v2/authParámetros de URL de autorización &access_type=offline&prompt=consentUsa esta cadena de parámetro si tu plataforma requiere tokens de actualización sin conexión para las sesiones de usuario.
URL del token https://oauth2.googleapis.com/tokenPermisos https://www.googleapis.com/auth/geminidataanalyticshttps://www.googleapis.com/auth/bigquery.readonlySi tu plataforma espera una sola cadena separada por espacios, ingresa lo siguiente:
https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonlyClient ID (ID de cliente) CLIENT_ID (el ID de cliente de OAuth 2.0 que creaste en la sección anterior) Client Secret (Secreto del cliente) CLIENT_SECRET (el secreto del cliente de OAuth 2.0 que creaste en la sección anterior) Verifica la conexión de OAuth en tu plataforma si se te solicita. Cuando se abra la pantalla de consentimiento de Google, accede y confirma que la aplicación solicite acceso de solo lectura a Gemini Data Analytics y BigQuery.
Sincroniza o vuelve a cargar las herramientas (acciones) para la conexión de MCP en tu plataforma para que el cliente de MCP llame a
tools/listenhttps://geminidataanalytics.googleapis.com/mcppara importar los esquemas de herramientas (comolist_data_agents,get_data_agentychat) y verificar que las herramientas importadas estén habilitadas.
Configura las instrucciones de la instrucción para el agente raíz
Las herramientas de MCP de la API de Conversational Analytics (list_data_agents, get_data_agent
y chat) requieren un ID del proyecto y una ubicación de Google Cloud de destino
(por ejemplo,
projects/PROJECT_ID/locations/LOCATION).
Como los usuarios empresariales no suelen saber qué ID del proyecto de Google Cloud aloja
los agentes de datos de tu organización, proporciona el ID del proyecto y la ubicación de destino
en las instrucciones del sistema personalizadas o la configuración de habilidades de tu agente raíz.
Esto evita que el agente raíz solicite a los usuarios empresariales que proporcionen un ID del proyecto
cuando hagan una pregunta sobre los datos.
Agrega instrucciones del sistema para el descubrimiento y el enrutamiento de agentes
Agrega las siguientes instrucciones al mensaje del sistema o a las instrucciones personalizadas de tu agente raíz, reemplazando PROJECT_ID por el ID del proyecto de Google Cloudy LOCATION por la ubicación de tu recurso (como 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.
4. If the user asks about a specific BigQuery table that isn't connected to any
of the available data agents, call the chat tool and pass the table directly
as inline context instead of using a data agent. Pass parent
("projects/PROJECT_ID/locations/LOCATION"),
inlineContext with a datasourceReferences.bq.tableReferences entry for the
table (projectId, datasetId, and tableId), and the user's question in
messages.
Autenticación para agentes de datos respaldados por Looker
Si tus agentes de datos se conectan a las exploraciones de Looker, las solicitudes a la
herramienta chat deben incluir un bloque credentials que contenga las credenciales de la API de Looker (un ID de cliente y un secreto del cliente), ya que Looker administra
la autenticación de forma independiente de IAM.
Cuando configures tu plataforma de agentes para agentes de datos respaldados por Looker, aplica las siguientes prácticas recomendadas:
- No solicites secretos a los usuarios: Configura el agente raíz para que nunca les pida a los usuarios finales que peguen o proporcionen credenciales de la API de Looker en el chat.
- Usa una cuenta de usuario de la API de Looker dedicada: Crea un usuario de la API de Looker dedicado con permisos de privilegio mínimo que tengan alcance solo para los modelos y las exploraciones que necesita el agente de datos.
- Inyecta credenciales fuera del contexto del modelo: Configura tu plataforma, el middleware del cliente de MCP o la capa de proxy para insertar credenciales de la API de Looker en la carga útil de la solicitud de
chaten la capa de transporte o de ejecución de herramientas. No coloques el secreto del cliente en las instrucciones de la instrucción del agente raíz ni en el historial de conversaciones.
Patrones de inserción de credenciales para plataformas de agentes
Para mantener los secretos fuera de la ventana de contexto del modelo, las plataformas suelen insertar credenciales de Looker con uno de los siguientes enfoques:
- Intercepción de proxy o middleware del cliente de MCP: En las plataformas que admiten middleware de solicitudes, API Gateways o hooks de intercepción de herramientas, el agente raíz genera la llamada a la herramienta
chatque contiene solo los parámetros semánticos (parent,dataAgentContextymessages). La capa de middleware intercepta la solicitud JSON-RPC saliente antes de que llegue ahttps://geminidataanalytics.googleapis.com/mcp, lee las credenciales de un almacén de secretos seguro o de variables de entorno, y propaga el objetocredentials. - Definiciones de herramientas encapsuladas: En los frameworks de agentes personalizados (como el Kit de desarrollo de agentes [ADK] o los organizadores de Python personalizados), expón una versión encapsulada de la herramienta
chatal agente raíz que omita el parámetrocredentialsdel esquema de la herramienta. El controlador de ejecución del wrapper adjunta el bloquecredentialsde forma programática desde una configuración segura antes de reenviar la llamada al servidor de MCP de la API de Conversational Analytics.
En el siguiente ejemplo, se muestra la carga útil completa de la solicitud JSON-RPC que el cliente de MCP envía al servidor de MCP remoto para la herramienta chat. Mientras el modelo genera los parámetros parent, dataAgentContext y messages, la plataforma host o el middleware del cliente de MCP completan el objeto credentials antes de enviar la solicitud:
{
"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"
}
}
]
}
Reemplaza los valores de muestra de la siguiente manera:
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
- LOCATION: Es la ubicación de tus recursos de la API de Conversational Analytics (por ejemplo,
global). - AGENT_ID: el ID de tu agente de datos respaldado por Looker
- LOOKER_CLIENT_ID: Es el ID de cliente de tu usuario de la API de Looker.
- LOOKER_CLIENT_SECRET: Es el secreto del cliente para tu usuario de la API de Looker.
- USER_QUESTION: Es la instrucción o pregunta que se enviará al agente de datos.
Verifica la conexión con una instrucción de prueba
Después de vincular la conexión de MCP personalizada a tu aplicación de agente, abre la interfaz de chat de tu plataforma, autoriza tu sesión de usuario cuando se te solicite y envía una instrucción de prueba para confirmar que el agente raíz puede invocar las herramientas de MCP de la API de Conversational Analytics y consultar BigQuery con tus credenciales delegadas.
Si configuraste las instrucciones del sistema en la sección anterior, puedes hacer una pregunta directamente a tus agentes de datos o ejecutar una consulta de prueba en un conjunto de datos públicos de BigQuery especificando el proyecto, la ubicación y el conjunto de datos en tu instrucción:
What are the top 5 selling products in projects/PROJECT_ID/locations/LOCATION using the public dataset bigquery-public-data.iowa_liquor_sales.sales?
También puedes indicarle de forma explícita al agente raíz que llame a la herramienta chat desde
tu conector de 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.
Reemplaza los valores de muestra de la siguiente manera:
- PROJECT_ID: Es el ID del proyecto deGoogle Cloud en el que habilitaste la API de Conversational Analytics.
- LOCATION: Es la ubicación de tus
recursos de la API de Conversational Analytics (por ejemplo,
global). - CONNECTOR_NAME: Es el nombre que
asignaste a la conexión de MCP personalizada en tu plataforma de agentes (por ejemplo,
ca-mcp-prod).
¿Qué sigue?
- Obtén más información sobre la arquitectura del servidor de MCP remoto de la API de Conversational Analytics y las asignaciones de herramientas.
- Aprende a compilar y configurar un agente de datos con HTTP o con el SDK de Python.
- Obtén información para guiar el comportamiento de los agentes con contexto creado.
- Soluciona problemas habituales en Soluciona errores de la API de Conversational Analytics.