注意：此文档集适用于 Gemini Enterprise 的 Standard 版、Plus 版、随用随付版和一线员工版。如需查看 Business 版文档，请参阅 Gemini Enterprise - Business 版帮助中心。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

设置具有 VPC 连接的自定义 MCP 服务器数据存储区的前提条件

本页面介绍了通过 Virtual Private Cloud (VPC) 网络将 Gemini Enterprise 流量路由到自定义 Model Context Protocol (MCP) 服务器所需的前提条件和网络基础设施。如果您的 MCP 服务器托管在 VPC 网络内，或者托管在公共网络中且需要来自静态 IP 地址的请求，请使用此设置。

概览

默认情况下，Gemini Enterprise 无法访问托管在专用网络内的资源。为了让 Gemini Enterprise 与您基础设施中的私有工具或操作安全通信，您需要通过 Egress Agent Gateway 将流量路由到您的私有 VPC 网络。

此连接模型支持以下部署用例：

专用网络托管：您的专用 MCP 服务器在专用 VPC 网络中运行，没有公共 IP 地址。
混合云和多云连接：通过混合网络连接跨多云或本地环境部署的私有 MCP 服务器上的操作。
公共 MCP 服务器的静态 IP 出站流量：通过 VPC 网络和 Cloud NAT 将出站流量路由到公开托管的 MCP 服务器，以便请求源自目标服务器可以允许的预留静态外部 IPv4 地址。

您可以通过声明方式定义此连接。代理连接模板包含您的出站流量配置：要使用的网络连接、要以私密方式解析的网域，以及要通过 VPC 网络路由的流量。然后，出站流量 Agent Gateway 会引用该模板来访问您的自定义 MCP 服务器。

您创建了以下三个资源：

Agent Gateway 用于在 VPC 网络中部署 Private Service Connect 接口以实现出站流量的 Private Service Connect 网络连接。
一个智能体连接模板，该模板指向该网络连接，并定义 DNS 对等互连和出站流量路由行为。
一个 Agent Gateway，用于引用模板并路由应用的出站请求。

验证要求和权限

在预配网络基础设施之前，请验证您的项目资源、API 和 Identity and Access Management (IAM) 权限。

资源要求

确保您的 Google Cloud环境中有以下资源。根据您的应用场景，您需要使用私有 MCP 服务器或公共 MCP 服务器。

所需资源	说明
专用 VPC 网络	一个安全的 VPC 网络，其中包含您要连接到 Gemini Enterprise 的基础设施和工作负载。
Agent Gateway 和连接性模板	`us-central1` 或 `europe-west1` 中与智能体连接模板关联的区域级出站流量 Agent Gateway。连接模板指定了 Private Service Connect 接口网络连接、DNS 对等互连设置和 VPC 出站流量路由模式，用于连接到您的 VPC，从而让 Gemini Enterprise 将出站请求路由到您的自定义 MCP 服务器。如需了解详情，请参阅 Agent Gateway 概览和为 Agent Gateway 设置 VPC 连接。
TrustConfig （可选）	可选。一个 Certificate Manager `TrustConfig` 资源，用于定义自定义根和中间 CA 受信任证书存储区（或许可清单中的证书）。您可以在代理连接模板中引用此资源，以便 Agent Gateway 验证与使用私有 CA 或自签名证书的私有 MCP 服务器的出站 TLS 连接。如需了解详情，请参阅 TLS 证书要求。
私有 MCP 服务器（用于私有托管）	一个实现 Model Context Protocol 并托管内部操作或数据的服务器。此服务器在您的 VPC 网络中私下运行，并使用 `StreamableHTTP` 传输。如果您的私有 MCP 服务器使用私有域名（例如 `mcp.cymbal.internal`），则在获得 DNS Peer (`roles/dns.peer`) 角色并在代理连接模板中配置 `dnsPeeringConfig` 后，Google 服务代理会通过私有 DNS 对等互连解析域名。如需了解详情，请参阅创建代理连接模板。
公共 MCP 服务器（用于静态 IP 出站流量）	一个实现 MCP 的服务器，可通过公共端点使用 `StreamableHTTP` 传输协议访问，并且要求请求来自静态外部 IPv4 地址：公有云 Cloud DNS 解析：不需要专用 Cloud DNS 对等互连；服务器通过标准公共 DNS 进行解析。网关出站流量配置：在代理连接模板中，将 `vpcEgress` 设置为 `ALL_TRAFFIC`，以通过 Private Service Connect 接口将发往互联网的请求路由到 VPC 网络。使用 Cloud NAT 的确定性出站流量：在分配给网络连接的子网上，使用预留的静态外部 IPv4 地址配置 Cloud NAT，以便目标 MCP 服务器可以允许来自源 IP 地址的请求。 VPC 路由继承：注入到 VPC 网络的流量遵循 VPC 路由表，例如默认互联网网关路由 (`0.0.0.0/0`) 或下一个跃点防火墙设备。
认证服务器（可选）	可选。如果您的私有 MCP 服务器需要 OAuth 2.0 认证，则需要在私有 VPC 网络中运行认证服务器。

