1. 简介
欢迎!在此 Codelab 中,您将学习如何使用 Google 托管的 Model Context Protocol (MCP) 服务器来增强 AI 智能体的功能。
Model Context Protocol (MCP) 是一种开源标准,可让 AI 模型安全高效地连接到外部数据源和工具。虽然大多数 MCP 实现都在本地计算机上运行,但 Google 提供了托管式远程 MCP 服务器。这些是完全托管的企业级端点,可让代理直接与 Google Cloud 基础架构互动,而无需管理任何服务器端代码或容器。
“受管理”的优势
与使用标准输入/输出 (stdio) 的本地 MCP 服务器不同,Google 的托管服务器使用可流式 HTTP。此架构可提供:
- 零基础设施:无需预配或扩缩服务器。
- 设计安全性:与 Google Cloud IAM 和 Audit Logs 原生集成。
- 无状态扩缩:通过标准负载平衡器和代理实现无缝互动。
学习内容
- 如何启用和验证受管理的 MCP 服务器。
- 如何使用 Cloud Logging MCP 服务器作为基础基准。
- 如何编排多个 MCP 服务器(开发者知识、Firestore 等)来构建自主工作流。
所需条件
- 启用了结算功能的 Google Cloud 项目。
- 熟悉 Google Cloud 控制台和
gcloudCLI。 - Google Cloud Shell(此处已预安装 Gemini CLI)。
本 Codelab 适合不同水平的用户和开发者(包括新手)。
报告问题
在学习此 Codelab 并使用 Antigravity 时,您可能会遇到问题。
如果遇到与 Codelab 相关的问题(错别字、说明错误),请点击此 Codelab 左下角的 Report a mistake 按钮提交 bug:

