BigQuery 원격 MCP 서버 사용

프리뷰

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'과 생성형 AI 프리뷰 제품 추가 약관이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 문서에서는 BigQuery 원격 모델 컨텍스트 프로토콜 (MCP) 서버를 사용하여 Gemini CLI, Gemini Code Assist의 에이전트 모드, Claude Code 또는 개발 중인 AI 애플리케이션과 같은 AI 애플리케이션에서 BigQuery에 연결하는 방법을 설명합니다.

모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델 (LLM)과 AI 애플리케이션 또는 에이전트가 외부 데이터 소스에 연결되는 방식을 표준화합니다. MCP 서버를 사용하면 도구, 리소스, 프롬프트를 사용하여 백엔드 서비스에서 작업을 실행하고 업데이트된 데이터를 가져올 수 있습니다.

로컬 MCP 서버는 일반적으로 로컬 머신에서 실행되며 동일한 기기의 서비스 간 통신을 위해 표준 입력 및 출력 스트림 (stdio)을 사용합니다. 원격 MCP 서버는 서비스의 인프라에서 실행되며 AI MCP 클라이언트와 MCP 서버 간 통신을 위해 AI 애플리케이션에 HTTPS 엔드포인트를 제공합니다. MCP 아키텍처에 대한 자세한 내용은 MCP 아키텍처를 참고하세요.

Google 및 Google Cloud 원격 MCP 서버에는 다음과 같은 기능과 이점이 있습니다.

• 간소화된 중앙 집중식 검색
• 관리형 전역 또는 리전 HTTPS 엔드포인트
• 세부적인 승인
• Model Armor 보호를 통한 선택적 프롬프트 및 응답 보안
• 중앙 집중식 감사 로깅

다른 MCP 서버에 대한 정보와 Google Cloud MCP 서버에 사용할 수 있는 보안 및 거버넌스 제어에 대한 정보는 Google Cloud MCP 서버 개요를 참고하세요.

다음과 같은 이유로 BigQuery 로컬 MCP 서버를 사용할 수 있습니다.

• 매개변수화된 SQL 쿼리를 기반으로 맞춤 도구를 빌드해야 합니다.
• 프로젝트에서 원격 MCP 서버를 사용 설정하거나 사용할 권한이 없습니다.

로컬 MCP 서버를 사용하는 방법에 대한 자세한 내용은 MCP로 LLM을 BigQuery에 연결을 참고하세요. 다음 섹션은 BigQuery 원격 MCP 서버에만 적용됩니다.

시작하기 전에

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우 필요한 권한이 이미 있습니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우 필요한 권한이 이미 있습니다.

1. Enable the BigQuery API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

   새 프로젝트에서는 BigQuery API가 자동으로 사용 설정됩니다.

2. (선택사항) 프로젝트에 대한 결제를 사용 설정합니다. 결제를 사용 설정하거나 신용카드를 제공하지 않는 경우 이 문서의 단계가 계속 작동합니다. BigQuery에서는 단계를 수행하기 위한 샌드박스를 제공합니다. 자세한 내용은 BigQuery 샌드박스 사용 설정을 참조하세요.
   참고: 프로젝트에 결제 계정이 있고 BigQuery 샌드박스를 사용하려는 경우 프로젝트의 결제를 중지하세요.

필요한 역할

