Google MCP 서버 시작하기

1. 소개

환영합니다! 이 Codelab에서는 Google 관리형 모델 컨텍스트 프로토콜 (MCP) 서버를 사용하여 AI 에이전트를 강화하는 방법을 알아봅니다.

모델 컨텍스트 프로토콜 (MCP)은 AI 모델이 외부 데이터 소스 및 도구에 안전하고 효율적으로 연결할 수 있도록 지원하는 오픈소스 표준입니다. 대부분의 MCP 구현은 머신에서 로컬로 실행되지만 Google에서는 관리형 원격 MCP 서버를 제공합니다. 이는 완전 호스팅된 엔터프라이즈 지원 엔드포인트로, 서버 측 코드나 컨테이너를 관리하지 않아도 상담사가 Google Cloud 인프라와 직접 상호작용할 수 있습니다.

'관리형'의 장점

표준 입력/출력 (stdio)을 사용하는 로컬 MCP 서버와 달리 Google 관리 서버는 스트리밍 가능한 HTTP를 사용합니다. 이 아키텍처는 다음을 제공합니다.

인프라 제로: 프로비저닝하거나 확장할 서버가 없습니다.
설계에 의한 보안: Google Cloud IAM 및 감사 로그와 기본적으로 통합됩니다.
상태 비저장 확장: 표준 부하 분산기와 프록시를 통한 원활한 상호작용

학습할 내용

관리형 MCP 서버를 사용 설정하고 인증하는 방법
Cloud Logging MCP 서버를 기본 기준선으로 사용하는 방법
여러 MCP 서버 (개발자 지식, Firestore 등)를 조정하여 자율 워크플로를 빌드하는 방법

필요한 항목

결제가 사용 설정된 Google Cloud 프로젝트.
Google Cloud 콘솔 및 gcloud CLI에 대한 기본 지식
Google Cloud Shell (Gemini CLI가 사전 설치되어 있음)

이 Codelab은 초보자를 포함한 모든 수준의 사용자와 개발자를 대상으로 합니다.

문제 보고

Codelab을 진행하고 Antigravity를 사용하면서 문제가 발생할 수 있습니다.

Codelab 관련 문제 (오타, 잘못된 안내)의 경우 이 Codelab의 왼쪽 하단에 있는 Report a mistake 버튼을 사용하여 버그를 신고하세요.

2. 시작하기 전에

이 단계에서는 Google Cloud 환경을 준비합니다. 지속적이고 사전 구성된 터미널을 제공하는 Google Cloud Shell 내에서 모든 작업을 수행합니다.

Cloud Shell 활성화

Google Cloud Console로 이동합니다.
오른쪽 상단 헤더에서 Cloud Shell 활성화 아이콘을 클릭합니다.
터미널 세션이 시작되면 메시지가 표시될 경우 승인합니다.

프로젝트 ID 설정

Cloud Shell이 올바른 프로젝트를 가리키는지 확인합니다.

# Set your active project
gcloud config set project YOUR_PROJECT_ID

# Verify the setting
gcloud config list project

Foundation API 사용 설정

관리형 MCP 서버를 사용하려면 기본 제품 API와 MCP 인터페이스가 모두 사용 설정되어 있어야 합니다. 다음 명령어를 실행하여 Cloud Logging 백엔드 (이 실습의 기준)를 사용 설정합니다.

# Enable the Cloud Logging API and its MCP interface
gcloud services enable logging.googleapis.com
gcloud beta services mcp enable logging.googleapis.com

참고: 관리형 MCP 서비스는 현재 베타 버전입니다. 이 기능을 사용 설정하려면 gcloud 베타 구성요소를 사용해야 합니다.

애플리케이션 기본 사용자 인증 정보 (ADC) 설정

Gemini CLI는 사용자 ID를 사용하여 MCP 서버와 통신합니다. 에이전트가 사용자를 대신하여 행동할 수 있는 권한을 부여합니다.

gcloud auth application-default login

터미널의 URL을 따라 로그인하고 승인 코드를 Cloud Shell에 다시 붙여넣습니다.

기본 IAM 역할 할당

관리형 MCP 서버는 이중 레이어 보안 모델을 사용합니다. 다음 두 가지 특정 '게이트'가 열려 있어야 합니다.

관문 1 (MCP 액세스): 프로토콜을 호출할 수 있는 역할입니다.
관문 2 (서비스 액세스): 데이터를 볼 수 있는 역할 (예: 로그 보기)입니다.