2. 准备工作
在此步骤中,您将准备 Google Cloud 环境。我们将在 Google Cloud Shell 中执行所有任务,该 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
启用基础 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 服务目前处于 Beta 版 阶段。您必须使用 gcloud beta 组件才能启用这些功能。
设置应用默认凭证 (ADC)
Gemini CLI 使用您的用户身份与 MCP 服务器通信。授予代理代表您执行操作的权限:
gcloud auth application-default login
按照终端中的网址操作,登录账号,然后将授权代码粘贴回 Cloud Shell。
分配基础 IAM 角色
托管式 MCP 服务器使用双层安全模型。您需要打开两个特定的“门”:
- Gate 1(MCP 访问权限):允许您调用协议的角色。
- Gate 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 服务器,必须使用 x-goog-user-project 标头,以确保 API 用量和结算正确归因于您的项目。
任务 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 中的工具
在开始聊天之前,我们先验证代理是否可以“看到”Logging 服务器公开的工具。启动 Gemini CLI:
gemini
进入 Gemini CLI 提示符 (>) 后,运行 list 命令:
/mcp list
验证检查点:您应该会看到 logging-mcp 列为就绪,并提供大约 6 个工具,包括 list_log_entries。
任务 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. Yes, allow once(是,允许一次)。
- 它会解析 JSON 响应,并告知您我们模拟的 Cloud SQL 权限遭拒错误。
4. 历程 A:大脑(开发者知识 MCP)
在此学习之旅中,您将通过将智能体连接到 Google Developer Knowledge MCP 服务器,为智能体赋予“大脑”。
AI 智能体面临的最大风险之一是产生幻觉,即自信地提供过时的 CLI 命令或已弃用的 API 参数。此 MCP 服务器通过以下方式解决了该问题:让代理基于 Google 的官方实时开发者文档语料库(涵盖 Google Cloud、Firebase、Android 等)进行回答。
任务 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 密钥
开发者知识 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:Brain,以便代理可以研究修复方案。
在此历程中,您将结合智能体的眼睛(Cloud Logging MCP)和大脑(开发者知识 MCP)来构建自主问题排查循环。
您无需再手动将错误代码复制到搜索引擎中,只需向智能体提供一个提示,让其扫描项目中的错误、研究官方解决方案,并生成可行的修复报告。
任务 1:在 GCP 中模拟“糟糕的一天”
为了展示自主问题排查的强大功能,我们需要一组真实的故障。我们将使用 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 |.
预期结果
您现在正在实时观看 Agentic Workflow。智能体将:
- 调用
list_log_entries可查看我们刚刚模拟的“糟糕的一天”。 - 分析文本,以确定 GCS、Cloud Run 和 Secret Manager 是否出现故障。
- 针对每项服务分别调用
search_documents和get_document,以找到正确的 IAM 角色或配置修复。 - 向您显示一个结构化表格,该表格类似于以下内容(建议可能有所不同):
服务 | 错误摘要 | 建议的修复方法 |
Cloud Storage | 上传时显示“403 Forbidden”错误 | 向服务账号授予 |
Cloud Run | 无法监听端口 8080 | 确保应用绑定到 |
Secret Manager | 缺少版本访问角色 | 将 |
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:自然语言数据库操作
启动 Gemini CLI 并执行一些基本操作来验证连接。
启动 Gemini CLI:
gemini
验证服务器是否已准备就绪:输入 /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).
验证:
List all documents in the 'products' collection from the 'mcp-lab-db' database.
不妨尝试其他提示,以便通过自然语言管理 Firestore 数据库和集合。
7. 历程 D:智能(BigQuery 和 Maps)
在此学习历程中,您将使用 BigQuery 和 Maps Grounding Lite MCP 服务器,让智能体能够分析 PB 级数据并了解现实世界。
在本部分结束时,您的代理将能够将自然语言转换为复杂的 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 并测试新的“智能”功能。
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来发现架构并运行查询。 - 对于 Google 地图,它将协调
lookup_weather和 compute_routes,为您提供有依据的实用旅行计划。
8. 安全加固:生产环境安全和 IAM
在最后一步中,您将从使用广泛的“Owner”权限转为使用生产环境级纵深防御模型。
AI 智能体天生就是“有帮助”的。如果您在界面级限制某个工具,智能代理可能会尝试通过运行 shell 命令来绕过该限制。如需真正确保基础架构的安全,您必须使用 Google Cloud IAM 构建硬边界。
双层安全模型
若要执行任何操作,代理必须通过两个门:
- 关口 1(MCP 关口):身份是否具有
roles/mcp.toolUser?(使用该协议的权限)。 - Gate 2(服务门):身份是否具有特定的产品角色(例如
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:“有用的代理”Bouncer 测试
现在,我们来测试一下该代理是否可以绕过我们的安全措施。
我们的第一步是激活服务账号,这样即使代理回退到使用 gcloud 命令,它也会以我们刚刚创建的服务账号身份运行。
激活服务账号:
运行以下命令,并将 [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 工具。由于缺少权限,该操作将失败。
- 然后,它会尝试通过回退到
run_shell_command工具来使用 gcloud firestore 命令,从而“提供帮助”。
结果:
该命令失败,并显示“禁止”错误。由于代理是在 mcp-reader-sa 身份下运行的,因此缺少 datastore.databases.delete 权限。IAM 是最终的后盾。无论代理如何尝试访问资源,Google Cloud API 级别的“Bouncer”都会阻止该请求。
切换回您的用户账号:
如需切换回您的用户账号,请运行以下命令:
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 和 Google 地图 中提取情报。
最重要的是,您最终将代理锚定在生产安全性的根中。您证明了虽然代理可能会“帮倒忙”,但 Google Cloud IAM 是最终的门卫,可确保您的自主工作流程始终遵循最小权限原则。
重点小结
- 托管 = 可扩缩:您通过可流式传输的 HTTP 连接到基础架构级工具,而无需部署任何服务器。
- 建立依据是强制性的:您使用开发者知识库 MCP 替换了 LLM 的“猜测”,确保智能体使用当前有效的命令。
- 编排即力量:您已经看到,当智能体组合多个 MCP 服务器来解决单个业务问题时,真正的魔力就会显现出来。