BigQuery MCP 서버를 사용 설정하는 데 필요한 권한을 얻으려면 BigQuery MCP 서버를 사용 설정하려는 프로젝트에 대해 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 프로젝트에서 API 및 MCP 서버 사용 설정: 서비스 사용량 관리자 (roles/serviceusage.serviceUsageAdmin)
• MCP 도구 호출: MCP 도구 사용자 (roles/mcp.toolUser)
• BigQuery 작업 실행: BigQuery 작업 사용자 (roles/bigquery.jobUser)
• BigQuery 데이터 쿼리: BigQuery 데이터 뷰어 (roles/bigquery.dataViewer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 BigQuery MCP 서버를 사용 설정하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

BigQuery MCP 서버를 사용 설정하려면 다음 권한이 필요합니다.

• 프로젝트에서 MCP 서버를 사용 설정합니다.
  • serviceusage.mcppolicy.get
  • serviceusage.mcppolicy.update
• MCP 도구 호출: mcp.tools.call
• BigQuery 작업 실행: bigquery.jobs.create
• BigQuery 데이터 쿼리: bigquery.tables.getData

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

참고: 작업에 따라 추가 BigQuery 권한이 필요할 수 있습니다. BigQuery 권한에 대한 자세한 내용은 BigQuery IAM 역할 및 권한을 참고하세요.

BigQuery MCP 서버 사용 설정 또는 사용 중지

gcloud beta services mcp enable 명령어를 사용하여 프로젝트에서 BigQuery MCP 서버를 사용 설정하거나 사용 중지할 수 있습니다. 자세한 내용은 다음 섹션을 참고하세요.

프로젝트에서 BigQuery MCP 서버 사용 설정

서비스 계정 키, OAuth 클라이언트 ID 또는 API 키와 같은 클라이언트 사용자 인증 정보에 다른 프로젝트를 사용하고 리소스 호스팅에 다른 프로젝트를 사용하는 경우 두 프로젝트 모두에서 BigQuery 서비스와 BigQuery 원격 MCP 서버를 사용 설정해야 합니다.

Google Cloud 프로젝트에서 BigQuery MCP 서버를 사용 설정하려면 다음 명령어를 실행합니다.

gcloud beta services mcp enable SERVICE \
    --project=PROJECT_ID

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• SERVICE: bigquery.googleapis.com (BigQuery의 전역 서비스 이름)

Google Cloud 프로젝트에서 사용할 수 있도록 BigQuery 원격 MCP 서버가 사용 설정되어 있습니다. Google Cloud 프로젝트에 BigQuery 서비스가 사용 설정되어 있지 않으면 BigQuery 원격 MCP 서버를 사용 설정하기 전에 서비스를 사용 설정하라는 메시지가 표시됩니다.

보안 권장사항에 따라 AI 애플리케이션이 작동하는 데 필요한 서비스에만 MCP 서버를 사용 설정하는 것이 좋습니다.

프로젝트에서 BigQuery MCP 서버 사용 중지

Google Cloud 프로젝트에서 BigQuery MCP 서버를 사용 중지하려면 다음 명령어를 실행합니다.

gcloud beta services mcp disable SERVICE \
    --project=PROJECT_ID

Google Cloud 프로젝트에서 BigQuery MCP 서버를 사용할 수 없습니다.

인증 및 승인

BigQuery MCP 서버는 인증 및 승인에 Identity and Access Management (IAM)와 함께 OAuth 2.0 프로토콜을 사용합니다. 모든 Google CloudID는 MCP 서버에 대한 인증에 지원됩니다.

BigQuery 원격 MCP 서버는 API 키를 허용하지 않습니다.

BigQuery MCP OAuth 범위

OAuth 2.0은 범위와 사용자 인증 정보를 사용하여 인증된 주 구성원이 리소스에 대해 특정 작업을 수행할 권한이 있는지 확인합니다. Google의 OAuth 2.0 범위에 대한 자세한 내용은 OAuth 2.0을 사용하여 Google API에 액세스하기를 참고하세요.

BigQuery에는 다음과 같은 MCP 도구 OAuth 범위가 있습니다.

gcloud CLI의 범위 URI	설명
https://www.googleapis.com/auth/bigquery	BigQuery에서 데이터를 조회 및 관리하고 Google 계정의 이메일 주소를 확인합니다.

도구 호출 중에 액세스하는 리소스에 추가 범위가 필요할 수 있습니다. BigQuery에 필요한 범위 목록을 보려면 BigQuery API v2의 OAuth 2.0 범위를 참고하세요.

BigQuery MCP 서버를 사용하도록 MCP 클라이언트 구성

Claude 또는 Gemini CLI와 같은 호스트 프로그램은 단일 MCP 서버에 연결되는 MCP 클라이언트를 인스턴스화할 수 있습니다. 호스트 프로그램에는 서로 다른 MCP 서버에 연결되는 클라이언트가 여러 개 있을 수 있습니다. 원격 MCP 서버에 연결하려면 MCP 클라이언트가 최소한 원격 MCP 서버의 URL을 알아야 합니다.

호스트에서 원격 MCP 서버에 연결하는 방법을 찾습니다. 이름, URL 등 서버에 관한 세부정보를 입력하라는 메시지가 표시됩니다.

BigQuery MCP 서버의 경우 필요에 따라 다음을 입력합니다.

• 서버 이름: BigQuery MCP 서버
• 서버 URL 또는 엔드포인트: bigquery.googleapis.com/mcp
• 전송: HTTP

• 인증 세부정보: Google Cloud 사용자 인증 정보, OAuth 클라이언트 ID 및 보안 비밀번호 또는 에이전트 ID 및 사용자 인증 정보

  선택하는 인증 세부정보는 인증하려는 방식에 따라 달라집니다. 자세한 내용은 MCP 서버에 인증을 참고하세요.

호스트별 안내는 다음을 참고하세요.

• Gemini CLI MCP 서버 설정
• Claude 지원: 원격 MCP를 사용하여 커스텀 커넥터 시작하기

일반적인 안내는 원격 MCP 서버에 연결을 참고하세요.

사용 가능한 도구

읽기 전용인 MCP 도구는 MCP 속성 mcp.tool.isReadOnly이 true로 설정되어 있습니다. 조직 정책을 통해 특정 환경에서 읽기 전용 도구만 허용할 수 있습니다.

사용 가능한 MCP 도구의 세부정보와 BigQuery MCP 서버에 대한 설명을 보려면 BigQuery MCP 참조를 참고하세요.

목록 도구

MCP 검사기를 사용하여 도구를 나열하거나 tools/list HTTP 요청을 BigQuery 원격 MCP 서버에 직접 전송합니다. tools/list 메서드는 인증이 필요하지 않습니다.

POST /mcp HTTP/1.1
Host: bigquery.googleapis.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
}