다음을 실행하여 필요한 액세스 권한을 부여합니다.

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

# Gate 1: Permission to use the MCP protocol
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/mcp.toolUser"

# Gate 2: Permission to view the actual logs
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/logging.viewer"

3. 기본 사항: 첫 번째 MCP 서버 연결

이 단계에서는 AI 에이전트 (Gemini CLI)를 Google Cloud Logging MCP 서버에 연결합니다. 이 도구는 상담사가 프로젝트 내부에서 발생하는 상황을 실시간으로 확인할 수 있도록 지원하므로 '기반'이라고 할 수 있습니다.

작업 1: 로깅 MCP 서버 구성

Gemini CLI는 settings.json 파일을 사용하여 연결을 관리합니다. 이 파일 (~/.gemini 폴더에 있음)을 수정하여 mcpServers 블록 내에 다음 스니펫을 추가해야 합니다. YOUR_PROJECT_ID를 실제 프로젝트 ID로 바꿉니다.

"logging-mcp": {
      "httpUrl": "https://logging.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/logging.read"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
}

참고: 관리형 MCP 서버에서 API 사용량과 청구가 프로젝트에 올바르게 귀속되도록 하려면 x-goog-user-project 헤더가 필요합니다.

작업 2: 프로젝트 활동 시뮬레이션 (로그 생성)

프로젝트가 새로 생성되었거나 유휴 상태인 경우 최근에 '흥미로운' 로그가 없을 수 있습니다. gcloud CLI를 사용하여 몇 가지 맞춤 항목을 삽입하여 에이전트가 찾을 수 있도록 합니다.

다음 명령어를 하나씩 실행하여 일련의 이벤트를 시뮬레이션합니다.

# 1. Simulate a standard system start
gcloud logging write mcp-test-log "System boot sequence initiated" --severity=INFO
# 2. Simulate a warning about resource limits
gcloud logging write mcp-test-log "High memory pressure detected in zone us-central1-a" --severity=WARNING
# 3. Simulate a critical authentication failure
gcloud logging write mcp-test-log "ERROR: Failed to connect to Cloud SQL. Permission Denied." --severity=ERROR

작업 3: Gemini CLI에서 도구 확인

채팅을 시작하기 전에 에이전트가 로깅 서버에서 노출된 도구를 '볼' 수 있는지 확인하겠습니다. Gemini CLI를 실행합니다.

gemini

Gemini CLI 프롬프트 (>) 내에서 list 명령어를 실행합니다.

/mcp list

확인 검문소: logging-mcp가 준비로 표시되고 list_log_entries를 포함하여 약 6개의 도구가 제공됩니다.

작업 4: 첫 번째 라이브 인프라 프롬프트

이제 에이전트에게 방금 만든 로그를 찾아 달라고 요청해 보겠습니다. 이전에 roles/logging.viewer 역할을 부여했으므로 이제 에이전트가 '연락'하여 프로젝트 상태를 읽을 수 있습니다.

Gemini CLI에 다음 프롬프트를 입력합니다.

Show me the 3 most recent log entries from the log named 'mcp-test-log'. What is the highest severity issue you see?

상담사 관찰:

에이전트가 Google Cloud 프로젝트 ID를 묻는 메시지를 표시할 수 있습니다. 이 정보를 제공해 주세요.
list_log_entries 도구가 필요하다고 식별합니다.
도구를 실행할 권한을 요청합니다. 1. 예, 한 번 허용합니다.
JSON 응답을 파싱하고 시뮬레이션한 Cloud SQL 권한 거부 오류에 대해 알려줍니다.

4. 여정 A: 브레인 (개발자 지식 MCP)

이 여정에서는 Google Developer Knowledge MCP 서버에 연결하여 에이전트에게 '두뇌'를 제공합니다.

AI 에이전트의 가장 큰 위험 중 하나는 할루시네이션입니다. 오래된 CLI 명령어 또는 지원 중단된 API 매개변수를 자신 있게 제공하는 것입니다. 이 MCP 서버는 Google Cloud, Firebase, Android 등을 다루는 Google의 공식 라이브 개발자 문서 코퍼스에 에이전트를 기반으로 하여 이 문제를 해결합니다.

작업 1: 지식 서비스 사용 설정

기본 단계와 마찬가지로 백엔드 API와 MCP 서비스 엔드포인트를 모두 사용 설정해야 합니다.

