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)](https://modelcontextprotocol.io/) 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](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/integration-patterns#ca-mcp-server).

> [!NOTE]
> **Note:** Data agents that you create within the Looker UI or through the Looker API aren't accessible through the Conversational Analytics API remote MCP server. To query Looker data through this MCP server, you must create a data agent by using the [Conversational Analytics API with a
> Looker data
> source](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/connect-looker). When querying Looker-backed data agents through the `chat` MCP tool, the request must include your Looker API credentials in the `credentials` object. The [Looker-managed MCP server](https://docs.cloud.google.com/looker/docs/mcp.md.txt) provides tools to query Looker models directly, but it doesn't surface data agents.

## Before you begin

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

1. In your Google Cloud project, [enable the required APIs](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/enable-the-api.md.txt) for the Conversational Analytics API and BigQuery.
2. Ensure that data operators have [created and configured one or more data
   agents](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-http) in your Google Cloud project, including clear descriptions of the data sources that each agent can access and the questions that it can answer.
3. Verify that business users who will authenticate through the MCP connection have the [required IAM roles](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/connect-mcp.md.txt#required-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](https://docs.cloud.google.com/iam/docs/roles-permissions/geminidataanalytics.md.txt#geminidataanalytics.dataAgentUser) (`roles/geminidataanalytics.dataAgentUser`) on your project
  - [Gemini for Google Cloud User](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudaicompanion.md.txt#cloudaicompanion.user) (`roles/cloudaicompanion.user`) on your project
- Run BigQuery queries: [BigQuery Job User](https://docs.cloud.google.com/iam/docs/roles-permissions/bigquery.md.txt#bigquery.jobUser) (`roles/bigquery.jobUser`) on your billing project
- Read BigQuery data: [BigQuery Data Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/bigquery.md.txt#bigquery.dataViewer) (`roles/bigquery.dataViewer`) on your dataset or table


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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](https://developers.google.com/identity/protocols/oauth2) to [configure
your OAuth consent
screen](https://developers.google.com/identity/protocols/oauth2/web-server#configuring_the_oauth_consent_screen)
and create an OAuth 2.0 client ID in the [Google Cloud console Credentials
page](https://console.cloud.google.com/apis/credentials). When configuring your credentials,
apply the following settings that are specific to the Conversational Analytics API MCP
integration:

1. **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.
2. **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](https://docs.cloud.google.com/gemini/enterprise/docs/connectors/custom-mcp-server/set-up-custom-mcp-server.md.txt) in Gemini Enterprise).
3. **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`
4. 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:

1. 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** | <var translate="no">CLIENT_ID</var> (the OAuth 2.0 client ID that you created in the previous section) |
   | **Client Secret** | <var translate="no">CLIENT_SECRET</var> (the OAuth 2.0 client secret that you created in the previous section) |

2. 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.

3. 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 <var translate="no">PROJECT_ID</var> with your Google Cloud
project ID and <var translate="no">LOCATION</var> 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]
> **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:

```json
{
  "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:

- <var class="readonly" translate="no">PROJECT_ID</var>: the ID of your Google Cloud project
- <var class="readonly" translate="no">LOCATION</var>: the location of your Conversational Analytics API resources (for example, `global`)
- <var class="readonly" translate="no">AGENT_ID</var>: the ID of your Looker-backed data agent
- <var class="readonly" translate="no">LOOKER_CLIENT_ID</var>: the client ID for your Looker API user
- <var class="readonly" translate="no">LOOKER_CLIENT_SECRET</var>: the client secret for your Looker API user
- <var class="readonly" translate="no">USER_QUESTION</var>: 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 (<var translate="no">CONNECTOR_NAME</var>):

    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.

Replace the sample values as follows:

- <var class="readonly" translate="no">PROJECT_ID</var>: the ID of the Google Cloud project where you enabled the Conversational Analytics API
- <var class="readonly" translate="no">LOCATION</var>: the location of your Conversational Analytics API resources (for example, `global`)
- <var class="readonly" translate="no">CONNECTOR_NAME</var>: the name that you assigned to the custom MCP connection in your agentic platform (for example, `ca-mcp-prod`)

## What's next

- Learn more about [Conversational Analytics API remote MCP server architecture and
  tool
  mappings](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/integration-patterns#ca-mcp-server).
- Learn how to [build and configure a data agent using HTTP](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-http.md.txt) or [using the Python
  SDK](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-sdk).
- Learn how to [guide agent behavior with authored
  context](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/data-agent-system-instructions).
- Troubleshoot common issues in [Troubleshoot Conversational Analytics API
  errors](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/troubleshoot-ca-errors).