샘플 사용 사례

다음은 BigQuery MCP 서버의 샘플 사용 사례입니다.

• BigQuery 데이터의 통계를 사용하여 문제 생성, 이메일 작성과 같은 특정 작업을 트리거하는 워크플로를 빌드합니다.

• BigQuery의 예측과 같은 고급 기능을 사용하여 고차 통계를 얻으세요.

• 맞춤 에이전트 지침을 사용하여 사용자를 위한 대화형 환경을 빌드하세요.

샘플 프롬프트

다음 샘플 프롬프트를 사용하여 BigQuery 리소스에 대한 정보를 얻고, 통계를 얻고, BigQuery 데이터를 분석할 수 있습니다.

• PROJECT_ID 프로젝트의 데이터 세트를 나열합니다.
• REGION 리전의 MCP 서버를 사용하여 PROJECT_ID 프로젝트에서 실행한 모든 쿼리를 찾아 줘. goog-mcp-server:true 태그를 사용하여 MCP 서버를 통해 실행된 쿼리 작업을 식별합니다.
• PROJECT_ID 프로젝트에서 DATASET_ID의 볼륨별 상위 주문을 찾아 줘. 적절한 표를 식별하고 올바른 스키마를 찾아 결과를 표시해 줘.
• 향후 연도에 대해 PROJECT_ID.DATASET_ID.TABLE_ID 테이블에 예측을 만듭니다. COLUMN_NAME을 데이터 열로, COLUMN_NAME을 타임스탬프 열로 사용합니다. 상위 10개 예측을 표시합니다.

프롬프트에서 다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• REGION: 리전의 이름
• DATASET_ID: 데이터 세트의 이름
• TABLE_ID: 테이블의 이름
• COLUMN_NAME: 열 이름

선택적 보안 및 안전 구성

MCP는 MCP 도구로 취할 수 있는 다양한 작업으로 인해 새로운 보안 위험과 고려사항을 도입합니다. 이러한 위험을 최소화하고 관리하기 위해Google Cloud 에서는 Google Cloud조직 또는 프로젝트에서 MCP 도구 사용을 제어할 수 있는 기본값과 맞춤설정 가능한 정책을 제공합니다.

MCP 보안 및 거버넌스에 관한 자세한 내용은 AI 보안 및 안전을 참고하세요.

Model Armor

Model Armor는 AI 애플리케이션의 보안과 안전을 강화하도록 설계된 Google Cloud 서비스입니다. LLM 프롬프트와 대답을 사전 예방적으로 검사하여 다양한 위험으로부터 보호하고 책임감 있는 AI 관행을 지원합니다. 클라우드 환경에 AI를 배포하든 외부 클라우드 제공업체에 배포하든 Model Armor를 사용하면 악의적인 입력을 방지하고, 콘텐츠 안전을 검증하고, 민감한 정보를 보호하고, 규정 준수를 유지하고, 다양한 AI 환경 전반에서 AI 안전 및 보안 정책을 일관되게 적용할 수 있습니다.

