شروع کار با سرورهای Google MCP

۱. مقدمه

خوش آمدید! در این آزمایشگاه کد، یاد خواهید گرفت که چگونه با استفاده از سرورهای پروتکل زمینه مدل مدیریت‌شده گوگل (MCP) عامل‌های هوش مصنوعی خود را تقویت کنید.

پروتکل زمینه مدل (MCP) یک استاندارد متن‌باز است که به مدل‌های هوش مصنوعی امکان می‌دهد تا به طور ایمن و کارآمد به منابع داده و ابزارهای خارجی متصل شوند. در حالی که اکثر پیاده‌سازی‌های MCP به صورت محلی روی دستگاه شما اجرا می‌شوند، گوگل سرورهای مدیریت‌شده MCP از راه دور را ارائه می‌دهد. این‌ها نقاط پایانی کاملاً میزبانی‌شده و آماده برای سازمان هستند که به نمایندگان شما اجازه می‌دهند بدون نیاز به مدیریت هیچ کد یا کانتینر سمت سرور، مستقیماً با زیرساخت Google Cloud تعامل داشته باشند.

مزیت «مدیریت‌شده»

برخلاف سرورهای محلی MCP که از ورودی/خروجی استاندارد (stdio) استفاده می‌کنند، سرورهای مدیریت‌شده گوگل از HTTP قابل پخش (Streamable HTTP ) استفاده می‌کنند. این معماری موارد زیر را ارائه می‌دهد:

  • زیرساخت صفر: هیچ سروری برای تأمین یا مقیاس‌پذیری وجود ندارد.
  • امنیت بر اساس طراحی: ادغام بومی با IAM و گزارش‌های حسابرسی Google Cloud.
  • مقیاس‌پذیری بدون وضعیت: تعامل یکپارچه از طریق متعادل‌کننده‌های بار استاندارد و پروکسی‌ها.

آنچه یاد خواهید گرفت

  • نحوه فعال‌سازی و احراز هویت سرورهای مدیریت‌شده MCP.
  • نحوه استفاده از سرور MCP Cloud Logging به عنوان یک مبنای اساسی.
  • چگونه چندین سرور MCP (دانش توسعه‌دهندگان، Firestore و غیره) را برای ایجاد گردش‌های کاری مستقل هماهنگ کنیم.

آنچه نیاز دارید

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب .
  • آشنایی با کنسول ابری گوگل و رابط خط فرمان gcloud
  • پوسته ابری گوگل (خط فرمان Antigravity از قبل نصب شده است).

این آزمایشگاه کد، برای کاربران و توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است.

گزارش مشکلات

همانطور که با آزمایشگاه کد و با Antigravity کار می‌کنید، ممکن است با مشکلاتی روبرو شوید.

برای مشکلات مربوط به codelab (غلط املایی، دستورالعمل‌های اشتباه)، لطفاً با استفاده از دکمه Report a mistake در گوشه پایین سمت چپ این codelab، یک اشکال (bug) ایجاد کنید:

b06b582bcd847f6d.png

۲. قبل از شروع

در این مرحله، محیط Google Cloud خود را آماده خواهید کرد. ما تمام وظایف را در Google Cloud Shell انجام خواهیم داد که یک ترمینال پایدار و از پیش پیکربندی شده را فراهم می‌کند.

فعال کردن پوسته ابری

  1. به کنسول ابری گوگل بروید.
  2. روی آیکون فعال‌سازی پوسته ابری در بالای سمت راست کلیک کنید.
  3. پس از شروع جلسه ترمینال، در صورت درخواست، اعلان را تأیید کنید.

شناسه پروژه خود را تنظیم کنید

مطمئن شوید که Cloud Shell شما به پروژه صحیح اشاره می‌کند:

# Set your active project
gcloud config set project YOUR_PROJECT_ID

# Verify the setting
gcloud config list project

فعال کردن API های Foundation

سرورهای مدیریت‌شده MCP نیاز به فعال بودن API محصول و رابط MCP دارند. با فعال کردن سرویس، رابط MCP مربوط به آن سرویس نیز فعال می‌شود.

دستور زیر را برای فعال کردن Cloud Logging backend (که مبنای ما برای این آزمایش است) اجرا کنید:

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

تنظیمات اعتبارنامه‌های پیش‌فرض برنامه (ADC)

رابط خط فرمان آنتی‌گراویتی از هویت کاربری شما برای ارتباط با سرورهای 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"

۳. مبانی: اتصال اولین سرور MCP شما

در این مرحله، شما عامل هوش مصنوعی خود (Antigravity CLI) را به سرور Google Cloud Logging MCP متصل خواهید کرد. این «اساس» ماست زیرا به عامل اجازه می‌دهد تا به صورت بلادرنگ ببیند که درون پروژه شما چه اتفاقی می‌افتد.

وظیفه ۱: پیکربندی سرور ثبت وقایع MCP

رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) از فایل mcp_config.json برای پیکربندی سرورهای MCP استفاده می‌کند. شما باید این فایل (که در پوشه ~/.gemini/config قرار دارد) را ویرایش کنید تا قطعه کد زیر را در بلوک mcpServers اضافه کنید. به جای YOUR_PROJECT_ID ، شناسه پروژه واقعی خود را قرار دهید:

"logging-mcp": {
      "url": "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"
      }
}

توجه : هدر x-goog-user-project برای سرورهای مدیریت‌شده MCP لازم است تا اطمینان حاصل شود که استفاده از API و پرداخت هزینه به درستی به پروژه شما نسبت داده می‌شود.

وظیفه ۲: شبیه‌سازی فعالیت پروژه (ایجاد گزارش‌ها)

اگر پروژه شما جدید یا غیرفعال است، ممکن است هیچ گزارش «جالب» جدیدی نداشته باشد. بیایید از رابط خط فرمان gcloud برای تزریق چند ورودی سفارشی استفاده کنیم تا عامل چیزی برای پیدا کردن داشته باشد.

برای شبیه‌سازی توالی رویدادها، این دستورات را یکی‌یکی اجرا کنید:

# 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

وظیفه ۳: تأیید ابزارها در Antigravity CLI

قبل از شروع چت، بیایید تأیید کنیم که آیا عامل می‌تواند ابزارهای نمایش داده شده توسط سرور ثبت وقایع را "ببیند". رابط خط فرمان Antigravity را اجرا کنید:

agy

وقتی وارد خط فرمان Antigravity CLI ( > ) شدید، دستور list را اجرا کنید:

/mcp list

نقطه بررسی تأیید: باید ببینید که logging-mcp به عنوان Ready فهرست شده و تقریباً 6 ابزار از جمله list_log_entries در آن موجود است.

وظیفه ۴: اولین درخواست زیرساخت زنده شما

حالا، بیایید از عامل بخواهیم گزارش‌هایی را که تازه ایجاد کرده‌ایم پیدا کند. از آنجایی که قبلاً نقش roles/logging.viewer را اعطا کرده‌اید، عامل اکنون می‌تواند «به شما دسترسی پیدا کند» و وضعیت پروژه شما را بخواند.

دستور زیر را در Antigravity CLI تایپ کنید:

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

به نماینده توجه کنید:

  1. ممکن است نماینده از شما شناسه پروژه گوگل کلود را بخواهد. لطفاً آن را ارائه دهید.
  2. تشخیص می‌دهد که به ابزار list_log_entries نیاز دارد.
  3. برای اجرای ابزارها از شما مجوزهایی درخواست خواهد شد. لطفاً این مجوز را بدهید.
  4. این ابزار پاسخ JSON را تجزیه و تحلیل می‌کند و خطای Cloud SQL Permission Denied که شبیه‌سازی کرده‌ایم را به شما اطلاع می‌دهد.

۴. سفر الف: مغز (دانش توسعه‌دهندگان MCP)

در این سفر، با اتصال نماینده خود به سرور MCP دانش توسعه‌دهندگان گوگل، به او یک «مغز» خواهید داد.

یکی از بزرگترین خطرات مربوط به عامل‌های هوش مصنوعی، توهم است، یعنی ارائه مطمئن دستورات CLI قدیمی یا پارامترهای API منسوخ شده. این سرور MCP با قرار دادن عامل در مجموعه اسناد رسمی و زنده توسعه‌دهندگان گوگل (شامل Google Cloud، Firebase، Android و موارد دیگر) این مشکل را حل می‌کند.