# 1. Enable the Developer Knowledge API
gcloud services enable developerknowledge.googleapis.com

# 2. Enable the MCP Server interface
gcloud beta services mcp enable developerknowledge.googleapis.com

작업 2: 제한된 API 키 프로비저닝

Developer Knowledge MCP는 인증에 API 키를 사용합니다. 보안을 위해 키를 생성하고 이 키가 특정 API에서만 사용될 수 있도록 제한합니다.

다음 스크립트를 실행하여 키를 만들고 검색합니다.

# Create the restricted API key
gcloud alpha services api-keys create \
    --display-name="MCP-Knowledge-Key" \
    --api-target service=developerknowledge.googleapis.com

# Wait a few seconds for the key to propagate, then fetch the string
gcloud alpha services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Knowledge-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

두 번째 명령어에서 반환된 긴 문자열을 복사합니다. YOUR_API_KEY입니다.

작업 3: Gemini CLI 구성

이제 Knowledge MCP 서버를 에이전트에 등록합니다. 이를 통해 에이전트는 100% 확실하게 대답할 수 없는 기술적 질문이 발생할 때마다 공식 문서를 검색할 수 있습니다.

~/.gemini/settings.json 파일의 mcpServers 섹션 내에 다음 스니펫을 추가하고 YOUR_API_KEY을 방금 복사한 문자열로 바꿉니다.

"developer-knowledge-mcp": {
      "httpUrl": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_API_KEY"
      }
}

작업 4: 과장 방지 테스트

이제 에이전트가 '추측'하는 대신 '조사'하는지 확인해 보겠습니다.

Gemini CLI를 실행합니다.

gemini

서버가 준비되었는지 확인합니다. /mcp list를 입력합니다. google-developer-knowledge에 2개의 도구 (search_documents, get_document)가 표시됩니다.

프롬프트: 상담사에게 특정 최신 명령어를 찾아 달라고 요청합니다.

I want to create a Google Cloud Storage bucket using the modern gcloud storage command. Search the official documentation for the exact syntax and show me an example for a bucket in the 'us-central1' region.

확인해야 할 사항:

Gemini에서 search_documents 사용 권한을 요청합니다.
그런 다음 get_document를 호출하여 찾은 특정 페이지를 읽을 가능성이 높습니다.
최종 답변에는 문서에서 직접 인용된 gcloud storage buckets create ... 명령어가 포함되어야 합니다.

5. 여정 B: 분류 (자동 문제 해결)

기본 요건: 이 여정에서는 상담사가 해결 방법을 조사할 수 있도록 여정 A: 브레인을 완료해야 합니다.

이 여정에서는 에이전트의 눈 (Cloud Logging MCP)과 두뇌 (개발자 지식 MCP)를 결합하여 자율 문제 해결 루프를 빌드합니다.

오류 코드를 검색엔진에 수동으로 복사하는 대신 에이전트에게 프로젝트에서 오류를 스캔하고, 공식 해결 방법을 조사하고, 실행 가능한 수정 보고서를 생성하라는 단일 프롬프트를 제공합니다.

작업 1: GCP에서 'Bad Day' 시뮬레이션

자율 문제 해결의 기능을 확인하려면 현실적인 실패 집합이 필요합니다. Python 스크립트를 사용하여 권한 거부 오류부터 할당량 문제까지 다양한 인프라 장애를 로그에 직접 삽입합니다.

Cloud Shell에서 원하는 폴더를 만들고 해당 폴더로 이동합니다.
simulate_errors.py이라는 파일을 만듭니다.

nano simulate_errors.py

다음 코드를 편집기에 붙여넣습니다.

import argparse
from google.cloud import logging

def simulate_errors(project_id):
    client = logging.Client(project=project_id)
    logger = client.logger("mcp-scenario-logger")

    print(f"Simulating realistic errors for project: {project_id}...")

    # 1. GCS Permission Error
    logger.log_text("ERROR: GCS Upload failed for 'gs://my-app-bucket/data.json'. Status: 403 Forbidden. Missing 'storage.objects.create' for service account.", severity="ERROR")

    # 2. Cloud Run Startup Error
    logger.log_text("ERROR: Cloud Run service 'api-gateway' failed to start. Container failed to listen on port 8080. Check 'Cloud Run container startup requirements'.", severity="ERROR")

    # 3. Secret Manager Access Error
    logger.log_text("ERROR: Access denied to secret 'API_KEY'. The identity lacks 'secretmanager.versions.access'.", severity="ERROR")

    print("Log entries written to 'mcp-scenario-logger'.")

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--project", required=True)
    args = parser.parse_args()
    simulate_errors(args.project)