启用必需的 API

在部署 Agent Gateway 和 Gemini Enterprise 应用的 Google Cloud 项目中，启用所需的最低限度 API：

Compute Engine API (compute.googleapis.com)：提供核心网络基础设施、子网、路由和 Private Service Connect 网络连接。
Network Connectivity API (networkconnectivity.googleapis.com)：管理跨项目和共享 VPC 网络端点。
网络安全 API (networksecurity.googleapis.com)：为网关流量创建和强制执行授权政策 (authzPolicies)。
Network Services API (networkservices.googleapis.com)：管理 Agent Gateway 资源 (agentGateways) 和连接模板 (agentConnectivityTemplates)。
Service Extensions API (serviceextensions.googleapis.com)：创建和管理授权扩展 (authzExtensions)，以用于 Identity-Aware Proxy (IAP) 委托授权。
Identity and Access Management API (iam.googleapis.com)：管理代理身份的服务账号和 IAM 统一访问权限政策 (UAP)。
Identity-Aware Proxy API (iap.googleapis.com)：对代理、端点和服务器流量进行身份验证和验证。
Agent Registry API (agentregistry.googleapis.com)：注册和管理由网关管理的智能体、MCP 服务器和工具端点。
Discovery Engine API (discoveryengine.googleapis.com)：启用 Gemini Enterprise 数据存储区和连接器。

如需启用最低要求的 API，请运行以下命令：

gcloud services enable \
    compute.googleapis.com \
    networkconnectivity.googleapis.com \
    networksecurity.googleapis.com \
    networkservices.googleapis.com \
    serviceextensions.googleapis.com \
    iam.googleapis.com \
    iap.googleapis.com \
    agentregistry.googleapis.com \
    discoveryengine.googleapis.com \
    --project=PROJECT_ID

将 PROJECT_ID 替换为部署 Agent Gateway 的项目 ID。

根据您的配置，您可能还需要启用可选 API：

Cloud DNS API (dns.googleapis.com)：仅当您为专用网域解析配置 DNS 对等互连时才需要。
Certificate Manager API (certificatemanager.googleapis.com)：仅当您在连接到使用私有 CA 或自签名证书的私有后端时配置自定义 TLS 信任锚 (TrustConfig) 时才需要。

验证所需的 IAM 角色

如需为 Agent Gateway 和自定义 MCP 服务器数据存储区配置 VPC 连接，请确保用于预配的身份和服务代理具有所需角色。

独立项目部署

在网关、网络连接和 VPC 网络位于同一项目的独立项目中，适用标准 Agent Gateway 权限（以及 Discovery Engine Editor 角色 roles/discoveryengine.editor，用于创建自定义 MCP 服务器数据存储区）。如需了解详情，请参阅必需的角色。

共享 VPC 或跨项目部署

如果您使用共享 VPC 或跨项目设置，其中目标 VPC 网络、子网或专用 DNS 区域位于中央宿主项目 (TARGET_VPC_PROJECT_ID) 中，则宿主项目所需的角色取决于您创建 Private Service Connect 网络连接的位置：

服务项目（推荐）：您在与 Agent Gateway 相同的服务项目中创建网络连接，并指向宿主项目的子网。此方法遵循最小权限原则，因为 Agent Gateway 服务代理只需要宿主项目上的 roles/compute.networkUser 权限。
宿主项目：您直接在中央宿主项目中创建网络连接。由于网关跨项目边界连接，因此服务代理需要更高的管理权限（roles/compute.networkAdmin 或具有 compute.networkAttachments.update 的自定义角色）才能在宿主项目中接受连接。