وظیفه ۱: فعال کردن سرویس‌های دانش

همانند مرحله پایه، باید API بک‌اند و نقطه پایانی سرویس MCP را فعال کنیم. 

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

وظیفه ۲: ارائه یک کلید API محدود

دانش توسعه‌دهندگان MCP از کلیدهای API برای احراز هویت استفاده می‌کند. برای امنیت، ما یک کلید ایجاد می‌کنیم و آن را محدود می‌کنیم تا فقط با این API خاص قابل استفاده باشد.

  1. برای ایجاد و بازیابی کلید خود، اسکریپت زیر را اجرا کنید: 
# Create the restricted API key
gcloud 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 services api-keys list \
   --filter="displayName='MCP-Knowledge-Key'" \
   --format="value(uid)"
  1. رشته طولانی کاراکترهای برگردانده شده توسط دستور دوم را کپی کنید. این YOUR_API_KEY شماست.

وظیفه ۳: پیکربندی رابط خط فرمان Antigravity

حالا، سرور Knowledge MCP را نزد نماینده خود ثبت کنید. این به نماینده اجازه می‌دهد هر زمان که با یک سوال فنی مواجه شد که نتوانست با اطمینان ۱۰۰٪ به آن پاسخ دهد، اسناد رسمی را جستجو کند.

قطعه کد زیر را در بخش mcpServers خود در فایل ~/.gemini/config/mcp_config.json اضافه کنید و YOUR_API_KEY با رشته‌ای که کپی کرده‌اید جایگزین کنید: 

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

وظیفه ۴: آزمون ضد توهم

بیایید بررسی کنیم که آیا عامل اکنون به جای «حدس زدن»، «در حال تحقیق» است یا خیر.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

تأیید آماده بودن سرور: عبارت /mcp list تایپ کنید. باید google-developer-knowledge به همراه ۳ ابزار ( search_documents, answer_query and get_documents ) مشاهده کنید.

سوال: از اپراتور بخواهید یک دستور خاص و مدرن پیدا کند. 

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.

چه چیزی را باید جستجو کرد:

  • مطمئن شوید که به طور صریح سرور MCP دانش توسعه‌دهندگان را برای فراخوانی فراخوانی می‌کنید. Gemini برای استفاده از ابزارهای خاص درخواست اجازه خواهد کرد.
  • پاسخ نهایی باید شامل دستور gcloud storage buckets create ... باشد که مستقیماً از مستندات ذکر شده است.

۵. سفر ب: تریاژ (عیب‌یابی خودکار)

پیش‌نیاز: این سفر مستلزم آن است که شما سفر الف: مغز را به پایان رسانده باشید تا مامور بتواند در مورد اصلاحات تحقیق کند.

در این مسیر، شما چشم‌های عامل خود (Cloud Logging MCP) و مغز (Developer Knowledge MCP) را برای ساخت یک حلقه عیب‌یابی خودکار ترکیب خواهید کرد.

به جای کپی کردن دستی کدهای خطا در موتور جستجو، به کارشناس یک پیام می‌دهید تا پروژه شما را برای یافتن خطاها اسکن کند، راه‌حل رسمی را بررسی کند و یک گزارش رفع اشکال قابل اجرا تهیه کند.

وظیفه ۱: شبیه‌سازی یک «روز بد» در GCP

برای دیدن قدرت عیب‌یابی خودکار، به مجموعه‌ای واقع‌بینانه از خرابی‌ها نیاز داریم. ما از یک اسکریپت پایتون برای تزریق انواع موانع زیرساختی - از خطاهای رد مجوز گرفته تا مشکلات سهمیه‌بندی - مستقیماً به گزارش‌های شما استفاده خواهیم کرد.

  1. در Cloud Shell، یک پوشه به دلخواه خود ایجاد کنید و به داخل آن بروید.
  2. یک فایل با نام simulate_errors.py ایجاد کنید: 
nano simulate_errors.py
  1. کد زیر را در ویرایشگر قرار دهید: 
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)
  1. برای ذخیره و خروج، کلیدهای Ctrl+O، Enter و Ctrl+X را فشار دهید.
  2. کتابخانه 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)

وظیفه ۲: اجرای حلقه خودمختار

اکنون، یک اعلان پیچیده اجرا می‌کنیم که به Antigravity CLI دستور می‌دهد هر دو سرور MCP را به‌طور همزمان هماهنگ کند.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

این "دستورالعمل اصلی" را در عامل تایپ کنید: 

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 |.

چه انتظاری باید داشت

اکنون شما در حال مشاهده‌ی گردش کار Agentic به صورت بلادرنگ هستید. Agent کارهای زیر را انجام خواهد داد:

  1. برای دیدن «روز بدی» که شبیه‌سازی کردیم، تابع list_log_entries را فراخوانی کنید.
  2. متن را تجزیه و تحلیل کنید تا مشخص شود که GCS، Cloud Run و Secret Manager از کار افتاده‌اند.
  3. برای یافتن نقش‌های صحیح IAM یا اصلاحات پیکربندی، برای هر یک از این سرویس‌ها search_documents و get_document را فراخوانی کنید.
  4. یک جدول ساختاریافته شبیه به این به شما ارائه می‌دهد (توصیه‌ها ممکن است متفاوت باشند):

ce3907897f1e05e7.png

۶. سفر C: داده‌ها (Firestore MCP)

در این سفر، شما از Firestore MCP Server برای مدیریت یک پایگاه داده سند NoSQL با استفاده از زبان طبیعی استفاده خواهید کرد.

فایراستور یک پایگاه داده انعطاف‌پذیر و مقیاس‌پذیر است، اما مدیریت آن اغلب نیاز به نوشتن کد پیچیده SDK یا پیمایش کنسول دارد. با MCP، عامل شما به یک مدیر پایگاه داده تبدیل می‌شود که قادر به بارگذاری داده‌ها، پرس‌وجو از رکوردها و حتی انجام مهاجرت‌های پیچیده طرحواره از طریق چت است.

وظیفه ۱: فعال کردن سرویس‌های Firestore

ابتدا، API فایراستور و نقطه پایانی MCP مربوط به آن را فعال کنید. 

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

وظیفه 2: اختصاص نقش‌های IAM در Firestore

برای اجرای کوئری‌ها، هویت شما به مجوزهای خاصی فراتر از دسترسی پایه MCP نیاز دارد. 

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

وظیفه ۳: ایجاد یک پایگاه داده تست اختصاصی

برای ایمن نگه داشتن آزمایش‌هایمان، یک پایگاه داده اختصاصی Firestore با نام mcp-lab-db ایجاد خواهیم کرد. 

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

وظیفه ۴: پیکربندی رابط خط فرمان Antigravity

سرور Firestore MCP را به نماینده خود اضافه کنید. پیکربندی زیر را به بخش mcpServers در فایل ~/.gemini/settings.json اضافه کنید. YOUR_PROJECT_ID را با شناسه پروژه واقعی خود جایگزین کنید: 

"firestore-mcp": {
      "url": "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"
      }
}

وظیفه ۵: عملیات پایگاه داده زبان طبیعی

Antigravity CLI را اجرا کنید و چند عملیات اولیه برای تأیید اتصال انجام دهید.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

تأیید کنید که سرور آماده است: دستور /mcp list تایپ کنید. باید firestore-mcp به همراه چندین ابزار ( add_document, create_database, list_documents, etc ) مشاهده کنید.

این دستورالعمل‌ها را به ترتیب امتحان کنید:

داده‌های بذر: 

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).

تأیید کنید: 

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

سایر دستورالعمل‌هایی را که به شما در مدیریت پایگاه‌های داده و مجموعه‌های Firestore از طریق زبان طبیعی کمک می‌کنند، امتحان کنید.

۷. سفر D: هوش (BigQuery و Maps)

در این مسیر، شما با استفاده از سرورهای BigQuery و Maps Grounding Lite MCP، به کارشناس خود توانایی تجزیه و تحلیل پتابایت‌ها داده و درک دنیای فیزیکی را خواهید داد.