Ctrl+O, Enter, Ctrl+X를 눌러 저장하고 종료합니다.
Google Cloud Logging 라이브러리를 설치하고 스크립트를 실행합니다.

python -m venv mcp_env
source mcp_env/bin/activate
pip install google-cloud-logging
python simulate_errors.py --project $(gcloud config get-value project)

작업 2: 자율 루프 실행

이제 Gemini가 두 MCP 서버를 동시에 오케스트레이션하도록 지시하는 복잡한 프롬프트를 실행합니다.

Gemini CLI를 실행합니다.

gemini

다음 '마스터 프롬프트'를 에이전트에 입력합니다.

I need to troubleshoot recent issues in my project. Perform the following autonomous loop:

Step 1 : Retrieval: Use the Logging MCP to fetch the 5 most recent ERROR entries from the log 'mcp-scenario-logger'.
Step 2 : Iteration: For every unique error found, extract the service and specific error message.
Step 3 : Research: Use the Developer Knowledge MCP to find the official resolution or gcloud command to fix each issue.
Step 4 : Resolution: Consolidate everything into a markdown table with columns: | Service | Error Summary | Recommended Fix |.

참고사항

이제 에이전트 워크플로를 실시간으로 시청하고 있습니다. 상담사는 다음 작업을 수행합니다.

list_log_entries를 호출하여 방금 시뮬레이션한 '나쁜 날'을 확인합니다.
텍스트를 분석하여 GCS, Cloud Run, Secret Manager가 실패하고 있음을 파악합니다.
각 서비스에 대해 search_documents 및 get_document를 호출하여 올바른 IAM 역할 또는 구성 수정사항을 찾습니다.
다음과 비슷한 구조화된 표를 표시합니다 (추천은 다를 수 있음).

서비스	오류 요약	권장 해결 방법
Cloud Storage	업로드 시 403 금지됨	서비스 계정에 `roles/storage.objectCreator` 권한을 부여합니다.
Cloud Run	포트 8080에서 수신 대기 실패	앱이 `$PORT`로 정의된 포트에서 0.0.0.0에 바인딩되어 있는지 확인합니다.
Secret Manager	버전 액세스 역할 누락	`roles/secretmanager.secretAccessor`을 ID에 할당합니다.

6. 여정 C: 데이터 (Firestore MCP)

이 여정에서는 Firestore MCP 서버를 사용하여 자연어만으로 NoSQL 문서 데이터베이스를 관리합니다.

Firestore는 유연하고 확장 가능한 데이터베이스이지만, 관리하려면 복잡한 SDK 코드를 작성하거나 콘솔을 탐색해야 하는 경우가 많습니다. MCP를 사용하면 에이전트가 채팅을 통해 데이터를 시딩하고, 레코드를 쿼리하고, 복잡한 스키마 마이그레이션까지 실행할 수 있는 데이터베이스 관리자가 됩니다.

작업 1: Firestore 서비스 사용 설정

먼저 Firestore API와 해당 MCP 엔드포인트를 사용 설정합니다.

# 1. Enable the Firestore API
gcloud services enable firestore.googleapis.com

# 2. Enable the MCP Server interface
gcloud beta services mcp enable firestore.googleapis.com

작업 2: Firestore IAM 역할 할당

쿼리를 실행하려면 기본 MCP 액세스 권한 외에 특정 권한이 필요합니다.

# Grant Firestore User role
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/datastore.user"

작업 3: 전용 테스트 데이터베이스 만들기

실험의 안전을 위해 mcp-lab-db라는 전용 Firestore 데이터베이스를 만듭니다.

gcloud firestore databases create --database=mcp-lab-db --location=nam5 --type=firestore-native

작업 4: Gemini CLI 구성

Firestore MCP 서버를 에이전트에 추가합니다. ~/.gemini/settings.json 파일의 mcpServers 섹션에 다음 구성을 추가합니다. YOUR_PROJECT_ID를 실제 프로젝트 ID로 바꿉니다.

"firestore-mcp": {
      "httpUrl": "https://firestore.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
}

작업 5: 자연어 DB 작업

Gemini CLI를 실행하고 몇 가지 기본 작업을 수행하여 연결을 확인합니다.

