Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 MCP 连接到数据智能体

作为第三方（例如 Claude Code、Claude Cowork 或 ChatGPT）或 Google 管理的智能体平台（例如 Gemini Enterprise）的管理员，您可以配置与对话式分析 API 远程 MCP 服务器 (https://geminidataanalytics.googleapis.com/mcp) 的自定义模型上下文协议 (MCP) 连接。将智能体平台连接到此服务器后，平台的根智能体便可代表业务用户发现和查询专用数据智能体。

对话式分析 API 远程 MCP 服务器使用三方 OAuth 2.0 流程将最终用户凭证 (EUC) 传播到 BigQuery。这种传播可确保智能体发现请求和 BigQuery 查询在经过身份验证的用户身份下运行，并遵循现有的 Identity and Access Management (IAM) 权限和数据治理政策。Looker 支持的数据智能体不会收到最终用户凭证；相反，查询需要单独的 Looker API 客户端凭证（请参阅 Looker 支持的数据智能体的身份验证）。

如需简要了解根智能体（接收用户请求的主要编排智能体）如何与远程 MCP 服务器通信，请参阅对话式分析 API 远程 MCP 服务器。

准备工作

在智能体平台中配置 MCP 连接之前，请先完成以下前提条件：

在 Google Cloud 项目中，启用对话式分析 API 和 BigQuery 所需的 API。
确保数据操作员已在您的 Google Cloud 项目中创建并配置了一个或多个数据智能体，包括对每个智能体可以访问的数据源以及可以回答的问题的清晰说明。
验证将通过 MCP 连接进行身份验证的业务用户是否具有所需的 IAM 角色、对目标数据集的读取权限以及对智能体的访问权限。

所需的角色

如需获得通过远程 MCP 服务器进行身份验证和查询数据智能体所需的权限，请让您的管理员为您授予以下 IAM 角色：

与数据智能体 Chat：
- 针对您的项目的 Gemini 数据分析 Data Agent User (roles/geminidataanalytics.dataAgentUser)
- 针对项目的 Gemini for Google Cloud User (roles/cloudaicompanion.user)
运行 BigQuery 查询：结算项目的 BigQuery Job User (roles/bigquery.jobUser)
读取 BigQuery 数据：针对数据集或表的 BigQuery Data Viewer (roles/bigquery.dataViewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

配置 OAuth 2.0 凭证和范围

如需让智能体平台对用户进行身份验证并将其凭证转发到对话式分析 API 远程 MCP 服务器，您必须在 Google Cloud 项目中创建 OAuth 2.0 凭证（客户端 ID 和客户端密钥）。

按照使用 OAuth 2.0 访问 Google API 中的标准步骤配置 OAuth 权限请求页面，并在 Google Cloud 控制台“凭据”页面中创建 OAuth 2.0 客户端 ID。配置凭证时，请应用以下特定于对话式分析 API MCP 集成的设置：

受众群体：如果贵组织使用 Google Workspace，请选择内部。此选择会将访问权限限制为您组织内的用户，避免对敏感范围进行 OAuth 应用验证，并确保 Google Workspace 应用访问权限控制政策不会阻止用户进行身份验证。
应用类型和重定向 URI：选择 Web 应用作为应用类型，并添加智能体平台所需的已获授权的重定向 URI（例如，在 Gemini Enterprise 中配置自定义 MCP 连接器时，使用 https://vertexaisearch.cloud.google.com/oauth-redirect）。
OAuth 范围：配置 OAuth 权限请求页面和客户端，以请求以下两个范围，以便根智能体有权代表用户调用对话式分析 API 工具并运行只读 BigQuery 查询：
- Gemini 数据分析范围： https://www.googleapis.com/auth/geminidataanalytics
- BigQuery 只读范围： https://www.googleapis.com/auth/bigquery.readonly
复制并妥善存储生成的客户端 ID 和客户端密钥。

配置自定义 MCP 连接

生成 OAuth 2.0 客户端 ID 和客户端密钥后，在智能体平台的管理设置中注册自定义 MCP 连接（或自定义 MCP 连接器）：

在智能体平台中，创建一个新的自定义 MCP 服务器连接，并指定以下配置值：

设置	值
MCP 服务器网址	`https://geminidataanalytics.googleapis.com/mcp`
身份验证方法	OAuth 2.0
授权网址	`https://accounts.google.com/o/oauth2/v2/auth`
授权网址参数	`&access_type=offline&prompt=consent` 如果您的平台需要为用户会话提供离线刷新令牌，请使用此参数字符串。
令牌网址	`https://oauth2.googleapis.com/token`
镜	`https://www.googleapis.com/auth/geminidataanalytics` `https://www.googleapis.com/auth/bigquery.readonly` 如果您的平台需要一个以空格分隔的字符串，请输入： `https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly`
客户端 ID (Client ID)	`CLIENT_ID`（您在上一部分中创建的 OAuth 2.0 客户端 ID）
客户端密钥 (Client Secret)	`CLIENT_SECRET`（您在上一部分中创建的 OAuth 2.0 客户端密钥）

如果系统提示，请在您的平台中验证 OAuth 连接。当 Google 权限请求页面打开时，请登录并确认应用请求了 Gemini 数据分析和 BigQuery 只读权限。
在您的平台中同步或重新加载 MCP 连接的工具（操作），以便 MCP 客户端在 https://geminidataanalytics.googleapis.com/mcp 上调用 tools/list 来导入工具架构（例如 list_data_agents、get_data_agent 和 chat），并验证导入的工具是否已启用。

为根智能体配置提示指令

对话式分析 API MCP 工具（list_data_agents、get_data_agent和chat）需要目标 Google Cloud 项目 ID 和位置（例如projects/PROJECT_ID/locations/LOCATION）。由于业务用户通常不知道哪个 Google Cloud 项目 ID 托管了贵组织的数据智能体，因此请在根智能体的自定义系统指令或 skill 配置中提供目标项目 ID 和位置。这样可以防止根代理在业务用户提出数据问题时提示他们提供项目 ID。

添加系统指令，以便发现和路由智能体

将以下指令添加到根智能体的系统提示或自定义指令中，并将 PROJECT_ID 替换为您的 Google Cloud项目 ID，将 LOCATION 替换为您的资源位置（例如 global、us 或 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.

Looker 支持的数据智能体的身份验证

如果您的数据智能体连接到 Looker 探索，则对 chat 工具的请求必须包含一个 credentials 块，其中包含 Looker API 凭据（客户端 ID 和客户端密钥），因为 Looker 独立于 IAM 管理身份验证。

为 Looker 支持的数据智能体配置智能体平台时，请遵循以下最佳实践：

不提示用户提供机密信息：将根智能体配置为绝不要求最终用户在对话中粘贴或提供 Looker API 凭证。
使用专用的 Looker API 用户账号：创建一个专用的 Looker API 用户，并为其分配最小权限，这些权限仅限于数据智能体所需的模型和探索。
在模型上下文之外注入凭据：配置您的平台、MCP 客户端中间件或代理层，以便在传输层或工具执行层将 Looker API 凭据注入 chat 请求载荷。请勿将客户端密钥放在根智能体的提示指令或对话记录中。

注意：请勿在系统提示指令或对话上下文中传递 clientSecret 字段。在提示文本中公开凭据会将其直接置于模型的上下文窗口中，从而增加通过对话日志、提示注入或生成的模型输出泄露机密的风险。请尽可能配置您的智能体平台或 MCP 客户端中间件，以便在模型上下文之外自动将 credentials 块注入工具调用载荷。如果您的平台要求直接在提示中配置凭证，请使用具有严格限定范围的只读权限的专用 Looker API 用户账号，并定期轮替客户端密钥。

智能体平台的凭证注入模式

为了使 Secret 不会出现在模型上下文窗口中，平台通常会使用以下方法之一注入 Looker 凭据：

MCP 客户端中间件或代理拦截：在支持请求中间件、API Gateway 或工具拦截钩子的平台中，根智能体生成仅包含语义参数（parent、dataAgentContext 和 messages）的 chat 工具调用。中间件层在传出 JSON-RPC 请求到达 https://geminidataanalytics.googleapis.com/mcp 之前对其进行拦截，从安全 Secret 存储区或环境变量中读取凭据，并填充 credentials 对象。
封装的工具定义：在自定义智能体框架（例如智能体开发套件 [ADK] 或自定义 Python 编排器）中，向根智能体公开 chat 工具的封装版本，该版本会从工具架构中省略 credentials 参数。封装容器的执行处理程序会先以编程方式从安全配置中附加 credentials 代码块，然后再将调用转发到对话式分析 API MCP 服务器。

以下示例展示了 MCP 客户端针对 chat 工具向远程 MCP 服务器发送的完整 JSON-RPC 请求载荷。虽然模型会生成 parent、dataAgentContext 和 messages 参数，但宿主平台或 MCP 客户端中间件会在分派请求之前填充 credentials 对象：

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

按如下所示替换示例值：

PROJECT_ID：您的 Google Cloud 项目的 ID
LOCATION：对话式分析 API 资源的位置（例如 global）
AGENT_ID：Looker 支持的数据智能体的 ID
LOOKER_CLIENT_ID：Looker API 用户的客户端 ID
LOOKER_CLIENT_SECRET：Looker API 用户的客户端密钥
USER_QUESTION：要发送给数据智能体的提示或问题

使用测试提示验证连接

将自定义 MCP 连接关联到代理应用后，打开平台的对话界面，在系统提示时授权用户会话，然后发送测试提示，以确认根智能体可以调用对话式分析 API MCP 工具，并使用您的委托凭证查询 BigQuery。

如果您在上一部分中配置了系统指令，则可以直接向数据智能体提问，也可以在提示中指定项目、位置和数据集，针对 BigQuery 公共数据集运行测试查询：

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

您还可以明确指示根智能体从 MCP 连接器 (CONNECTOR_NAME) 调用 chat 工具：

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.