در پایان این بخش، عامل شما قادر خواهد بود زبان طبیعی را به پرس‌وجوهای پیچیده SQL ترجمه کند و توصیه‌های مکانی-مکانی آگاه از متن (مانند زمان سفر و آب و هوا) ارائه دهد تا پاسخ‌های خود را بر اساس واقعیت بنا کند.

وظیفه ۱: فعال کردن سرویس‌های اطلاعاتی

رابط‌های API و MCP را برای BigQuery و Google Maps فعال کنید. 

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

وظیفه ۲: اختصاص نقش‌های IAM در BigQuery

برای اجرای کوئری‌ها، هویت شما به مجوزهای خاصی فراتر از دسترسی پایه 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"

وظیفه ۳: ارائه کلید API نقشه‌ها

برخلاف سایر سرویس‌هایی که صرفاً به IAM متکی هستند، سرور Maps Grounding Lite برای سهمیه‌بندی و صدور صورتحساب به یک کلید API نیاز دارد.

کلید را ایجاد کنید: 

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

رشته کلید را دریافت کنید:

چند ثانیه صبر کنید تا کلید منتشر شود، سپس رشته را دریافت کنید. 

gcloud services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Maps-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

رشته کلید را برای مرحله بعدی کپی کنید .

وظیفه ۴: پیکربندی رابط خط فرمان Antigravity

حالا هر دو سرور را ثبت کنید. قطعه کدهای زیر را به بخش mcpServers در فایل ~/.gemini/settings.json اضافه کنید. YOUR_PROJECT_ID و YOUR_MAPS_API_KEY را به ترتیب جایگزین کنید. 

"bigquery-mcp": {
      "url": "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": {
      "url": "https://mapstools.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_MAPS_API_KEY"
      }
}

وظیفه ۵: هوش در عمل

رابط خط فرمان Antigravity را اجرا کنید و قابلیت‌های جدید «هوش» را آزمایش کنید. 

agy

تأیید کنید که سرور آماده است: عبارت /mcp list تایپ کنید. باید bigquery-mcp و maps-grounding-lite-mcp به همراه چندین ابزار فهرست شده ببینید.

سناریو ۱: موتور تحلیلی (BigQuery) از عامل بخواهید بدون اینکه شما هیچ SQL بدانید، از یک مجموعه داده عمومی پرس‌وجو کند: 

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

سناریو ۲: زمینه جغرافیایی (نقشه‌ها) از نماینده بخواهید یک سفر در دنیای واقعی را برنامه‌ریزی کند: 

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 را هماهنگ می‌کند تا یک برنامه سفر مفید و مطمئن به شما ارائه دهد.

۸. مقاوم‌سازی: امنیت تولید و IAM

در این مرحله نهایی، شما از استفاده از مجوزهای گسترده "مالک" به یک مدل دفاع در عمق سطح تولید (Production-Grade Defense-in-Depth) منتقل خواهید شد.

عامل‌های هوش مصنوعی ذاتاً «مفید» هستند. اگر ابزاری را در سطح رابط کاربری محدود کنید، یک عامل هوشمند ممکن است سعی کند با اجرای یک دستور shell از آن محدودیت عبور کند. برای ایمن‌سازی واقعی زیرساخت خود، باید با استفاده از Google Cloud IAM مرزهای سختی ایجاد کنید.

مدل امنیتی دولایه

برای اجرای هر عملی، یک عامل باید از دو دروازه عبور کند:

  1. دروازه ۱ (دروازه MCP): آیا هویت roles/mcp.toolUser دارد؟ (مجوز استفاده از پروتکل).
  2. دروازه ۲ (دروازه سرویس): آیا هویت، نقش خاص محصول (مثلاً roles/datastore.viewer ) را دارد؟ (مجوز مشاهده داده‌ها).

وظیفه ۱: لایه ۱ - فیلترینگ سمت کلاینت ( excludeTools )

اولین لایه دفاعی، پنهان کردن ابزارها از عامل است، به طوری که حتی به استفاده از آنها "فکر" هم نکند.

  1. تنظیمات Antigravity CLI خود را در ویرایشگر Cloud Shell باز کنید: 
cloudshell edit ~/.gemini/config/settings.json
  1. بلوک firestore-mcp را پیدا کنید و دستورالعمل excludeTools را برای پنهان کردن اقدامات مخرب اضافه کنید: 
"firestore-mcp": {
  "url": "https://firestore.googleapis.com/mcp",
  "excludeTools": ["delete_database", "update_database", "delete_document"],
  ...
}

فایل را ذخیره کنید و Antigravity CLI را مجدداً راه اندازی کنید. /mcp list را اجرا کنید و متوجه خواهید شد که آن ابزارها اکنون از بین رفته اند.

وظیفه ۲: لایه ۲ - برتری زیرساخت (IAM Bouncer)

فیلترینگ سمت کلاینت یک مانع «نرم» است. اگر از عامل بخواهید «پایگاه داده 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

وظیفه ۳: آزمون بازتاب «عامل مفید»

حالا، بیایید بررسی کنیم که آیا عامل می‌تواند از سد امنیتی ما عبور کند یا خیر.

اولین قدم ما فعال کردن حساب کاربری سرویس (Service Account) خواهد بود، به طوری که حتی اگر عامل دوباره به استفاده از دستور gcloud روی آورد، تحت هویت حساب کاربری سرویسی که ما تازه ایجاد کرده‌ایم، عمل کند.

فعال کردن حساب کاربری سرویس:

دستور زیر را اجرا کنید و [PATH_TO_KEY_FILE] را با مسیر واقعی فایل کلید JSON خود (مثلاً reader-key.json ) جایگزین کنید. 

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

تغییر را تأیید کنید:

پس از اجرای دستور، می‌توانید با اجرای دستور زیر از فعال بودن حساب سرویس اطمینان حاصل کنید: 

gcloud auth list

خروجی، حساب کاربری سرویس را به عنوان اعتبارنامه فعال نشان می‌دهد.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

این دستور را تایپ کنید: 

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

چه اتفاقی می‌افتد؟

  1. عامل ابتدا سعی می‌کند از ابزار delete_database در سرور Firestore MCP استفاده کند. این کار به دلیل عدم مجوز با شکست مواجه خواهد شد.
  2. سپس با مراجعه به ابزار run_shell_command برای استفاده از دستور gcloud firestore، سعی می‌کند «مفید» باشد.

نتیجه:

دستور با خطای Forbidden اجرا نمی‌شود. از آنجا که عامل تحت هویت mcp-reader-sa در حال اجرا است، فاقد مجوز datastore.databases.delete است. IAM پشتیبان نهایی است. مهم نیست که عامل چگونه سعی در دسترسی به منبع داشته باشد، "Bouncer" در سطح Google Cloud API درخواست را مسدود می‌کند.

به حساب کاربری خود برگردید:

برای بازگشت به حساب کاربری خود، دستور زیر را وارد کنید: 

gcloud config set account YOUR_EMAIL_ADDRESS

۹. پاکسازی

برای جلوگیری از هزینه‌های ناخواسته، منابع آزمایشی خود را حذف کنید: 

# 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

۱۰. نتیجه‌گیری

تبریک! شما با موفقیت به تمام سرورهای مدیریت‌شده‌ی MCP گوگل دسترسی پیدا کردید.

شما با «ترانک» آزمایشگاه شروع کردید و یک اتصال بنیادی به Cloud Logging برقرار کردید. از آنجا، به «ماجراجویی‌های» ماژولار روی آوردید - پایه‌گذاری دانش عامل خود، خودکارسازی حلقه‌های عیب‌یابی پیچیده، انتقال داده‌ها در Firestore و استخراج اطلاعات از BigQuery و Maps .

از همه مهم‌تر، شما با تثبیت عامل خود در ریشه‌های امنیت تولید، کار را به پایان رساندید. شما ثابت کردید که اگرچه یک عامل می‌تواند در مواقع بروز خطا «مفید» باشد، اما Google Cloud IAM بهترین راه حل است و تضمین می‌کند که گردش‌های کاری مستقل شما همیشه اصل حداقل امتیاز را رعایت کنند.

