MCP を使用してデータ エージェントに接続する

サードパーティ（Claude Code、Claude Cowork、ChatGPT など）または Google が管理するエージェント プラットフォーム（Gemini Enterprise など）の管理者として、Conversational Analytics API リモート MCP サーバー（https://geminidataanalytics.googleapis.com/mcp）へのカスタム Model Context Protocol（MCP）接続を構成できます。エージェント プラットフォームをこのサーバーに接続すると、プラットフォームのルート エージェントがビジネス ユーザーに代わって、専用のデータ エージェントを検出してクエリを実行できます。

会話型分析 API リモート MCP サーバーは、3-legged OAuth 2.0 フローを使用して、エンドユーザー認証情報（EUC）を BigQuery に伝播します。この伝播により、エージェントの検出リクエストと BigQuery クエリが認証済みユーザーの ID で実行され、既存の Identity and Access Management（IAM）権限とデータ ガバナンス ポリシーが遵守されます。Looker を利用するデータ エージェントはエンドユーザーの認証情報を受け取りません。代わりに、クエリには個別の Looker API クライアント認証情報が必要です（Looker を利用するデータ エージェントの認証をご覧ください）。

ルート エージェント（ユーザー リクエストを受信するプライマリ オーケストレーション エージェント）がリモート MCP サーバーと通信する方法のアーキテクチャの概要については、Conversational Analytics API リモート MCP サーバーをご覧ください。

始める前に

エージェント プラットフォームで MCP 接続を構成する前に、次の前提条件を満たしてください。

  1. Google Cloud プロジェクトで、Conversational Analytics API と BigQuery に必要な API を有効にします。
  2. データ オペレーターが Google Cloud プロジェクトで1 つ以上のデータ エージェントを作成して構成していることを確認します。これには、各エージェントがアクセスできるデータソースと、回答できる質問の明確な説明が含まれます。
  3. MCP 接続を介して認証するビジネス ユーザーに、必要な IAM ロール、ターゲット データセットへの読み取りアクセス権、エージェントへのアクセス権があることを確認します。

必要なロール

リモート MCP サーバーを介して認証し、データ エージェントにクエリを実行するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

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 統合に固有の次の設定を適用します。

  1. 対象: 組織で Google Workspace を使用している場合は、[内部] を選択します。この選択により、組織内のユーザーへのアクセスが制限され、機密スコープの OAuth アプリの確認が不要になり、Google Workspace アプリのアクセス制御ポリシーによってユーザーの認証がブロックされなくなります。
  2. アプリケーションの種類とリダイレクト URI: アプリケーションの種類として [ウェブ アプリケーション] を選択し、エージェント プラットフォームに必要な承認済みのリダイレクト URI を追加します（例: Gemini Enterprise でカスタム MCP コネクタを構成する場合は https://vertexaisearch.cloud.google.com/oauth-redirect）。
  3. OAuth スコープ: ルート エージェントが会話型分析 API ツールを呼び出し、ユーザーに代わって読み取り専用の BigQuery クエリを実行できるように、次の両方のスコープをリクエストするように OAuth 同意画面とクライアントを構成します。
    • Gemini データ分析スコープ: https://www.googleapis.com/auth/geminidataanalytics
    • BigQuery 読み取り専用スコープ: https://www.googleapis.com/auth/bigquery.readonly
  4. 生成されたクライアント ID とクライアント シークレットをコピーして安全に保存します。

カスタム MCP 接続を構成する

OAuth 2.0 クライアント ID とクライアント シークレットを生成したら、エージェント プラットフォームの管理設定でカスタム MCP 接続（またはカスタム MCP コネクタ）を登録します。

  1. エージェント プラットフォームで、新しいカスタム MCP サーバー接続を作成し、次の構成値を指定します。

    設定 値
    MCP サーバーの URL https://geminidataanalytics.googleapis.com/mcp
    認証方法 OAuth 2.0
    認可 URL https://accounts.google.com/o/oauth2/v2/auth
    認可 URL パラメータ

    &access_type=offline&prompt=consent

    プラットフォームでユーザー セッションにオフライン更新トークンが必要な場合は、このパラメータ文字列を使用します。
    トークン URL 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（前のセクションで作成した OAuth 2.0 クライアント ID）
    クライアント シークレット CLIENT_SECRET（前のセクションで作成した OAuth 2.0 クライアント シークレット）

  2. プロンプトが表示されたら、プラットフォームで OAuth 接続を確認します。Google の同意画面が開いたら、ログインして、アプリケーションが Gemini Data Analytics と BigQuery の両方の読み取り専用アクセスをリクエストしていることを確認します。

  3. プラットフォームで 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.

Looker を利用したデータ エージェントの認証

データ エージェントが Looker Explore に接続する場合、chat ツールへのリクエストには、Looker API 認証情報（クライアント ID とクライアント シークレット）を含む credentials ブロックを含める必要があります。これは、Looker が IAM とは独立して認証を管理するためです。

Looker を利用したデータ エージェント用にエージェント プラットフォームを構成する場合は、次のベスト プラクティスを適用します。

  • ユーザーにシークレットを要求しない: エンドユーザーに Looker API 認証情報をチャットで貼り付けたり提供したりするよう要求しないように、ルート エージェントを構成します。
  • 専用の Looker API ユーザー アカウントを使用する: データ エージェントが必要とするモデルと Explore のみにスコープが設定された最小権限を持つ専用の Looker API ユーザーを作成します。
  • モデル コンテキスト外で認証情報を挿入する: プラットフォーム、MCP クライアント ミドルウェア、またはプロキシレイヤを構成して、トランスポート レイヤまたはツール実行レイヤで Looker API 認証情報を chat リクエスト ペイロードに挿入します。クライアント シークレットをルート エージェントのプロンプト指示や会話履歴に配置しないでください。

エージェント型プラットフォームの認証情報インジェクション パターン

シークレットをモデル コンテキスト ウィンドウから除外するため、プラットフォームは通常、次のいずれかの方法で Looker 認証情報を挿入します。

  • MCP クライアント ミドルウェアまたはプロキシ インターセプト: リクエスト ミドルウェア、API Gateway、ツール インターセプト フックをサポートするプラットフォームでは、ルート エージェントはセマンティック パラメータ（parent、dataAgentContext、messages）のみを含む chat ツール呼び出しを生成します。ミドルウェア レイヤは、送信される JSON-RPC リクエストが https://geminidataanalytics.googleapis.com/mcp に到達する前にインターセプトし、安全なシークレット ストアまたは環境変数から認証情報を読み取り、credentials オブジェクトに入力します。
  • ラップされたツール定義: カスタム エージェント フレームワーク（Agent Development Kit（ADK）やカスタム Python オーケストレーターなど）で、ツールスキーマから credentials パラメータを省略した chat ツールのラップされたバージョンをルート エージェントに公開します。ラッパーの実行ハンドラは、Conversational Analytics API MCP サーバーに呼び出しを転送する前に、安全な構成から credentials ブロックをプログラムでアタッチします。

次の例は、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.

サンプル値を次のように置き換えます。

  • PROJECT_ID: 会話型分析 API を有効にしたGoogle Cloud プロジェクトの ID
  • LOCATION: 会話型分析 API リソースのロケーション（例: global）
  • CONNECTOR_NAME: エージェント プラットフォームでカスタム MCP 接続に割り当てた名前（例: ca-mcp-prod）

次のステップ