Gemini CLI를 실행합니다.

gemini

서버가 준비되었는지 확인합니다. /mcp list를 입력합니다. 여러 도구 (add_document, create_database, list_documents, etc)가 있는 firestore-mcp가 표시됩니다.

다음 프롬프트를 순서대로 사용해 보세요.

시드 데이터:

In the 'mcp-lab-db' database, add three documents to a 'products' collection. Include a laptop (stock 5), a mouse (stock 25), and a keyboard (stock 8).

확인:

List all documents in the 'products' collection from the 'mcp-lab-db' database.

자연어를 통해 Firestore 데이터베이스와 컬렉션을 관리하는 데 도움이 되는 다른 프롬프트를 사용해 보세요.

7. 여정 D: 인텔리전스 (BigQuery 및 지도)

이 여정에서는 BigQuery 및 Maps Grounding Lite MCP 서버를 사용하여 페타바이트 규모의 데이터를 분석하고 실제 세계를 이해하는 기능을 에이전트에 제공합니다.

이 섹션이 끝나면 에이전트가 자연어를 복잡한 SQL 쿼리로 변환하고, 대답을 현실에 기반하도록 맥락을 인식하는 지리 공간적 조언 (예: 이동 시간, 날씨)을 제공할 수 있습니다.

작업 1: 인텔리전스 서비스 사용 설정

BigQuery와 Google 지도의 API 및 MCP 인터페이스를 모두 사용 설정합니다.

# 1. Enable product APIs
gcloud services enable bigquery.googleapis.com mapstools.googleapis.com

# 2. Enable MCP Server interfaces
gcloud beta services mcp enable bigquery.googleapis.com
gcloud beta services mcp enable mapstools.googleapis.com

작업 2: BigQuery IAM 역할 할당

쿼리를 실행하려면 기본 MCP 액세스 권한 외에 특정 권한이 필요합니다.

# Grant BigQuery Job User and Data Viewer roles
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="user:$USER_EMAIL" \
    --role="roles/bigquery.dataViewer"

작업 3: 지도 API 키 프로비저닝

IAM만 사용하는 다른 서비스와 달리 Maps Grounding Lite 서버에는 할당량 및 결제를 위한 API 키가 필요합니다.

키를 만듭니다.

gcloud alpha services api-keys create --display-name="MCP-Maps-Key"

키 문자열 가져오기:

# Wait a few seconds for the key to propagate, then fetch the string
gcloud alpha services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Maps-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

다음 단계를 위해 키 문자열을 복사합니다.

작업 4: Gemini CLI 구성

이제 두 서버를 모두 등록합니다. 아래 스니펫을 ~/.gemini/settings.json 파일의 mcpServers 섹션에 추가합니다. YOUR_PROJECT_ID 및 YOUR_MAPS_API_KEY을 적절하게 바꿉니다.

"bigquery-mcp": {
      "httpUrl": "https://bigquery.googleapis.com/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": [
          "https://www.googleapis.com/auth/cloud-platform"
        ]
      },
      "timeout": 30000,
      "headers": {
        "x-goog-user-project": "YOUR_PROJECT_ID"
      }
},
"maps-grounding-lite-mcp": {
      "httpUrl": "https://mapstools.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_MAPS_API_KEY"
      }
}

작업 5: 인텔리전스 활용

Gemini CLI를 실행하고 새로운 'Intelligence' 기능을 테스트합니다.

gemini

서버가 준비되었는지 확인합니다. /mcp list를 입력합니다. bigquery-mcp 및 maps-grounding-lite-mcp이 표시되고 여러 도구가 나열됩니다. .

시나리오 1: 분석 엔진 (BigQuery) SQL을 모르는 상태에서 에이전트에게 공개 데이터 세트를 쿼리하도록 요청합니다.

Run a query to count the number of penguins on each island in the BigQuery public dataset ml_datasets.penguins.

시나리오 2: 지리 공간 컨텍스트 (지도) 에이전트에게 실제 여행을 계획해 달라고 요청합니다.

I am planning a drive from Mumbai to Pune tomorrow morning. Based on current weather and routing, what should I expect in terms of travel time and what should I carry?

확인해야 할 사항:

BigQuery의 경우 에이전트가 execute_sql를 호출하여 스키마를 검색하고 쿼리를 실행합니다.
지도에서는 lookup_weather를 오케스트레이션하고 compute_routes를 계산하여 근거가 있고 유용한 여행 계획을 제공합니다.