نکات کلیدی

  • مدیریت‌شده = مقیاس‌پذیر: شما از طریق Streamable HTTP بدون استقرار حتی یک سرور، به ابزارهای سطح زیرساخت متصل شدید.
  • اتصال به زمین اجباری است: شما «حدس زدن» LLM را با « دانش توسعه‌دهنده» MCP جایگزین کردید و مطمئن شدید که عامل شما از دستورات معتبر و به‌روز استفاده می‌کند.
  • هماهنگی قدرت است: دیدید که جادوی واقعی زمانی اتفاق می‌افتد که یک اپراتور چندین سرور MCP را برای حل یک مشکل تجاری واحد ترکیب می‌کند.
 ،

۱. مقدمه

خوش آمدید! در این آزمایشگاه کد، یاد خواهید گرفت که چگونه با استفاده از سرورهای پروتکل زمینه مدل مدیریت‌شده گوگل (MCP) عامل‌های هوش مصنوعی خود را تقویت کنید.

پروتکل زمینه مدل (MCP) یک استاندارد متن‌باز است که به مدل‌های هوش مصنوعی امکان می‌دهد تا به طور ایمن و کارآمد به منابع داده و ابزارهای خارجی متصل شوند. در حالی که اکثر پیاده‌سازی‌های MCP به صورت محلی روی دستگاه شما اجرا می‌شوند، گوگل سرورهای مدیریت‌شده MCP از راه دور را ارائه می‌دهد. این‌ها نقاط پایانی کاملاً میزبانی‌شده و آماده برای سازمان هستند که به نمایندگان شما اجازه می‌دهند بدون نیاز به مدیریت هیچ کد یا کانتینر سمت سرور، مستقیماً با زیرساخت Google Cloud تعامل داشته باشند.

مزیت «مدیریت‌شده»

برخلاف سرورهای محلی MCP که از ورودی/خروجی استاندارد (stdio) استفاده می‌کنند، سرورهای مدیریت‌شده گوگل از HTTP قابل پخش (Streamable HTTP ) استفاده می‌کنند. این معماری موارد زیر را ارائه می‌دهد:

  • زیرساخت صفر: هیچ سروری برای تأمین یا مقیاس‌پذیری وجود ندارد.
  • امنیت بر اساس طراحی: ادغام بومی با IAM و گزارش‌های حسابرسی Google Cloud.
  • مقیاس‌پذیری بدون وضعیت: تعامل یکپارچه از طریق متعادل‌کننده‌های بار استاندارد و پروکسی‌ها.

آنچه یاد خواهید گرفت

  • نحوه فعال‌سازی و احراز هویت سرورهای مدیریت‌شده MCP.
  • نحوه استفاده از سرور MCP Cloud Logging به عنوان یک مبنای اساسی.
  • چگونه چندین سرور MCP (دانش توسعه‌دهندگان، Firestore و غیره) را برای ایجاد گردش‌های کاری مستقل هماهنگ کنیم.

آنچه نیاز دارید

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب .
  • آشنایی با کنسول ابری گوگل و رابط خط فرمان gcloud
  • پوسته ابری گوگل (خط فرمان Antigravity از قبل نصب شده است).

این آزمایشگاه کد، برای کاربران و توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است.

گزارش مشکلات

همانطور که با آزمایشگاه کد و با Antigravity کار می‌کنید، ممکن است با مشکلاتی روبرو شوید.

برای مشکلات مربوط به codelab (غلط املایی، دستورالعمل‌های اشتباه)، لطفاً با استفاده از دکمه Report a mistake در گوشه پایین سمت چپ این codelab، یک اشکال (bug) ایجاد کنید:

b06b582bcd847f6d.png

۲. قبل از شروع

در این مرحله، محیط Google Cloud خود را آماده خواهید کرد. ما تمام وظایف را در Google Cloud Shell انجام خواهیم داد که یک ترمینال پایدار و از پیش پیکربندی شده را فراهم می‌کند.

فعال کردن پوسته ابری

  1. به کنسول ابری گوگل بروید.
  2. روی آیکون فعال‌سازی پوسته ابری در بالای سمت راست کلیک کنید.
  3. پس از شروع جلسه ترمینال، در صورت درخواست، اعلان را تأیید کنید.

شناسه پروژه خود را تنظیم کنید

مطمئن شوید که Cloud Shell شما به پروژه صحیح اشاره می‌کند:

# Set your active project
gcloud config set project YOUR_PROJECT_ID

# Verify the setting
gcloud config list project

فعال کردن API های Foundation

سرورهای مدیریت‌شده MCP نیاز به فعال بودن API محصول و رابط MCP دارند. با فعال کردن سرویس، رابط MCP مربوط به آن سرویس نیز فعال می‌شود.

دستور زیر را برای فعال کردن Cloud Logging backend (که مبنای ما برای این آزمایش است) اجرا کنید:

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

تنظیمات اعتبارنامه‌های پیش‌فرض برنامه (ADC)

رابط خط فرمان آنتی‌گراویتی از هویت کاربری شما برای ارتباط با سرورهای 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"

۳. مبانی: اتصال اولین سرور MCP شما

در این مرحله، شما عامل هوش مصنوعی خود (Antigravity CLI) را به سرور Google Cloud Logging MCP متصل خواهید کرد. این «اساس» ماست زیرا به عامل اجازه می‌دهد تا به صورت بلادرنگ ببیند که درون پروژه شما چه اتفاقی می‌افتد.

وظیفه ۱: پیکربندی سرور ثبت وقایع MCP

رابط خط فرمان آنتی‌گراویتی (Antigravity CLI) از فایل mcp_config.json برای پیکربندی سرورهای MCP استفاده می‌کند. شما باید این فایل (که در پوشه ~/.gemini/config قرار دارد) را ویرایش کنید تا قطعه کد زیر را در بلوک mcpServers اضافه کنید. به جای YOUR_PROJECT_ID ، شناسه پروژه واقعی خود را قرار دهید:

"logging-mcp": {
      "url": "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"
      }
}

توجه : هدر x-goog-user-project برای سرورهای مدیریت‌شده MCP لازم است تا اطمینان حاصل شود که استفاده از API و پرداخت هزینه به درستی به پروژه شما نسبت داده می‌شود.

وظیفه ۲: شبیه‌سازی فعالیت پروژه (ایجاد گزارش‌ها)

اگر پروژه شما جدید یا غیرفعال است، ممکن است هیچ گزارش «جالب» جدیدی نداشته باشد. بیایید از رابط خط فرمان gcloud برای تزریق چند ورودی سفارشی استفاده کنیم تا عامل چیزی برای پیدا کردن داشته باشد.

برای شبیه‌سازی توالی رویدادها، این دستورات را یکی‌یکی اجرا کنید:

# 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

وظیفه ۳: تأیید ابزارها در Antigravity CLI

قبل از شروع چت، بیایید تأیید کنیم که آیا عامل می‌تواند ابزارهای نمایش داده شده توسط سرور ثبت وقایع را "ببیند". رابط خط فرمان Antigravity را اجرا کنید:

agy

وقتی وارد خط فرمان Antigravity CLI ( > ) شدید، دستور list را اجرا کنید:

/mcp list

نقطه بررسی تأیید: باید ببینید که logging-mcp به عنوان Ready فهرست شده و تقریباً 6 ابزار از جمله list_log_entries در آن موجود است.

وظیفه ۴: اولین درخواست زیرساخت زنده شما

حالا، بیایید از عامل بخواهیم گزارش‌هایی را که تازه ایجاد کرده‌ایم پیدا کند. از آنجایی که قبلاً نقش roles/logging.viewer را اعطا کرده‌اید، عامل اکنون می‌تواند «به شما دسترسی پیدا کند» و وضعیت پروژه شما را بخواند.

دستور زیر را در Antigravity CLI تایپ کنید:

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

به نماینده توجه کنید:

  1. ممکن است نماینده از شما شناسه پروژه گوگل کلود را بخواهد. لطفاً آن را ارائه دهید.
  2. تشخیص می‌دهد که به ابزار list_log_entries نیاز دارد.
  3. برای اجرای ابزارها از شما مجوزهایی درخواست خواهد شد. لطفاً این مجوز را بدهید.
  4. این ابزار پاسخ JSON را تجزیه و تحلیل می‌کند و خطای Cloud SQL Permission Denied که شبیه‌سازی کرده‌ایم را به شما اطلاع می‌دهد.