除了标准 Agent Gateway 权限之外，还需在宿主项目中授予以下角色：

主账号或身份	所需 IAM 角色	用途
预配身份¹ （用户账号或部署服务账号）	Compute Network Viewer (`roles/compute.networkViewer`) DNS Reader (`roles/dns.reader`) Network Connectivity Regional Endpoint Admin (`roles/networkconnectivity.regionalEndpointAdmin`) Network Connectivity Consumer Network Admin (`roles/networkconnectivity.consumerNetworkAdmin`)	允许在网关创建或更新期间对目标 VPC 网络、子网、网络连接和专用 DNS 区域进行后端验证。
网络连接创建者（创建连接的管理员）	Compute Network User (`roles/compute.networkUser`)	允许使用宿主项目中的共享 VPC 子网创建 Private Service Connect 网络连接。
服务项目中的网络连接（推荐）
Agent Gateway 服务代理²	Compute Network User (`roles/compute.networkUser`) DNS 对等互连 (`roles/dns.peer`)	允许 Agent Gateway 服务代理使用宿主项目子网进行网络连接、连接 Private Service Connect 接口以路由出站流量，以及与宿主项目中的专用 Cloud DNS 区域进行对等互连。
宿主项目中的网络连接
Agent Gateway 服务代理²	Compute Network Admin (`roles/compute.networkAdmin`) 或具有以下权限的自定义角色： `compute.networkAttachments.get` `compute.networkAttachments.update` `compute.regionOperations.get` DNS 对等互连 (`roles/dns.peer`)	允许 Agent Gateway 服务代理更新宿主项目网络连接，以允许来自 Agent Gateway 租户项目的连接、路由出站流量，以及与宿主项目中的专用 Cloud DNS 区域建立对等互连。

¹ 对于预配身份，宿主项目上的基本项目级角色（例如 Viewer [roles/viewer] 或 Editor [roles/editor]）也足够。

² Agent Gateway 服务代理的格式为 service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com。

向 Agent Gateway 服务代理授予角色

创建 Agent Gateway 服务身份并授予所需角色：

gcloud beta services identity create \
    --service=networkservices.googleapis.com \
    --project=AGENT_GATEWAY_PROJECT_ID

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com" \
    --role="roles/compute.networkUser"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com" \
    --role="roles/dns.peer"

替换以下内容：

AGENT_GATEWAY_PROJECT_ID：您在其中部署 Agent Gateway 的项目 ID。
TARGET_PROJECT_ID：您在其中授予角色的项目 ID。对于独立部署，这与 AGENT_GATEWAY_PROJECT_ID 相同。对于共享 VPC 或跨项目部署，这是您的宿主项目 ID (TARGET_VPC_PROJECT_ID)。
AGENT_GATEWAY_PROJECT_NUMBER：您部署 Agent Gateway 的项目的数字项目编号。

（可选）注册 OAuth 应用

如果您的私有 MCP 服务器需要 OAuth 2.0 身份验证，请将 Gemini Enterprise 作为 OAuth 客户端应用注册到您的身份提供方。

Google 身份

如果 Google 是您的身份提供方，请在 Google Cloud 控制台中执行以下步骤：

在 Google Cloud 控制台中，前往凭证页面。
点击创建凭证并选择 OAuth 客户端 ID。
在应用类型列表中，选择 Web 应用。
可选：如果系统提示，请选择此客户端将由 AI 赋能的智能体使用，以指定用于智能体工作流的客户端。
在名称字段中，为客户端应用输入一个描述性名称。
在已获授权的重定向 URI 部分中，点击添加 URI，然后输入：
https://vertexaisearch.cloud.google.com/oauth-redirect
点击创建。
在已创建 OAuth 客户端对话框中，复制客户端 ID 和客户端密钥。

第三方提供方

如果您使用第三方身份提供方（例如 Okta 或 Azure AD），请在提供方的管理门户中执行以下步骤：

前往身份提供方的管理门户。
创建新的 OAuth 客户端应用。
将授权重定向网址设置为：
https://vertexaisearch.cloud.google.com/oauth-redirect
向客户端应用授予必要的 OAuth 范围。
获取在数据存储区配置期间使用的客户端 ID 和客户端密钥。