8. 강화: 프로덕션 보안 및 IAM

이 마지막 단계에서는 광범위한 '소유자' 권한을 사용하는 대신 프로덕션 등급 심층 방어 모델을 사용합니다.

AI 에이전트는 기본적으로 '유용'합니다. UI 수준에서 도구를 제한하면 스마트 에이전트가 셸 명령어를 실행하여 해당 제한을 우회하려고 시도할 수 있습니다. 인프라를 안전하게 보호하려면 Google Cloud IAM을 사용하여 강력한 경계를 구축해야 합니다.

이중 레이어 보안 모델

작업을 실행하려면 에이전트가 다음 두 관문을 통과해야 합니다.

1번 게이트 (MCP 게이트): ID에 roles/mcp.toolUser이 있나요? (프로토콜 사용 권한)
관문 2 (서비스 관문): ID에 특정 제품 역할 (예: roles/datastore.viewer)이 있나요? (데이터를 볼 수 있는 권한)

작업 1: 레이어 1 - 클라이언트 측 필터링 (`excludeTools`)

첫 번째 방어선은 에이전트가 도구를 사용한다는 '생각'조차 하지 않도록 도구를 숨기는 것입니다.

Cloud Shell 편집기에서 Gemini CLI 설정을 엽니다.

cloudshell edit ~/.gemini/settings.json

firestore-mcp 블록을 찾아 excludeTools 지시어를 추가하여 파괴적인 작업을 숨깁니다.

"firestore-mcp": {
  "httpUrl": "https://firestore.googleapis.com/mcp",
  "excludeTools": ["delete_database", "update_database", "delete_document"],
  ...
}

파일을 저장하고 Gemini CLI를 다시 시작합니다. /mcp list를 실행하면 이제 도구가 사라진 것을 확인할 수 있습니다.

작업 2: 2계층 - 인프라 우위 (IAM 바운서)

클라이언트 측 필터링은 '소프트' 가드레일입니다. 에이전트에게 '내 Firestore 데이터베이스 삭제'를 요청했는데 도구가 숨겨져 있으면 gcloud firestore databases delete를 실행하려고 할 수 있습니다. 이를 방지하기 위해 최소 권한 서비스 계정을 사용합니다.

'읽기 전용' 서비스 계정 만들기:

# Create the service account
gcloud iam service-accounts create mcp-reader-sa --display-name="MCP Reader Only"

# Grant ONLY the necessary roles (Gate 1 + Gate 2)
export PROJECT_ID=$(gcloud config get-value project)
SA_EMAIL="mcp-reader-sa@$PROJECT_ID.iam.gserviceaccount.com"

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/mcp.toolUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/datastore.viewer"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA_EMAIL" --role="roles/aiplatform.user"

키 생성 및 활성화:

gcloud iam service-accounts keys create reader-key.json --iam-account=$SA_EMAIL
export GOOGLE_APPLICATION_CREDENTIALS=$(pwd)/reader-key.json

작업 3: '유용한 에이전트' 바운서 테스트

이제 에이전트가 보안을 우회할 수 있는지 테스트해 보겠습니다.

첫 번째 단계는 서비스 계정을 활성화하는 것입니다. 이렇게 하면 에이전트가 gcloud 명령어를 사용하는 경우에도 방금 만든 서비스 계정 ID로 작동합니다.

서비스 계정 활성화:

다음 명령어를 실행하여 [PATH_TO_KEY_FILE] 을 JSON 키 파일의 실제 경로 (예: reader-key.json)로 바꿉니다.

gcloud auth activate-service-account --key-file=[PATH_TO_KEY_FILE]

변경사항 확인:

명령어를 실행한 후 다음을 실행하여 서비스 계정이 활성 상태인지 확인할 수 있습니다.

gcloud auth list

출력에 서비스 계정이 활성 사용자 인증 정보로 표시됩니다.

Gemini CLI 실행:

gemini

다음 프롬프트를 입력합니다.

I want to delete the 'mcp-lab-db' firestore database. If the tool is missing, try using the gcloud firestore command in the terminal.

발생하는 상황

에이전트는 먼저 Firestore MCP 서버에서 delete_database 도구를 사용하려고 시도합니다. 권한이 없으므로 실패합니다.
그런 다음 gcloud firestore 명령어를 사용하기 위해 run_shell_command 도구로 대체하여 '유용'하려고 시도합니다.