۴. سفر الف: مغز (دانش توسعه‌دهندگان MCP)

در این سفر، با اتصال نماینده خود به سرور MCP دانش توسعه‌دهندگان گوگل، به او یک «مغز» خواهید داد.

یکی از بزرگترین خطرات مربوط به عامل‌های هوش مصنوعی، توهم است، یعنی ارائه مطمئن دستورات CLI قدیمی یا پارامترهای API منسوخ شده. این سرور MCP با قرار دادن عامل در مجموعه اسناد رسمی و زنده توسعه‌دهندگان گوگل (شامل Google Cloud، Firebase، Android و موارد دیگر) این مشکل را حل می‌کند.

وظیفه ۱: فعال کردن سرویس‌های دانش

همانند مرحله پایه، باید API بک‌اند و نقطه پایانی سرویس MCP را فعال کنیم. 

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

وظیفه ۲: ارائه یک کلید API محدود

دانش توسعه‌دهندگان MCP از کلیدهای API برای احراز هویت استفاده می‌کند. برای امنیت، ما یک کلید ایجاد می‌کنیم و آن را محدود می‌کنیم تا فقط با این API خاص قابل استفاده باشد.

  1. برای ایجاد و بازیابی کلید خود، اسکریپت زیر را اجرا کنید: 
# Create the restricted API key
gcloud 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 services api-keys list \
   --filter="displayName='MCP-Knowledge-Key'" \
   --format="value(uid)"
  1. رشته طولانی کاراکترهای برگردانده شده توسط دستور دوم را کپی کنید. این YOUR_API_KEY شماست.

وظیفه ۳: پیکربندی رابط خط فرمان Antigravity

حالا، سرور Knowledge MCP را نزد نماینده خود ثبت کنید. این به نماینده اجازه می‌دهد هر زمان که با یک سوال فنی مواجه شد که نتوانست با اطمینان ۱۰۰٪ به آن پاسخ دهد، اسناد رسمی را جستجو کند.

قطعه کد زیر را در بخش mcpServers خود در فایل ~/.gemini/config/mcp_config.json اضافه کنید و YOUR_API_KEY با رشته‌ای که کپی کرده‌اید جایگزین کنید: 

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

وظیفه ۴: آزمون ضد توهم

بیایید بررسی کنیم که آیا عامل اکنون به جای «حدس زدن»، «در حال تحقیق» است یا خیر.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

تأیید آماده بودن سرور: عبارت /mcp list تایپ کنید. باید google-developer-knowledge به همراه ۳ ابزار ( search_documents, answer_query and get_documents ) مشاهده کنید.

سوال: از اپراتور بخواهید یک دستور خاص و مدرن پیدا کند. 

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.

چه چیزی را باید جستجو کرد:

  • مطمئن شوید که به طور صریح سرور MCP دانش توسعه‌دهندگان را برای فراخوانی فراخوانی می‌کنید. Gemini برای استفاده از ابزارهای خاص درخواست اجازه خواهد کرد.
  • پاسخ نهایی باید شامل دستور gcloud storage buckets create ... باشد که مستقیماً از مستندات ذکر شده است.

۵. سفر ب: تریاژ (عیب‌یابی خودکار)

پیش‌نیاز: این سفر مستلزم آن است که شما سفر الف: مغز را به پایان رسانده باشید تا مامور بتواند در مورد اصلاحات تحقیق کند.

در این مسیر، شما چشم‌های عامل خود (Cloud Logging MCP) و مغز (Developer Knowledge MCP) را برای ساخت یک حلقه عیب‌یابی خودکار ترکیب خواهید کرد.

به جای کپی کردن دستی کدهای خطا در موتور جستجو، به کارشناس یک پیام می‌دهید تا پروژه شما را برای یافتن خطاها اسکن کند، راه‌حل رسمی را بررسی کند و یک گزارش رفع اشکال قابل اجرا تهیه کند.

وظیفه ۱: شبیه‌سازی یک «روز بد» در GCP

برای دیدن قدرت عیب‌یابی خودکار، به مجموعه‌ای واقع‌بینانه از خرابی‌ها نیاز داریم. ما از یک اسکریپت پایتون برای تزریق انواع موانع زیرساختی - از خطاهای رد مجوز گرفته تا مشکلات سهمیه‌بندی - مستقیماً به گزارش‌های شما استفاده خواهیم کرد.

  1. در Cloud Shell، یک پوشه به دلخواه خود ایجاد کنید و به داخل آن بروید.
  2. یک فایل با نام simulate_errors.py ایجاد کنید: 
nano simulate_errors.py
  1. کد زیر را در ویرایشگر قرار دهید: 
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)
  1. برای ذخیره و خروج، کلیدهای Ctrl+O، Enter و Ctrl+X را فشار دهید.
  2. کتابخانه 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)

وظیفه ۲: اجرای حلقه خودمختار

اکنون، یک اعلان پیچیده اجرا می‌کنیم که به Antigravity CLI دستور می‌دهد هر دو سرور MCP را به‌طور همزمان هماهنگ کند.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

این "دستورالعمل اصلی" را در عامل تایپ کنید: 

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 |.

چه انتظاری باید داشت

اکنون شما در حال مشاهده‌ی گردش کار Agentic به صورت بلادرنگ هستید. Agent کارهای زیر را انجام خواهد داد:

  1. برای دیدن «روز بدی» که شبیه‌سازی کردیم، تابع list_log_entries را فراخوانی کنید.
  2. متن را تجزیه و تحلیل کنید تا مشخص شود که GCS، Cloud Run و Secret Manager از کار افتاده‌اند.
  3. برای یافتن نقش‌های صحیح IAM یا اصلاحات پیکربندی، برای هر یک از این سرویس‌ها search_documents و get_document را فراخوانی کنید.
  4. یک جدول ساختاریافته شبیه به این به شما ارائه می‌دهد (توصیه‌ها ممکن است متفاوت باشند):

ce3907897f1e05e7.png

۶. سفر C: داده‌ها (Firestore MCP)

در این سفر، شما از Firestore MCP Server برای مدیریت یک پایگاه داده سند NoSQL با استفاده از زبان طبیعی استفاده خواهید کرد.

فایراستور یک پایگاه داده انعطاف‌پذیر و مقیاس‌پذیر است، اما مدیریت آن اغلب نیاز به نوشتن کد پیچیده SDK یا پیمایش کنسول دارد. با MCP، عامل شما به یک مدیر پایگاه داده تبدیل می‌شود که قادر به بارگذاری داده‌ها، پرس‌وجو از رکوردها و حتی انجام مهاجرت‌های پیچیده طرحواره از طریق چت است.

وظیفه ۱: فعال کردن سرویس‌های Firestore

ابتدا، API فایراستور و نقطه پایانی MCP مربوط به آن را فعال کنید. 

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

وظیفه 2: اختصاص نقش‌های IAM در Firestore

برای اجرای کوئری‌ها، هویت شما به مجوزهای خاصی فراتر از دسترسی پایه MCP نیاز دارد. 

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

وظیفه ۳: ایجاد یک پایگاه داده تست اختصاصی

برای ایمن نگه داشتن آزمایش‌هایمان، یک پایگاه داده اختصاصی Firestore با نام mcp-lab-db ایجاد خواهیم کرد. 

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

وظیفه ۴: پیکربندی رابط خط فرمان Antigravity

سرور Firestore MCP را به نماینده خود اضافه کنید. پیکربندی زیر را به بخش mcpServers در فایل ~/.gemini/settings.json اضافه کنید. YOUR_PROJECT_ID را با شناسه پروژه واقعی خود جایگزین کنید: 

"firestore-mcp": {
      "url": "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"
      }
}

وظیفه ۵: عملیات پایگاه داده زبان طبیعی

Antigravity CLI را اجرا کنید و چند عملیات اولیه برای تأیید اتصال انجام دهید.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

تأیید کنید که سرور آماده است: دستور /mcp list تایپ کنید. باید firestore-mcp به همراه چندین ابزار ( add_document, create_database, list_documents, etc ) مشاهده کنید.

