Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

MCP를 사용하여 데이터 에이전트에 연결

서드 파티(예: Claude Code, Claude Cowork, ChatGPT) 또는 Google 관리 에이전트 플랫폼(예: Gemini Enterprise)의 관리자는 Conversational Analytics API 원격 MCP 서버(https://geminidataanalytics.googleapis.com/mcp)에 대한 커스텀 모델 컨텍스트 프로토콜(MCP) 연결을 구성할 수 있습니다. 에이전트 플랫폼을 이 서버에 연결하면 플랫폼의 루트 에이전트가 비즈니스 사용자를 대신하여 특수 데이터 에이전트를 검색하고 쿼리할 수 있습니다.

대화형 분석 API 원격 MCP 서버는 3-legged OAuth 2.0 플로우를 사용하여 최종 사용자 인증 정보(EUC)를 BigQuery에 전파합니다. 이 전파를 통해 에이전트 검색 요청과 BigQuery 쿼리가 인증된 사용자의 ID로 실행되고 기존 Identity and Access Management(IAM) 권한 및 데이터 거버넌스 정책을 준수할 수 있습니다. Looker 지원 데이터 에이전트는 최종 사용자 인증 정보를 수신하지 않습니다. 대신 쿼리에 별도의 Looker API 클라이언트 사용자 인증 정보가 필요합니다(Looker 지원 데이터 에이전트 인증 참조).

사용자 요청을 수신하는 기본 조정 에이전트인 루트 에이전트가 원격 MCP 서버와 통신하는 방식에 대한 아키텍처 개요는 대화형 분석 API 원격 MCP 서버를 참조하세요.

시작하기 전에

에이전트 플랫폼에서 MCP 연결을 구성하기 전에 다음 기본 요건을 완료하세요.

Google Cloud 프로젝트에서 대화형 분석 API 및 BigQuery에 필요한 API를 사용 설정합니다.
데이터 운영자가 Google Cloud 프로젝트에서 하나 이상의 데이터 에이전트를 만들고 구성했는지 확인합니다. 여기에는 각 에이전트가 액세스할 수 있는 데이터 소스와 답변할 수 있는 질문에 대한 명확한 설명이 포함되어야 합니다.
MCP 연결을 통해 인증할 비즈니스 사용자가 필수 IAM 역할을 가지고 있고 대상 데이터 세트에 대한 읽기 액세스 권한과 에이전트에 대한 액세스 권한이 있는지 확인합니다.

필요한 역할

원격 MCP 서버를 통해 인증하고 데이터 에이전트를 쿼리하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

데이터 에이전트와 채팅:
- 프로젝트에 대한 Gemini 데이터 분석 데이터 에이전트 사용자(roles/geminidataanalytics.dataAgentUser)
- 프로젝트에 대한 Google Cloud를 위한 Gemini 사용자(roles/cloudaicompanion.user)
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 콘솔 사용자 인증 정보 페이지에서 OAuth 2.0 클라이언트 ID를 만듭니다. 사용자 인증 정보를 구성할 때 대화형 분석 API MCP 통합과 관련된 다음 설정을 적용합니다.

대상: 조직에서 Google Workspace를 사용하는 경우 내부를 선택합니다. 이 선택은 조직 내 사용자로 액세스를 제한하고, 민감한 범위에 대한 OAuth 앱 인증의 필요성을 방지하며, Google Workspace 앱 액세스 제어 정책이 사용자의 인증을 차단하지 않도록 합니다.
애플리케이션 유형 및 리디렉션 URI: 애플리케이션 유형으로 웹 애플리케이션을 선택하고 에이전트형 플랫폼에 필요한 승인된 리디렉션 URI를 추가합니다(예: Gemini Enterprise에서 커스텀 MCP 커넥터를 구성할 때 https://vertexaisearch.cloud.google.com/oauth-redirect).
OAuth 범위: 루트 에이전트가 사용자를 대신하여 대화형 분석 API 도구를 호출하고 읽기 전용 BigQuery 쿼리를 실행할 수 있는 권한을 갖도록 다음 두 범위를 모두 요청하도록 OAuth 동의 화면과 클라이언트를 구성합니다.
- 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 서버 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 클라이언트 보안 비밀번호)

메시지가 표시되면 플랫폼에서 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.

Looker 지원 데이터 에이전트 인증

데이터 에이전트가 Looker Explore에 연결하는 경우 Looker는 IAM과 별개로 인증을 관리하므로 chat 도구에 대한 요청에는 Looker API 사용자 인증 정보(클라이언트 ID 및 클라이언트 보안 비밀번호)가 포함된 credentials 블록이 포함되어야 합니다.

Looker 지원 데이터 에이전트를 위한 에이전트형 플랫폼을 구성할 때는 다음 권장사항을 적용하세요.

사용자에게 보안 비밀을 요청하지 않음: 루트 에이전트가 최종 사용자에게 채팅에서 Looker API 사용자 인증 정보를 붙여넣거나 제공하도록 요청하지 않도록 구성합니다.
전용 Looker API 사용자 계정 사용: 데이터 에이전트에 필요한 모델 및 Explore로만 범위가 지정된 최소 권한을 가진 전용 Looker API 사용자를 만듭니다.
모델 컨텍스트 외부에 사용자 인증 정보 삽입: 전송 또는 도구 실행 레이어에서 chat 요청 페이로드에 Looker API 사용자 인증 정보를 삽입하도록 플랫폼, MCP 클라이언트 미들웨어 또는 프록시 레이어를 구성합니다. 루트 에이전트의 프롬프트 안내나 대화 기록에 클라이언트 보안 비밀번호를 입력하지 마세요.

주의: 시스템 프롬프트 안내 또는 대화 컨텍스트에서 clientSecret 필드를 전달하지 마세요. 프롬프트 텍스트에 사용자 인증 정보를 노출하면 모델의 컨텍스트 윈도우에 직접 배치되므로 대화 로그, 프롬프트 인젝션 또는 생성된 모델 출력을 통해 보안 비밀이 유출될 위험이 높아집니다. 가능하면 모델 컨텍스트 외부에서 도구 호출 페이로드에 credentials 블록을 자동으로 삽입하도록 에이전트 플랫폼 또는 MCP 클라이언트 미들웨어를 구성합니다. 플랫폼에서 프롬프트에 직접 사용자 인증 정보를 구성해야 하는 경우 엄격하게 범위가 지정된 읽기 전용 권한이 있는 전용 Looker API 사용자 계정을 사용하고 클라이언트 보안 비밀번호를 정기적으로 순환합니다.

에이전트형 플랫폼의 사용자 인증 정보 삽입 패턴

모델 컨텍스트 창에서 보안 비밀을 제외하기 위해 플랫폼은 일반적으로 다음 방법 중 하나를 사용하여 Looker 사용자 인증 정보를 삽입합니다.

MCP 클라이언트 미들웨어 또는 프록시 가로채기: 요청 미들웨어, API Gateway 또는 도구 가로채기 후크를 지원하는 플랫폼에서 루트 에이전트는 시맨틱 파라미터(parent, dataAgentContext, messages)만 포함하는 chat 도구 호출을 생성합니다. 미들웨어 레이어는 발신 JSON-RPC 요청이 https://geminidataanalytics.googleapis.com/mcp에 도달하기 전에 가로채고, 보안 비밀 저장소 또는 환경 변수에서 사용자 인증 정보를 읽고, credentials 객체를 채웁니다.
래핑된 도구 정의: 커스텀 에이전트 프레임워크(예: 에이전트 개발 키트(ADK) 또는 커스텀 Python 조정자)에서 도구 스키마에서 credentials 파라미터를 생략하는 chat 도구의 래핑된 버전을 루트 에이전트에 노출합니다. 래퍼의 실행 핸들러는 대화 분석 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.