Model Armor는 특정 지역에서만 사용할 수 있습니다. 프로젝트에 Model Armor가 사용 설정되어 있고 지원되지 않는 지역에서 해당 프로젝트에 대한 호출이 이루어지면 Model Armor가 교차 지역 호출을 실행합니다. 자세한 내용은 Model Armor 위치를 참고하세요.

Model Armor 사용 설정

모델 아머를 사용 설정하려면 다음 단계를 완료하세요.

1. Google Cloud 프로젝트에서 Model Armor를 사용 설정합니다.

   gcloud services enable modelarmor.googleapis.com \
       --project=PROJECT_ID
   

   PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

2. 권장되는 Model Armor 최소 기준 설정을 구성합니다.

   gcloud model-armor floorsettings update \
       --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
       --mcp-sanitization=ENABLED \
       --malicious-uri-filter-settings-enforcement=ENABLED \
       --pi-and-jailbreak-filter-settings-enforcement=ENABLED \
       --pi-and-jailbreak-filter-settings-confidence-level=MEDIUM_AND_ABOVE
   

   PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

   Model Armor는 악성 URL과 프롬프트 인젝션 및 탈옥 시도를 검사하도록 구성되어 있습니다.

   구성 가능한 Model Armor 필터에 대한 자세한 내용은 Model Armor 필터를 참고하세요.

3. MCP 서비스의 콘텐츠 보안 제공업체로 Model Armor를 추가합니다.

   gcloud beta services mcp content-security add modelarmor.googleapis.com \
       --project=PROJECT_ID
   

   PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

4. MCP 트래픽이 Model Armor로 전송되는지 확인합니다.

   gcloud beta services mcp content-security get \
       --project=PROJECT_ID
   

   PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

Model Armor 로깅

Model Armor 감사 및 플랫폼 로그에 대한 자세한 내용은 Model Armor 감사 로깅을 참고하세요.

주의: 요청이 실패하면 Model Armor가 전체 페이로드를 로깅합니다. 이로 인해 로그에 민감한 정보가 노출될 수 있습니다.

프로젝트에서 Model Armor 사용 중지

Google Cloud 프로젝트에서 Model Armor를 사용 중지하려면 다음 명령어를 실행합니다.

gcloud beta services mcp content-security remove modelarmor.googleapis.com \
    --project=PROJECT_ID

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

Google Cloud 의 MCP 트래픽은 지정된 프로젝트에 대해 Model Armor로 스캔되지 않습니다.

Model Armor로 MCP 트래픽 스캔 사용 중지

프로젝트에서 Model Armor를 계속 사용하고 싶지만 Model Armor로 MCP 트래픽을 스캔하는 것을 중지하려면 다음 명령어를 실행하세요.

gcloud model-armor floorsettings update \
    --full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
    --mcp-sanitization=DISABLED

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

Model Armor는 Google Cloud에서 MCP 트래픽을 검사하지 않습니다.

조직 수준 MCP 제어

gcp.managed.allowedMCPService 제약 조건을 사용하여 Google Cloud 조직에서 MCP 서버 사용을 제어하는 맞춤 조직 정책을 만들 수 있습니다. 자세한 내용과 사용 예는 IAM으로 액세스 제어를 참고하세요.

할당량 및 한도

BigQuery 원격 MCP 서버에는 자체 할당량이 없습니다. MCP 서버에 대한 호출 수에는 제한이 없습니다.

MCP 서버 도구에서 호출하는 API에 의해 적용되는 할당량은 계속 적용됩니다. MCP 서버 도구에서 호출하는 API 메서드는 다음과 같습니다.

도구	API 메서드	할당량
list_dataset_ids	datasets.list	데이터 세트 할당량 및 한도
list_table_ids	tables.list	표 할당량 및 한도
get_dataset_info	datasets.get	데이터 세트 할당량 및 한도
get_table_info	tables.get	표 할당량 및 한도
execute_sql	jobs.Query	쿼리 작업 할당량 및 한도

BigQuery 할당량에 대한 자세한 내용은 할당량 및 한도를 참고하세요.

다음 단계

• BigQuery MCP 참조 문서를 읽어보세요.
• Google Cloud MCP 서버에 대해 자세히 알아보세요.
• MCP 지원 제품을 참고하세요.