این دستورالعمل‌ها را به ترتیب امتحان کنید:

داده‌های بذر: 

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).

تأیید کنید: 

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

سایر دستورالعمل‌هایی را که به شما در مدیریت پایگاه‌های داده و مجموعه‌های Firestore از طریق زبان طبیعی کمک می‌کنند، امتحان کنید.

۷. سفر D: هوش (BigQuery و Maps)

در این مسیر، شما با استفاده از سرورهای BigQuery و Maps Grounding Lite MCP، به کارشناس خود توانایی تجزیه و تحلیل پتابایت‌ها داده و درک دنیای فیزیکی را خواهید داد.

در پایان این بخش، عامل شما قادر خواهد بود زبان طبیعی را به پرس‌وجوهای پیچیده SQL ترجمه کند و توصیه‌های مکانی-مکانی آگاه از متن (مانند زمان سفر و آب و هوا) ارائه دهد تا پاسخ‌های خود را بر اساس واقعیت بنا کند.

وظیفه ۱: فعال کردن سرویس‌های اطلاعاتی

رابط‌های API و MCP را برای BigQuery و Google Maps فعال کنید. 

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

وظیفه ۲: اختصاص نقش‌های IAM در BigQuery

برای اجرای کوئری‌ها، هویت شما به مجوزهای خاصی فراتر از دسترسی پایه 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"

وظیفه ۳: ارائه کلید API نقشه‌ها

برخلاف سایر سرویس‌هایی که صرفاً به IAM متکی هستند، سرور Maps Grounding Lite برای سهمیه‌بندی و صدور صورتحساب به یک کلید API نیاز دارد.

کلید را ایجاد کنید: 

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

رشته کلید را دریافت کنید:

چند ثانیه صبر کنید تا کلید منتشر شود، سپس رشته را دریافت کنید. 

gcloud services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Maps-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

رشته کلید را برای مرحله بعدی کپی کنید .

وظیفه ۴: پیکربندی رابط خط فرمان Antigravity

حالا هر دو سرور را ثبت کنید. قطعه کدهای زیر را به بخش mcpServers در فایل ~/.gemini/settings.json اضافه کنید. YOUR_PROJECT_ID و YOUR_MAPS_API_KEY را به ترتیب جایگزین کنید. 

"bigquery-mcp": {
      "url": "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": {
      "url": "https://mapstools.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_MAPS_API_KEY"
      }
}

وظیفه ۵: هوش در عمل

رابط خط فرمان Antigravity را اجرا کنید و قابلیت‌های جدید «هوش» را آزمایش کنید. 

agy

تأیید کنید که سرور آماده است: عبارت /mcp list تایپ کنید. باید bigquery-mcp و maps-grounding-lite-mcp به همراه چندین ابزار فهرست شده ببینید.

سناریو ۱: موتور تحلیلی (BigQuery) از عامل بخواهید بدون اینکه شما هیچ SQL بدانید، از یک مجموعه داده عمومی پرس‌وجو کند: 

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

سناریو ۲: زمینه جغرافیایی (نقشه‌ها) از نماینده بخواهید یک سفر در دنیای واقعی را برنامه‌ریزی کند: 

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 را هماهنگ می‌کند تا یک برنامه سفر مفید و مطمئن به شما ارائه دهد.

۸. مقاوم‌سازی: امنیت تولید و IAM

در این مرحله نهایی، شما از استفاده از مجوزهای گسترده "مالک" به یک مدل دفاع در عمق سطح تولید (Production-Grade Defense-in-Depth) منتقل خواهید شد.

عامل‌های هوش مصنوعی ذاتاً «مفید» هستند. اگر ابزاری را در سطح رابط کاربری محدود کنید، یک عامل هوشمند ممکن است سعی کند با اجرای یک دستور shell از آن محدودیت عبور کند. برای ایمن‌سازی واقعی زیرساخت خود، باید با استفاده از Google Cloud IAM مرزهای سختی ایجاد کنید.

مدل امنیتی دولایه

برای اجرای هر عملی، یک عامل باید از دو دروازه عبور کند:

  1. دروازه ۱ (دروازه MCP): آیا هویت roles/mcp.toolUser دارد؟ (مجوز استفاده از پروتکل).
  2. دروازه ۲ (دروازه سرویس): آیا هویت، نقش خاص محصول (مثلاً roles/datastore.viewer ) را دارد؟ (مجوز مشاهده داده‌ها).

وظیفه ۱: لایه ۱ - فیلترینگ سمت کلاینت ( excludeTools )

اولین لایه دفاعی، پنهان کردن ابزارها از عامل است، به طوری که حتی به استفاده از آنها "فکر" هم نکند.

  1. تنظیمات Antigravity CLI خود را در ویرایشگر Cloud Shell باز کنید: 
cloudshell edit ~/.gemini/config/settings.json
  1. بلوک firestore-mcp را پیدا کنید و دستورالعمل excludeTools را برای پنهان کردن اقدامات مخرب اضافه کنید: 
"firestore-mcp": {
  "url": "https://firestore.googleapis.com/mcp",
  "excludeTools": ["delete_database", "update_database", "delete_document"],
  ...
}

فایل را ذخیره کنید و Antigravity CLI را مجدداً راه اندازی کنید. /mcp list را اجرا کنید و متوجه خواهید شد که آن ابزارها اکنون از بین رفته اند.

وظیفه ۲: لایه ۲ - برتری زیرساخت (IAM Bouncer)

فیلترینگ سمت کلاینت یک مانع «نرم» است. اگر از عامل بخواهید «پایگاه داده 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

وظیفه ۳: آزمون بازتاب «عامل مفید»

حالا، بیایید بررسی کنیم که آیا عامل می‌تواند از سد امنیتی ما عبور کند یا خیر.

اولین قدم ما فعال کردن حساب کاربری سرویس (Service Account) خواهد بود، به طوری که حتی اگر عامل دوباره به استفاده از دستور gcloud روی آورد، تحت هویت حساب کاربری سرویسی که ما تازه ایجاد کرده‌ایم، عمل کند.

فعال کردن حساب کاربری سرویس:

دستور زیر را اجرا کنید و [PATH_TO_KEY_FILE] را با مسیر واقعی فایل کلید JSON خود (مثلاً reader-key.json ) جایگزین کنید. 

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

تغییر را تأیید کنید:

پس از اجرای دستور، می‌توانید با اجرای دستور زیر از فعال بودن حساب سرویس اطمینان حاصل کنید: 

gcloud auth list

خروجی، حساب کاربری سرویس را به عنوان اعتبارنامه فعال نشان می‌دهد.

اجرای رابط خط فرمان آنتی‌گراویتی: 

agy

این دستور را تایپ کنید: 

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

چه اتفاقی می‌افتد؟

  1. The agent will first attempt to use the delete_database tool in the Firestore MCP Server. It will fail because of lack of permission.
  2. It then attempts to be "helpful" by falling back to the run_shell_command tool to use the gcloud firestore command.

The Result:

The command fails with a Forbidden error. Because the agent is running under the mcp-reader-sa identity, it lacks the datastore.databases.delete permission. IAM is the ultimate backstop. No matter how the agent tries to reach the resource, the "Bouncer" at the Google Cloud API level will block the request.

Switch back to your user account:

To switch back to your user account, give the following command: 

gcloud config set account YOUR_EMAIL_ADDRESS

9. Cleanup

To avoid unwanted charges, delete your test resources: 

# 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

۱۰. نتیجه‌گیری

Congratulations! You've successfully navigated the full stack of Google Managed MCP Servers .

You started with the "Trunk" of the lab, establishing a foundational connection to Cloud Logging . From there, you branched out into modular "Adventures"—grounding your agent's knowledge, automating complex troubleshooting loops, migrating data in Firestore , and extracting intelligence from BigQuery and Maps .

Most importantly, you finished by anchoring your agent in the Roots of production security. You proved that while an agent can be "helpful" to a fault, Google Cloud IAM is the ultimate bouncer, ensuring that your autonomous workflows always respect the Principle of Least Privilege.