创建网络连接

在专用 VPC 网络中创建 Private Service Connect 网络连接。Agent Gateway 会使用此网络连接在您的 VPC 网络中部署 Private Service Connect 接口，以用于出站流量。

确保您已满足以下前提条件：
- 您已在创建网络连接的项目中启用 Compute Engine API。
- 满足以下所有要求的子网：
  - 它位于与您的 Gemini Enterprise 应用位置匹配的区域：us-central1（适用于全球或 us 多区域应用）或 europe-west1（适用于 eu 多区域应用）。
  - 其 IP 地址范围至少为 /28。
  - 它已启用专用 Google 访问通道。
  - 它尚未被其他网络连接使用。
- 所需的 IAM 角色：
  - 在您创建网络连接的项目中，您需要拥有 Compute Network Admin (roles/compute.networkAdmin) 角色。
  - 如果子网位于共享 VPC 宿主项目中：子网上的 Compute Network User (roles/compute.networkUser)。您必须在关联到宿主项目的服务项目中创建网络连接。
在 Google Cloud 控制台中，前往网络连接页面。

前往“网络连接”
点击创建网络连接。
在名称字段中，输入一个描述性名称，例如 cymbal-mcp-vpc-attachment。
选择满足第 1 步中的前提条件的网络、区域和子网。
在连接偏好设置下，选择自动接受所有连接。
点击创建网络连接。
创建完成后，复制网络连接的资源 URI，以便在下一步中使用。URI 的格式如下：
```
projects/PROJECT_ID/regions/LOCATION/networkAttachments/ATTACHMENT_NAME
```

（可选）为静态 IP 出站流量配置 Cloud NAT

如果您的应用场景是静态 IP 出站流量流向需要请求来自预留 IP 地址的公共或外部 MCP 服务器，请在分配给网络连接的子网上配置 Cloud NAT：

预留静态外部 IPv4 地址：在网络连接所在的区域中预留区域级静态 IP 地址：

gcloud compute addresses create STATIC_IP_NAME \
    --region=LOCATION \
    --project=PROJECT_ID

创建 Cloud Router 路由器：如果您的 VPC 网络在该区域中还没有 Cloud Router 路由器，请创建一个：

gcloud compute routers create ROUTER_NAME \
    --network=NETWORK_NAME \
    --region=LOCATION \
    --project=PROJECT_ID

创建 Cloud NAT 网关：创建与 Cloud Router 路由器关联的 Cloud NAT 网关，并将其绑定到预留的静态 IP 地址。确保 NAT 网关涵盖分配给网络连接的子网：
```
gcloud compute routers nats create NAT_NAME \
    --router=ROUTER_NAME \
    --region=LOCATION \
    --nat-custom-subnet-ip-ranges=SUBNET_NAME \
    --nat-external-ip-pool=STATIC_IP_NAME \
    --project=PROJECT_ID
```
替换以下内容：
- STATIC_IP_NAME：预留外部 IP 地址的名称。
- LOCATION：与您的网络连接匹配的区域（us-central1 或 europe-west1）。
- PROJECT_ID：您的 Google Cloud 项目 ID。
- ROUTER_NAME：Cloud Router 的名称。
- NETWORK_NAME：您的 VPC 网络的名称。
- NAT_NAME：新 Cloud NAT 网关的名称。
- SUBNET_NAME：分配给网络连接的子网。

如需了解详情，请参阅设置和管理 Cloud NAT。

创建代理连接模板

定义一个代理连接模板，用于封装 VPC 出站流量配置，包括网络连接、DNS 对等互连和出站流量路由模式。您可以使用 gcloud CLI 创建连接模板和 Agent Gateway。如需详细了解连接模板架构和路由选项，请参阅为 Agent Gateway 设置 VPC 连接。

