Connect to a data agent using MCP

As an administrator of a third-party (such as Claude Code, Claude Cowork, or ChatGPT) or Google-managed agentic platform (such as Gemini Enterprise), you can configure a custom Model Context Protocol (MCP) connection to the Conversational Analytics API remote MCP server (https://geminidataanalytics.googleapis.com/mcp). Connecting your agentic platform to this server lets your platform's root agent discover and query specialized data agents on behalf of business users.

The Conversational Analytics API remote MCP server uses a 3-legged OAuth 2.0 flow to propagate end-user credentials (EUC) to BigQuery. This propagation ensures that agent discovery requests and BigQuery queries run under the authenticated user's identity and respect existing Identity and Access Management (IAM) permissions and data governance policies. Looker-backed data agents don't receive end-user credentials; instead, queries require separate Looker API client credentials (see Authentication for Looker-backed data agents).

For an architectural overview of how root agents — the primary orchestrating agent that receives user requests — communicate with the remote MCP server, see Conversational Analytics API remote MCP server.

Before you begin

Before you configure the MCP connection in your agentic platform, complete the following prerequisites:

In your Google Cloud project, enable the required APIs for the Conversational Analytics API and BigQuery.
Ensure that data operators have created and configured one or more data agents in your Google Cloud project, including clear descriptions of the data sources that each agent can access and the questions that it can answer.
Verify that business users who will authenticate through the MCP connection have the required IAM roles and read access to the target datasets and access to the agent.

Required roles

To get the permissions that you need to authenticate through the remote MCP server and query data agents, ask your administrator to grant you the following IAM roles:

Chat with data agents:
- Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser) on your project
- Gemini for Google Cloud User (roles/cloudaicompanion.user) on your project
Run BigQuery queries: BigQuery Job User (roles/bigquery.jobUser) on your billing project
Read BigQuery data: BigQuery Data Viewer (roles/bigquery.dataViewer) on your dataset or table

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Configure OAuth 2.0 credentials and scopes

To let your agentic platform authenticate users and forward their credentials to the Conversational Analytics API remote MCP server, you must create OAuth 2.0 credentials (a client ID and client secret) in your Google Cloud project.

Follow the standard steps in Using OAuth 2.0 to Access Google APIs to configure your OAuth consent screen and create an OAuth 2.0 client ID in the Google Cloud console Credentials page. When configuring your credentials, apply the following settings that are specific to the Conversational Analytics API MCP integration:

Audience: If your organization uses Google Workspace, select Internal. This selection restricts access to users within your organization, avoids the need for OAuth app verification for sensitive scopes, and ensures that Google Workspace App Access Control policies don't block users from authenticating.
Application type and redirect URI: Select Web application as the application type, and add the Authorized redirect URI required by your agentic platform (for example, https://vertexaisearch.cloud.google.com/oauth-redirect when configuring a custom MCP connector in Gemini Enterprise).
OAuth scopes: Configure your OAuth consent screen and client to request both of the following scopes so that the root agent has permission to call Conversational Analytics API tools and run read-only BigQuery queries on behalf of the user:
- Gemini Data Analytics scope: https://www.googleapis.com/auth/geminidataanalytics
- BigQuery read-only scope: https://www.googleapis.com/auth/bigquery.readonly
Copy and securely store the generated Client ID and Client Secret.

Configure the custom MCP connection

After you generate your OAuth 2.0 client ID and client secret, register a custom MCP connection (or custom MCP connector) in your agentic platform's administration settings:

In your agentic platform, create a new custom MCP server connection and specify the following configuration values:

Setting	Value
MCP server URL	`https://geminidataanalytics.googleapis.com/mcp`
Authentication method	OAuth 2.0
Authorization URL	`https://accounts.google.com/o/oauth2/v2/auth`
Authorization URL parameters	`&access_type=offline&prompt=consent` Use this parameter string if your platform requires offline refresh tokens for user sessions.
Token URL	`https://oauth2.googleapis.com/token`
Scopes	`https://www.googleapis.com/auth/geminidataanalytics` `https://www.googleapis.com/auth/bigquery.readonly` If your platform expects a single space-separated string, enter: `https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly`
Client ID	`CLIENT_ID` (the OAuth 2.0 client ID that you created in the previous section)
Client Secret	`CLIENT_SECRET` (the OAuth 2.0 client secret that you created in the previous section)

Verify the OAuth connection in your platform if prompted. When the Google consent screen opens, sign in and confirm that the application requests both Gemini Data Analytics and BigQuery read-only access.
Sync or reload the tools (actions) for the MCP connection in your platform so that the MCP client calls tools/list on https://geminidataanalytics.googleapis.com/mcp to import the tool schemas (such as list_data_agents, get_data_agent, and chat), and verify that the imported tools are enabled.

Configure prompt instructions for the root agent

The Conversational Analytics API MCP tools — list_data_agents, get_data_agent, and chat—require a target Google Cloud project ID and location (for example, projects/PROJECT_ID/locations/LOCATION). Because business users typically don't know which Google Cloud project ID hosts your organization's data agents, provide the target project ID and location in your root agent's custom system instructions or skill configuration. This prevents the root agent from prompting business users to supply a project ID when they ask a data question.

Add system instructions for agent discovery and routing

Add the following instructions to your root agent's system prompt or custom instructions, replacing PROJECT_ID with your Google Cloud project ID and LOCATION with your resource location (such as global, us, or 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.

Authentication for Looker-backed data agents

If your data agents connect to Looker Explores, requests to the chat tool must include a credentials block containing Looker API credentials (a client ID and client secret), because Looker manages authentication independently of IAM.

When configuring your agentic platform for Looker-backed data agents, apply the following best practices:

Do not prompt users for secrets: Configure the root agent never to ask end users to paste or provide Looker API credentials in chat.
Use a dedicated Looker API user account: Create a dedicated Looker API user with least-privilege permissions that are scoped only to the models and Explores that the data agent needs.
Inject credentials outside the model context: Configure your platform, MCP client middleware, or proxy layer to inject Looker API credentials into the chat request payload at the transport or tool-execution layer. Do not place the client secret in the root agent's prompt instructions or conversation history.

Caution: Do not pass the clientSecret field in system prompt instructions or conversational context. Exposing credentials in prompt text places them directly in the model's context window, increasing the risk of secret leakage through conversation logs, prompt injection, or generated model outputs. Whenever possible, configure your agentic platform or MCP client middleware to inject the credentials block into the tool call payload automatically outside the model context. If your platform requires configuring credentials directly in prompts, use a dedicated Looker API user account with strictly scoped, read-only permissions, and rotate the client secret regularly.

Credential injection patterns for agentic platforms

To keep secrets out of the model context window, platforms typically inject Looker credentials by using one of the following approaches:

MCP client middleware or proxy interception: In platforms that support request middleware, API gateways, or tool-interception hooks, the root agent generates the chat tool call containing only the semantic parameters (parent, dataAgentContext, and messages). The middleware layer intercepts the outgoing JSON-RPC request before it reaches https://geminidataanalytics.googleapis.com/mcp, reads the credentials from a secure secret store or environment variables, and populates the credentials object.
Wrapped tool definitions: In custom agent frameworks (such as the Agent Development Kit (ADK) or custom Python orchestrators), expose a wrapped version of the chat tool to the root agent that omits the credentials parameter from the tool schema. The wrapper's execution handler attaches the credentials block programmatically from a secure configuration before forwarding the call to the Conversational Analytics API MCP server.

The following example shows the complete JSON-RPC request payload that the MCP client sends to the remote MCP server for the chat tool. While the model generates the parent, dataAgentContext, and messages parameters, the host platform or MCP client middleware populates the credentials object before dispatching the request:

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

Replace the sample values as follows:

PROJECT_ID: the ID of your Google Cloud project
LOCATION: the location of your Conversational Analytics API resources (for example, global)
AGENT_ID: the ID of your Looker-backed data agent
LOOKER_CLIENT_ID: the client ID for your Looker API user
LOOKER_CLIENT_SECRET: the client secret for your Looker API user
USER_QUESTION: the prompt or question to send to the data agent

Verify the connection with a test prompt

After you link the custom MCP connection to your agent application, open your platform's chat interface, authorize your user session when prompted, and send a test prompt to confirm that the root agent can invoke the Conversational Analytics API MCP tools and query BigQuery using your delegated credentials.

If you configured the system instructions in the previous section, you can ask a question directly against your data agents, or run a test query against a BigQuery public dataset by specifying the project, location, and dataset in your 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?

You can also explicitly instruct the root agent to call the chat tool from your MCP connector (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.