نکات کلیدی

  • Managed = Scalable: You connected to infrastructure-level tools via Streamable HTTP without deploying a single server.
  • Grounding is Mandatory: You replaced LLM "guessing" with the Developer Knowledge MCP , ensuring your agent uses current, valid commands.
  • Orchestration is Power: You saw that the true magic happens when an agent combines multiple MCP servers to solve a single business problem.
 ،

۱. مقدمه

Welcome! In this codelab, you will learn how to supercharge your AI agents using Google Managed Model Context Protocol (MCP) Servers .

The Model Context Protocol (MCP) is an open-source standard that enables AI models to safely and efficiently connect to external data sources and tools. While most MCP implementations run locally on your machine, Google provides Managed Remote MCP Servers . These are fully hosted, enterprise-ready endpoints that allow your agents to interact directly with Google Cloud infrastructure without you having to manage any server-side code or containers.

The "Managed" Advantage

Unlike local MCP servers that use standard input/output (stdio), Google's managed servers utilize Streamable HTTP . This architecture offers:

  • Zero Infrastructure: No servers to provision or scale.
  • Security by Design: Native integration with Google Cloud IAM and Audit Logs.
  • Stateless Scaling: Seamless interaction through standard load balancers and proxies.

آنچه یاد خواهید گرفت

  • How to enable and authenticate Managed MCP Servers.
  • How to use the Cloud Logging MCP Server as a foundational baseline.
  • How to orchestrate multiple MCP servers (Developer Knowledge, Firestore, etc.) to build autonomous workflows.

آنچه نیاز دارید

  • A Google Cloud Project with billing enabled .
  • Familiarity with the Google Cloud Console and gcloud CLI.
  • Google Cloud Shell (Antigravity CLI is pre-installed here).

This codelab, designed for users and developers of all levels (including beginners).

Reporting issues

As you work through the codelab and with Antigravity, you might encounter problems.

For codelab related issues (typos, wrong instructions), please open a bug with Report a mistake button in bottom left corner of this codelab:

b06b582bcd847f6d.png

2. Before You Begin

In this step, you will prepare your Google Cloud environment. We will be performing all tasks within Google Cloud Shell , which provides a persistent, pre-configured terminal.

فعال کردن پوسته ابری

  1. Navigate to the Google Cloud Console .
  2. Click the Activate Cloud Shell icon in the top right header.
  3. Once the terminal session starts, authorize the prompt if asked.

Set your Project ID

Ensure your Cloud Shell is pointing to the correct project:

# Set your active project
gcloud config set project YOUR_PROJECT_ID

# Verify the setting
gcloud config list project

Enable Foundation APIs

Managed MCP servers require both the underlying product API and the MCP interface to be enabled. By enabling the service, the underlying MCP interface for the service will also get enabled.

Run the following command to enable the Cloud Logging backend (our baseline for this lab):

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

Setup Application Default Credentials (ADC)

Antigravity CLI uses your user identity to communicate with MCP servers. Grant the agent permission to act on your behalf:

gcloud auth application-default login

Follow the URL in the terminal, sign in, and paste the authorization code back into Cloud Shell.

Assign Foundational IAM Roles

Managed MCP servers use a Dual-Layer security model. You need two specific gates that you need to get validated at or for the gates to be open:

  1. Gate 1 (MCP Access): The role that allows you to call the protocol.
  2. Gate 2 (Service Access): The role that allows you to see the data (eg, viewing logs).

Run the following to grant yourself the required access:

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. Foundations: Connecting Your First MCP Server

In this step, you will link your AI agent (Antigravity CLI) to the Google Cloud Logging MCP Server . This is our "foundation" because it allows the agent to see what is happening inside your project in real-time.

Task 1: Configure the Logging MCP Server

Antigravity CLI uses a mcp_config.json file to configure the MCP Servers. You will need to edit this file (present in ~/.gemini/config folder) to add the following snippet inside the mcpServers block. Replace YOUR_PROJECT_ID with your actual Project ID:

"logging-mcp": {
      "url": "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"
      }
}

Note : The x-goog-user-project header is required for Managed MCP servers to ensure that API usage and billing are correctly attributed to your project.

Task 2: Simulate Project Activity (Create Logs)

If your project is new or idle, it might not have any recent "interesting" logs. Let's use the gcloud CLI to inject a few custom entries so the agent has something to find.

Run these commands one by one to simulate a sequence of events:

# 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

Task 3: Verify Tools in Antigravity CLI

Before we start chatting, let's verify that the agent can "see" the tools exposed by the Logging server. Launch the Antigravity CLI:

agy

Once inside the Antigravity CLI prompt ( > ), run the list command:

/mcp list

Verification Checkpoint: You should see logging-mcp listed as Ready with approximately 6 tools available, including list_log_entries .

Task 4: Your First Live Infrastructure Prompt

Now, let's ask the agent to find the logs we just created. Because you granted the roles/logging.viewer role earlier, the agent can now "reach out" and read your project state.

Type the following prompt into the Antigravity CLI:

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

Observe the Agent:

  1. The Agent might prompt you for the Google Cloud Project Id. Please provide that.
  2. It will identify that it needs the list_log_entries tool.
  3. It will ask for your permissions to run the tools. Please allow that.
  4. It will parse the JSON response and tell you about the Cloud SQL Permission Denied error we simulated.

4. Journey A: The Brain (Developer Knowledge MCP)

In this journey, you will give your agent a "brain" by connecting it to the Google Developer Knowledge MCP Server .

One of the biggest risks with AI agents is hallucination ie confidently providing outdated CLI commands or deprecated API parameters. This MCP server solves that by grounding the agent in Google's official, live developer documentation corpus (covering Google Cloud, Firebase, Android, and more).

Task 1: Enable the Knowledge Services

As with our foundation step, we must enable the backend API and the MCP service endpoint. 

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

Task 2: Provision a Restricted API Key

The Developer Knowledge MCP uses API Keys for authentication. For security, we will create a key and restrict it so it can only be used with this specific API.

  1. Run the following script to create and retrieve your key: 
# Create the restricted API key
gcloud 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 services api-keys list \
   --filter="displayName='MCP-Knowledge-Key'" \
   --format="value(uid)"
  1. Copy the long string of characters returned by the second command. This is your YOUR_API_KEY .

Task 3: Configure Antigravity CLI

Now, register the Knowledge MCP server with your agent. This allows the agent to search the official docs whenever it encounters a technical question it can't answer with 100% certainty.

Add the following snippet inside your mcpServers section in ~/.gemini/config/mcp_config.json file, replacing YOUR_API_KEY with the string you just copied: 

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

Task 4: The Anti-Hallucination Test

Let's verify that the agent is now "researching" instead of "guessing."

Launch Antigravity CLI: 

agy

Verify the server is Ready: Type /mcp list . You should see google-developer-knowledge with 3 tools ( search_documents, answer_query and get_documents ).

The Prompt: Ask the agent to find a specific, modern command. 

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.

What to look for:

  • Make sure that you explicitly call out the Developer Knowledge MCP Server to be invoked. Gemini will ask for permission to use specific tools.
  • The final answer should include a gcloud storage buckets create ... command, cited directly from the documentation.

5. Journey B: The Triage (Autonomous Troubleshooting)

Prerequisite: This journey requires you to have completed Journey A: The Brain so the agent can research fixes.

In this journey, you will combine your agent's Eyes (Cloud Logging MCP) and Brain (Developer Knowledge MCP) to build an Autonomous Troubleshooting Loop .

Instead of manually copying error codes into a search engine, you will give the agent a single prompt to scan your project for errors, research the official resolution, and generate an actionable fix report.

Task 1: Simulate a "Bad Day" in GCP

To see the power of autonomous troubleshooting, we need a realistic set of failures. We will use a Python script to inject a variety of infrastructure hurdles—from permission denied errors to quota issues—directly into your logs.

  1. In Cloud Shell, create a folder of your choice and navigate into it.
  2. create a file named simulate_errors.py : 
nano simulate_errors.py
  1. Paste the following code into the editor: 
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)
  1. Press Ctrl+O, Enter, and Ctrl+X to save and exit.
  2. Install the Google Cloud Logging library and run the script: 
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)

Task 2: Execute the Autonomous Loop