创建一个名为 agw-connectivity-template.yaml 的 YAML 配置文件：
```
name: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: PSC_NETWORK_ATTACHMENT_URI
  # Optional: Delete the dnsPeeringConfig block if you don't require private DNS peering
  dnsPeeringConfig:
    domains:
      - DOMAIN_NAME
    targetNetwork: TARGET_VPC_NETWORK_URI
  vpcEgress: VPC_EGRESS_MODE
  # Optional: Include tlsConfig if your MCP server uses a private CA or self-signed certificate
  # tlsConfig:
  #   trustConfig: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/trustConfigs/TRUST_CONFIG_NAME
  #   additionalRoots: ADDITIONAL_ROOTS_OPTION
```
保留 accessPath 和 deploymentModel 值，并替换以下内容：
- AGENT_GATEWAY_PROJECT_NUMBER：部署网关的 Google Cloud 项目的数字编号。如需检索项目编号，请运行：gcloud projects describe PROJECT_ID --format="value(projectNumber)"。
- LOCATION：智能体连接性模板的区域，对应于您的 Gemini Enterprise 应用位置：
  - 对于 global 或 us 多区域应用，请指定 us-central1。
  - 对于 eu 多区域应用，请指定 europe-west1。
- CONNECTIVITY_TEMPLATE_NAME：您为新代理连接模板资源选择的名称（例如 cymbal-mcp-connectivity-template）。
- PSC_NETWORK_ATTACHMENT_URI：您在创建网络连接中复制的资源 URI。此值的格式为 projects/PROJECT_ID/regions/REGION/networkAttachments/ATTACHMENT_NAME。如果网络连接与网关位于不同的项目中（例如，共享 VPC 宿主项目），请指定完整的资源路径。
- DOMAIN_NAME：（可选）用于专用 DNS 对等互连的一个或多个域名后缀（例如 cymbal.internal. 或 run.app.）。为您要对等互连的每个域名后缀在 domains 下添加一个列表项。每个值都必须以英文句点 (.) 结尾，并且具有为目标网络授权的相应专用 Cloud DNS 代管区域。如果 MCP 服务器使用公共网域或水平分割 DNS，则无需进行 DNS 对等互连，您可以省略 dnsPeeringConfig。对于根域名对等互连、VPC Service Controls 和其他高级 DNS 场景，请参阅为 Agent Gateway 设置 VPC 连接。
- TARGET_VPC_NETWORK_URI：目标 VPC 网络的资源 URI，格式为 projects/PROJECT_ID/global/networks/NETWORK_NAME。此网络必须与您创建网络连接的 VPC 网络完全相同。
- VPC_EGRESS_MODE：出站流量路由设置。设置为 PRIVATE_RANGES_ONLY（默认）可通过 VPC 网络路由发往专用 IP 范围（RFC 1918、RFC 6598、E 类）的流量，或设置为 ALL_TRAFFIC 可通过 VPC 网络路由所有出站代理流量（包括公共互联网地址）。
- tlsConfig：（可选）通过 HTTPS 连接到使用私有 CA 或自签名证书的私有端点时，用于服务器证书验证的 TLS 配置：
  - TRUST_CONFIG_NAME：包含您的私有 CA 证书或信任锚的 Certificate Manager TrustConfig 资源的名称。
  - ADDITIONAL_ROOTS_OPTION：指定除了自定义信任配置之外，是否还信任公开受信任的 CA 根。设置为 PUBLICLY_TRUSTED_ROOTS（默认）可同时信任由 trustConfig 参数验证的证书和所有公开可信的 CA。设置为 NO_ADDITIONAL_ROOTS，以仅信任通过 trustConfig 参数验证的证书。如需了解如何在 Certificate Manager 中创建 TrustConfig 资源，请参阅为 Agent Gateway 设置 VPC 连接。
运行以下命令以创建代理连接模板：
```
gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
    --source="agw-connectivity-template.yaml" \
    --location=LOCATION \
    --project=AGENT_GATEWAY_PROJECT_ID
```
替换以下内容：
- CONNECTIVITY_TEMPLATE_NAME：代理连接模板资源的名称。
- LOCATION：您创建代理连接模板资源的位置。例如 us-central1。
- AGENT_GATEWAY_PROJECT_ID：您要在其中部署 Agent Gateway 的 Google Cloud项目 ID。

创建 Agent Gateway

创建引用代理连接模板的 Agent Gateway 资源。如需详细了解如何为 Gemini Enterprise 部署网关，请参阅通过 Agent Gateway 路由 Gemini Enterprise 流量。

