如果您是第三方 (例如 Claude Code、Claude Cowork 或 ChatGPT) 或 Google 代管代理功能平台 (例如 Gemini Enterprise) 的管理員,可以設定自訂Model Context Protocol (MCP) 連線,連至對話式數據分析 API 遠端 MCP 伺服器 (https://geminidataanalytics.googleapis.com/mcp)。將代理功能平台連至這個伺服器後,平台的根代理就能代表商業使用者,探索及查詢專門的資料代理。
對話式數據分析 API 遠端 MCP 伺服器會使用 3-legged OAuth 2.0 流程,將使用者憑證 (EUC) 傳播至 BigQuery。這項傳播機制可確保代理探索要求和 BigQuery 查詢,會以經過驗證的使用者身分執行,並遵循現有的 Identity and Access Management (IAM) 權限和資料治理政策。Looker 支援的資料代理不會收到使用者憑證,而是需要個別的 Looker API 用戶端憑證才能執行查詢 (請參閱「Looker 支援的資料代理驗證」)。
如要瞭解根代理 (接收使用者要求的主要協調代理) 如何與遠端 MCP 伺服器通訊,請參閱「對話式數據分析 API 遠端 MCP 伺服器」一節。
事前準備
在代理平台設定 MCP 連線前,請先完成下列必要條件:
- 在 Google Cloud 專案中,啟用 Conversational Analytics API 和 BigQuery 的必要 API。
- 請確保資料操作人員已在 Google Cloud 專案中建立並設定一或多個資料代理,包括清楚說明各代理可存取的資料來源,以及可回答的問題。
- 確認要透過 MCP 連線驗證的企業使用者具備必要 IAM 角色、目標資料集的讀取權限,以及代理的存取權。
必要的角色
如要取得透過遠端 MCP 伺服器驗證及查詢資料代理所需的權限,請要求管理員授予您下列 IAM 角色:
-
與資料代理對話:
- 專案的 Gemini 資料分析資料代理使用者 (
roles/geminidataanalytics.dataAgentUser) - 專案的 Gemini for Google Cloud 使用者 (
roles/cloudaicompanion.user)
- 專案的 Gemini 資料分析資料代理使用者 (
-
執行 BigQuery 查詢:帳單專案的 BigQuery 工作使用者 (
roles/bigquery.jobUser) -
讀取 BigQuery 資料:資料集或資料表的 BigQuery 資料檢視者 (
roles/bigquery.dataViewer)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
設定 OAuth 2.0 憑證和範圍
如要讓代理平台驗證使用者,並將其憑證轉送至對話式數據分析 API 遠端 MCP 伺服器,您必須在 Google Cloud 專案中建立 OAuth 2.0 憑證 (用戶端 ID 和用戶端密鑰)。
請按照「使用 OAuth 2.0 存取 Google API」中的標準步驟,設定 OAuth 同意畫面,並在Google Cloud 控制台的「Credentials」(憑證) 頁面中建立 OAuth 2.0 用戶端 ID。設定憑證時,請套用下列 Conversational Analytics API MCP 整合專用設定:
- 目標對象:如果貴組織使用 Google Workspace,請選取「內部」。這項設定會限制只有貴組織內的使用者可以存取,避免需要對敏感範圍進行 OAuth 應用程式驗證,並確保 Google Workspace 應用程式存取控管政策不會阻擋使用者進行驗證。
- 應用程式類型和重新導向 URI:選取「網頁應用程式」做為應用程式類型,並新增代理平台所需的授權重新導向 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
- Gemini 資料分析範圍:
- 複製並妥善保存系統產生的用戶端 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/geminidataanalyticshttps://www.googleapis.com/auth/bigquery.readonly如果平台預期會收到以空格分隔的單一字串,請輸入:
https://www.googleapis.com/auth/geminidataanalytics https://www.googleapis.com/auth/bigquery.readonly用戶端 ID CLIENT_ID (您在上一節建立的 OAuth 2.0 用戶端 ID) 用戶端密鑰 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 託管貴組織的資料代理,因此請在根代理的自訂系統指令或技能設定中,提供目標專案 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.
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.
Looker 支援的資料代理驗證
如果資料代理連結至 Looker 探索,對 chat 工具的要求必須包含含有 Looker API 憑證 (用戶端 ID 和用戶端密鑰) 的 credentials 區塊,因為 Looker 會獨立於 IAM 管理驗證。
為 Looker 支援的資料代理設定代理平台時,請採用下列最佳做法:
- 請勿提示使用者提供密鑰:設定根代理,絕不要求使用者在對話中貼上或提供 Looker API 憑證。
- 使用專屬的 Looker API 使用者帳戶:建立專屬的 Looker API 使用者,並授予最小權限,範圍僅限資料代理所需的模型和探索。
- 在模型內容外插入憑證:設定平台、MCP 用戶端中介軟體或 Proxy 層,在傳輸或工具執行層將 Looker API 憑證插入
chat要求酬載。請勿將用戶端密鑰放在根代理的提示指令或對話記錄中。
代理平台憑證插入模式
為避免將密鑰傳入模型內容視窗,平台通常會採用下列其中一種方法,插入 Looker 憑證:
- MCP 用戶端中介軟體或 Proxy 攔截:在支援要求中介軟體、API Gateway 或工具攔截掛鉤的平台中,根代理會生成僅包含語意參數 (
parent、dataAgentContext和messages) 的chat工具呼叫。中介軟體層會在傳出的 JSON-RPC 要求到達https://geminidataanalytics.googleapis.com/mcp之前攔截,從安全的 Secret 儲存庫或環境變數讀取憑證,並填入credentials物件。 - 封裝工具定義:在自訂代理架構 (例如 Agent Development Kit (ADK) 或自訂 Python 自動化調度管理工具) 中,向根代理公開
chat工具的封裝版本,並從工具結構定義中省略credentials參數。包裝函式的執行處理常式會先透過程式輔助方式,從安全設定附加credentials區塊,再將呼叫轉送至對話式數據分析 API MCP 伺服器。
以下範例顯示 MCP 用戶端傳送至遠端 MCP 伺服器的完整 JSON-RPC 要求酬載,用於 chat 工具。模型會生成 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.
請按照下列方式替換範例值:
- PROJECT_ID:已啟用對話式數據分析 API 的Google Cloud 專案 ID
- LOCATION:對話式數據分析 API 資源的位置 (例如
global) - CONNECTOR_NAME:您在代理平台中指派給自訂 MCP 連線的名稱 (例如
ca-mcp-prod)
後續步驟
- 進一步瞭解 對話式數據分析 API 遠端 MCP 伺服器架構和工具對應。
- 瞭解如何使用 HTTP 建構及設定資料代理,或使用 Python SDK。
- 瞭解如何使用編寫的情境引導代理行為。
- 如要排解常見問題,請參閱「排解 Conversational Analytics API 錯誤」。