Now, we will fire a complex prompt that instructs Antigravity CLI to orchestrate both MCP servers simultaneously.

Launch Antigravity CLI: 

agy

Type this "Master Prompt" into the agent: 

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 |.

چه انتظاری باید داشت

You are now watching an Agentic Workflow in real-time. The agent will:

  1. Call list_log_entries to see the "Bad Day" we just simulated.
  2. Analyze the text to identify that GCS, Cloud Run, and Secret Manager are failing.
  3. Call search_documents and get_document for each of those services to find the correct IAM roles or configuration fixes.
  4. Present you with a structured table that looks similar to this (the recommendations could differ):

ce3907897f1e05e7.png

6. Journey C: The Data (Firestore MCP)

In this journey, you will use the Firestore MCP Server to manage a NoSQL document database using nothing but natural language.

Firestore is a flexible, scalable database, but managing it often requires writing complex SDK code or navigating the console. With MCP, your agent becomes a Database Administrator , capable of seeding data, querying records, and even performing complex schema migrations via chat.

Task 1: Enable Firestore Services

First, enable the Firestore API and its corresponding MCP endpoint. 

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

Task 2: Assign Firestore IAM Roles

To run queries, your identity needs specific permissions beyond the basic MCP access. 

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

Task 3: Create a Dedicated Test Database

To keep our experiments safe, we will create a dedicated Firestore database named mcp-lab-db . 

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

Task 4: Configure Antigravity CLI

Add the Firestore MCP server to your agent. Add the following configuration to the mcpServers section in the ~/.gemini/settings.json file. Replace YOUR_PROJECT_ID with your actual Project ID: 

"firestore-mcp": {
      "url": "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"
      }
}

Task 5: Natural Language DB Ops

Launch Antigravity CLI and perform some basic operations to verify the connection.

Launch Antigravity CLI: 

agy

Verify the server is Ready: Type /mcp list . You should see firestore-mcp with several tools ( add_document, create_database, list_documents, etc ).

Try these prompts in order:

Seed Data: 

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).

Verify: 

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

Do try out other prompts that help you manage Firestore databases and collections via natural language.

7. Journey D: Intelligence (BigQuery & Maps)

In this journey, you will equip your agent with the ability to analyze petabytes of data and understand the physical world using the BigQuery and Maps Grounding Lite MCP servers.

By the end of this section, your agent will be able to translate natural language into complex SQL queries and provide context-aware geospatial advice (like travel times and weather) to ground its responses in reality.

Task 1: Enable Intelligence Services

Enable the APIs and MCP interfaces for both BigQuery and Google Maps. 

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

Task 2: Assign BigQuery IAM Roles

To run queries, your identity needs specific permissions beyond the basic MCP access. 

# 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"

Task 3: Provision a Maps API Key

Unlike other services that rely solely on IAM, the Maps Grounding Lite server requires an API Key for quota and billing.

Create the key: 

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

Fetch the key string:

Wait a few seconds for the key to propagate, then fetch the string. 

gcloud services api-keys get-key-string \
    $(gcloud alpha services api-keys list \
    --filter="displayName='MCP-Maps-Key'" \
    --format="value(name)") \
    --format="value(keyString)"

Copy the key string for the next step.

Task 4: Configure Antigravity CLI

Now, register both servers. Add the snippets below to the mcpServers section in the ~/.gemini/settings.json file. Replace YOUR_PROJECT_ID and YOUR_MAPS_API_KEY accordingly. 

"bigquery-mcp": {
      "url": "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": {
      "url": "https://mapstools.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_MAPS_API_KEY"
      }
}

Task 5: Intelligence in Action

Launch Antigravity CLI and test the new "Intelligence" capabilities. 

agy

Verify the server is Ready: Type /mcp list . You should see bigquery-mcp and maps-grounding-lite-mcp with several tools listed. .

Scenario 1: The Analytical Engine (BigQuery) Ask the agent to query a public dataset without you knowing any SQL: 

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

Scenario 2: Geospatial Context (Maps) Ask the agent to plan a real-world trip: 

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?

What to look for:

  • For BigQuery, the agent will call execute_sql to discover the schema and run the query.
  • For Maps, it will orchestrate lookup_weather and compute_routes to give you a grounded, helpful travel plan.

8. Hardening: Production Security & IAM

In this final step, you will move from using broad "Owner" permissions to a Production-Grade Defense-in-Depth model.

AI agents are "helpful" by nature. If you restrict a tool at the UI level, a smart agent might attempt to bypass that restriction by running a shell command instead. To truly secure your infrastructure, you must build hard boundaries using Google Cloud IAM .

The Dual-Layer Security Model

To execute any action, an agent must pass through two gates:

  1. Gate 1 (The MCP Gate): Does the identity have roles/mcp.toolUser ? (Permission to use the protocol).
  2. Gate 2 (The Service Gate): Does the identity have the specific product role (eg, roles/datastore.viewer )? (Permission to see the data).

Task 1: Layer 1 - Client-Side Filtering ( excludeTools )

The first layer of defense is hiding tools from the agent so it doesn't even "think" about using them.

  1. Open your Antigravity CLI settings in the Cloud Shell editor: 
cloudshell edit ~/.gemini/config/settings.json
  1. Find the firestore-mcp block and add the excludeTools directive to hide destructive actions: 
"firestore-mcp": {
  "url": "https://firestore.googleapis.com/mcp",
  "excludeTools": ["delete_database", "update_database", "delete_document"],
  ...
}

Save the file and restart Antigravity CLI. Run /mcp list and notice those tools are now gone.

Task 2: Layer 2 - Infrastructure Supremacy (The IAM Bouncer)

Client-side filtering is a "soft" guardrail. If you ask the agent to "Delete my Firestore database," and the tool is hidden, it might try to run gcloud firestore databases delete . To prevent this, we use a Least Privilege Service Account.

Create a "Reader-Only" Service Account: 

# 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"

Generate and Activate the Key: 

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

Task 3: The "Helpful Agent" Bouncer Test

Now, let's test if the agent can bypass our security.

Our first step will be to activate the Service Account, so that even if the agent falls back on using gcloud command, it operates under the service account identity that we have just created.

Activate the Service Account:

Run the following command, replacing [PATH_TO_KEY_FILE] with the actual path to your JSON key file (eg, reader-key.json ). 

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

Verify the Change:

After running the command, you can verify that the service account is active by running: 

gcloud auth list

The output will show the service account as the active credential.

Launch Antigravity CLI: 

agy

Type this prompt: 

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

چه اتفاقی می‌افتد؟

  1. The agent will first attempt to use the delete_database tool in the Firestore MCP Server. It will fail because of lack of permission.
  2. It then attempts to be "helpful" by falling back to the run_shell_command tool to use the gcloud firestore command.

The Result:

The command fails with a Forbidden error. Because the agent is running under the mcp-reader-sa identity, it lacks the datastore.databases.delete permission. IAM is the ultimate backstop. No matter how the agent tries to reach the resource, the "Bouncer" at the Google Cloud API level will block the request.

Switch back to your user account:

To switch back to your user account, give the following command: 

gcloud config set account YOUR_EMAIL_ADDRESS

9. Cleanup

To avoid unwanted charges, delete your test resources: 

# 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

۱۰. نتیجه‌گیری

Congratulations! You've successfully navigated the full stack of Google Managed MCP Servers .

You started with the "Trunk" of the lab, establishing a foundational connection to Cloud Logging . From there, you branched out into modular "Adventures"—grounding your agent's knowledge, automating complex troubleshooting loops, migrating data in Firestore , and extracting intelligence from BigQuery and Maps .

Most importantly, you finished by anchoring your agent in the Roots of production security. You proved that while an agent can be "helpful" to a fault, Google Cloud IAM is the ultimate bouncer, ensuring that your autonomous workflows always respect the Principle of Least Privilege.

نکات کلیدی

  • Managed = Scalable: You connected to infrastructure-level tools via Streamable HTTP without deploying a single server.
  • Grounding is Mandatory: You replaced LLM "guessing" with the Developer Knowledge MCP , ensuring your agent uses current, valid commands.
  • Orchestration is Power: You saw that the true magic happens when an agent combines multiple MCP servers to solve a single business problem.