创建一个名为 cymbal-agent-gateway-vpc-egress.yaml 的网关 YAML 配置文件：
```
name: AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
# Optional: Include only when using Agent Registry governance or IAP authorization
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGISTRY_LOCATION
```
保留 protocols 和 googleManaged 值，并替换以下内容：
- AGENT_GATEWAY_NAME：您为 Agent Gateway 资源选择的名称（例如 cymbal-mcp-gateway）。
- AGENT_GATEWAY_PROJECT_NUMBER：您在其中创建网关的 Google Cloud 项目的数字编号。
- LOCATION：网关所在的区域。此值必须与网络连接和连接模板（us-central1 或 europe-west1）的区域一致。
- CONNECTIVITY_TEMPLATE_NAME：您在创建代理连接模板中创建的代理连接模板的名称。
- PROJECT_ID：您的 Google Cloud项目 ID。仅在将网关与 Agent Registry 关联以实现统一的智能体治理、工具发现和 IAP 访问权限政策时，才需要提供此信息。如果您使用基本授权，请省略 registries 代码块。
- REGISTRY_LOCATION：Agent Registry 实例的位置，必须与 Gemini Enterprise 应用和网关位置一致：
  - 如果您的应用位置为 us，请使用 us-central1 或 us。
  - 如果您的应用位置为eu，请使用europe-west1、eu或global。
  - 如果您的应用位置为 global，请使用 us-central1、us 或 global。
运行以下命令以创建 Agent Gateway 资源：
```
gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
    --source="cymbal-agent-gateway-vpc-egress.yaml" \
    --location=LOCATION \
    --project=AGENT_GATEWAY_PROJECT_ID
```
替换以下内容：
- AGENT_GATEWAY_NAME：Agent Gateway 资源的名称。
- LOCATION：创建网关的区域（us-central1 或 europe-west1）。
- AGENT_GATEWAY_PROJECT_ID：您在其中创建网关的 Google Cloud项目 ID。

创建授权政策

创建 Agent Gateway 后，配置授权政策以允许出站流量通过网关。如果您在 Agent Registry 中注册 MCP 服务器，并希望通过 IAM 政策控制智能体访问权限，请使用 IAP 授权。否则，请使用基本授权，它允许所有出站流量通过网关。

IAP 授权

在 DRY_RUN 审核模式下部署 IAP 授权扩展。此模式允许出站流量，因此您可以在不屏蔽请求的情况下验证连接。如需了解详情，请参阅将授权委托给 IAP。

在名为 iap-request-authz-extension.yaml 的 YAML 文件中定义授权扩展：

name: cymbal-iap-request-authz-ext
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN"

导入授权扩展程序：

gcloud service-extensions authz-extensions import cymbal-iap-request-authz-ext \
    --source=iap-request-authz-extension.yaml \
    --location=LOCATION \
    --project=PROJECT_ID

在名为 iap-request-authz-policy.yaml 的 YAML 文件中定义授权政策：

name: cymbal-iap-request-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/cymbal-iap-request-authz-ext"

导入授权政策：
```
gcloud network-security authz-policies import cymbal-iap-request-authz-policy \
    --source=iap-request-authz-policy.yaml \
    --location=LOCATION \
    --project=PROJECT_ID
```
替换以下内容：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- LOCATION：Agent Gateway 的位置，例如 us-central1 或 europe-west1。
- AGENT_GATEWAY_NAME：Agent Gateway 资源的名称（例如 cymbal-mcp-gateway）。

基本授权

如果您的部署不需要 IAP 或 IAM 代理政策，请配置基本授权政策，以允许所有出站流量通过网关（在网关 YAML 配置中将可选的 registries 块注释掉）：

创建名为 basic-authz-policy-allow-all.yaml 的配置文件：

name: AGENT_GATEWAY_NAME-authz-policy-allow-all
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: ALLOW
httpRules:
  - to:
      operations:
        - paths:
            - prefix: /

导入授权政策：

gcloud network-security authz-policies import AGENT_GATEWAY_NAME-authz-policy-allow-all \
    --source=basic-authz-policy-allow-all.yaml \
    --location=LOCATION \
    --project=PROJECT_ID