결과:

명령어가 Forbidden 오류와 함께 실패합니다. 에이전트가 mcp-reader-sa ID로 실행되므로 datastore.databases.delete 권한이 없습니다. IAM은 궁극적인 안전장치입니다. 에이전트가 리소스에 도달하려고 시도하는 방식과 관계없이 Google Cloud API 수준의 '바운서'가 요청을 차단합니다.

사용자 계정으로 다시 전환:

사용자 계정으로 다시 전환하려면 다음 명령어를 입력합니다.

gcloud config set account YOUR_EMAIL_ADDRESS

9. 삭제

원치 않는 요금이 청구되지 않도록 테스트 리소스를 삭제하세요.

# Delete the Firestore database
gcloud firestore databases delete --database=mcp-lab-db

# Remove the service account
gcloud iam service-accounts delete mcp-reader-sa@$PROJECT_ID.iam.gserviceaccount.com

10. 결론

축하합니다. Google 관리형 MCP 서버의 전체 스택을 성공적으로 탐색했습니다.

실습의 '트렁크'에서 Cloud Logging에 대한 기본 연결을 설정했습니다. 여기에서 에이전트의 지식을 기반으로 하고, 복잡한 문제 해결 루프를 자동화하고, Firestore에서 데이터를 이전하고, BigQuery 및 Maps에서 인텔리전스를 추출하는 모듈식 '어드벤처'로 확장했습니다.

가장 중요한 것은 프로덕션 보안의 기본에 에이전트를 고정하여 마무리했다는 점입니다. 에이전트가 과도하게 '유용'할 수 있지만 Google Cloud IAM은 궁극적인 보안 담당자로서 자율 워크플로가 항상 최소 권한의 원칙을 준수하도록 보장합니다.

핵심 요점

관리형 = 확장 가능: 단일 서버를 배포하지 않고 스트리밍 가능한 HTTP를 통해 인프라 수준 도구에 연결했습니다.
그라운딩 필수: LLM '추측'을 개발자 지식 MCP로 대체하여 에이전트가 현재의 유효한 명령어를 사용하도록 했습니다.
조정은 강력한 기능입니다. 에이전트가 여러 MCP 서버를 결합하여 단일 비즈니스 문제를 해결할 때 진정한 마법이 일어납니다.

Google MCP 서버 시작하기

1. 소개

'관리형'의 장점

학습할 내용

필요한 항목

문제 보고

2. 시작하기 전에

Cloud Shell 활성화

프로젝트 ID 설정

Foundation API 사용 설정

애플리케이션 기본 사용자 인증 정보 (ADC) 설정

기본 IAM 역할 할당

3. 기본 사항: 첫 번째 MCP 서버 연결

작업 1: 로깅 MCP 서버 구성

작업 2: 프로젝트 활동 시뮬레이션 (로그 생성)

작업 3: Gemini CLI에서 도구 확인

작업 4: 첫 번째 라이브 인프라 프롬프트

4. 여정 A: 브레인 (개발자 지식 MCP)

작업 1: 지식 서비스 사용 설정

작업 2: 제한된 API 키 프로비저닝

작업 3: Gemini CLI 구성

작업 4: 과장 방지 테스트

5. 여정 B: 분류 (자동 문제 해결)

작업 1: GCP에서 'Bad Day' 시뮬레이션

작업 2: 자율 루프 실행

6. 여정 C: 데이터 (Firestore MCP)

작업 1: Firestore 서비스 사용 설정

작업 2: Firestore IAM 역할 할당

작업 3: 전용 테스트 데이터베이스 만들기

작업 4: Gemini CLI 구성

작업 5: 자연어 DB 작업

7. 여정 D: 인텔리전스 (BigQuery 및 지도)

작업 1: 인텔리전스 서비스 사용 설정

작업 2: BigQuery IAM 역할 할당

작업 3: 지도 API 키 프로비저닝

작업 4: Gemini CLI 구성

작업 5: 인텔리전스 활용

8. 강화: 프로덕션 보안 및 IAM

이중 레이어 보안 모델

작업 1: 레이어 1 - 클라이언트 측 필터링 (excludeTools)

작업 2: 2계층 - 인프라 우위 (IAM 바운서)

작업 3: '유용한 에이전트' 바운서 테스트

9. 삭제

10. 결론

핵심 요점

작업 1: 레이어 1 - 클라이언트 측 필터링 (`excludeTools`)