验证有效的授权政策：
```
gcloud network-security authz-policies describe AGENT_GATEWAY_NAME-authz-policy-allow-all \
    --location=LOCATION \
    --project=PROJECT_ID
```
替换以下内容：
- AGENT_GATEWAY_NAME：Agent Gateway 资源的名称。
- PROJECT_ID：您的 Google Cloud 项目 ID。
- LOCATION：Agent Gateway 的位置（us-central1 或 europe-west1）。

更新防火墙规则

Agent Gateway 出站流量进入 VPC 网络不需要出站防火墙规则，因为 VPC 网络默认允许出站流量。如果您配置了拒绝出站流量的防火墙规则（例如阻止流向互联网的流量的规则），请添加一条允许来自网络连接子网的出站流量的规则。对于流向公共 MCP 服务器的静态 IP 出站流量，此规则必须允许流量流向服务器的公共 IP 地址。

如果您连接到托管在 VPC 网络内的专用 MCP 服务器，则还必须创建一条入站流量防火墙规则，以允许来自网络连接子网的传入连接：

在 Google Cloud 控制台中，前往防火墙页面。
点击创建防火墙规则。
在名称字段中，输入一个名称，例如 allow-cymbal-mcp-gateway-ingress。
选择您的私有 MCP 服务器运行所在的 VPC 网络。
将流量方向设置为入站。
将对匹配项执行的操作设置为允许。
在目标中，根据您的网络部署模型选择指定的目标标记或网络中的所有实例。
在来源 IPv4 范围中，输入与网络连接关联的子网的 IP 地址范围。
在协议和端口下，选择指定的协议和端口，并指定您的私有 MCP 服务器使用的 TCP 端口，例如 tcp:443 或 tcp:8080。
点击创建。

验证网关配置

确认您的网关、代理连接模板和 Private Service Connect 网络连接已正确关联并接受：

验证网关是否引用了您的代理连接模板：
```
gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
    --location=LOCATION \
    --project=AGENT_GATEWAY_PROJECT_ID
```
输出包含一个 agentConnectivityTemplate 字段，该字段引用您创建的模板。如果缺少此字段，则网关不会通过 VPC 网络路由流量。验证网关 YAML 文件中的 agentConnectivityTemplate 值是否正确，然后重新导入该文件。

验证您的代理连接模板是否引用了您的网络连接：

gcloud network-services agent-connectivity-templates describe CONNECTIVITY_TEMPLATE_NAME \
    --location=LOCATION \
    --project=AGENT_GATEWAY_PROJECT_ID

在输出中，确认 egressNetworkConfig.networkAttachment 指向您的网络连接资源 URI。

验证您的网络连接是否显示已接受的连接：
```
gcloud compute network-attachments describe ATTACHMENT_NAME \
    --region=LOCATION \
    --project=PROJECT_ID
```
在输出中，确认 connectionEndpoints 列出了一个包含 status: ACCEPTED 的条目。

排查常见网关错误

如果 Gemini Enterprise 无法通过网关连接到您的自定义 MCP 服务器，请检查对话轮次或 Cloud Logging 中返回的 HTTP 状态代码：

错误	原因	解决方法
HTTP 403 Forbidden	默认情况下，通过 Agent Gateway 的出站流量会被屏蔽，直到有效的授权政策绑定到网关。	确保您已完成创建授权政策，并且您的政策以网关的完整资源路径为目标： `projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME` 如需确认政策处于有效状态，请运行以下命令： `gcloud network-security authz-policies describe AGENT_GATEWAY_NAME-authz-policy-allow-all --location=LOCATION --project=PROJECT_ID`
HTTP 503 服务不可用	网关无法解析您的私有 MCP 服务器主机名，也无法将数据包路由到您的 VPC 网络。	如果您的服务器使用私有域名（例如 `mcp.cymbal.internal`），请验证代理连接模板中的 `dnsPeeringConfig.domains` 是否包含带尾随点 (`.`) 的域名后缀，以及您的私有 Cloud DNS 区域是否已获得目标 VPC 网络的授权。验证网络连接子网是否已启用专用 Google 访问通道。请验证您的防火墙规则是否允许从网络连接子网到 MCP 服务器（在所配置端口上）的入站流量。

后续步骤

如需在完成前提条件设置后创建自定义 MCP 服务器数据存储区，请参阅创建自定义 MCP 服务器数据存储区。
如需了解详细的 Agent Gateway 治理选项，请参阅为 Agent Gateway 设置 VPC 连接。