透過虛擬私有雲連線設定自訂 MCP 伺服器資料儲存庫的必要條件

本頁面說明必要條件和網路基礎架構，以便透過虛擬私有雲 (VPC) 網路，將 Gemini Enterprise 流量轉送至自訂 Model Context Protocol (MCP) 伺服器。如果 MCP 伺服器是由私人託管於虛擬私有雲網路，或由公開託管，且需要來自靜態 IP 位址的要求，請使用這項設定。

總覽

根據預設，Gemini Enterprise 無法存取託管於私人網路中的資源。如要讓 Gemini Enterprise 與基礎架構中的私人工具或動作安全通訊，請透過 Egress Agent Gateway 將流量轉送至私人虛擬私有雲網路。

這種連線模式支援下列部署用途：

• 私人網路託管：私人 MCP 伺服器在私人虛擬私有雲網路中執行，沒有公開 IP 位址。
• 混合雲和多雲端連線能力：透過混合網路，將動作連結至部署在多雲端或地端部署環境的私人 MCP 伺服器。
• 公開 MCP 伺服器的靜態 IP 輸出：透過虛擬私有雲網路和 Cloud NAT，將傳出流量轉送至公開託管的 MCP 伺服器，讓要求來自目的地伺服器可允許的預留靜態外部 IPv4 位址。

您可以用宣告方式定義這項連線能力。代理程式連線範本會保留輸出設定：要使用的網路連結、要私下解析的網域，以及要透過虛擬私有雲網路轉送的流量。接著，輸出 Agent Gateway 會參照該範本，連至自訂 MCP 伺服器。

您建立下列三項資源：

1. Private Service Connect 網路連結：Agent Gateway 會使用這個連結，在虛擬私有雲網路中部署 Private Service Connect 介面，用於輸出。
2. 代理程式連線能力範本：指向該網路連結，並定義 DNS 對接和輸出路由行為。
3. Agent Gateway：參照範本並轉送應用程式的傳出要求。

確認需求條件和權限

佈建網路基礎架構前，請先確認專案資源、API 和 Identity and Access Management (IAM) 權限。

資源需求

請確認 Google Cloud環境中有下列資源。視用途而定，您需要私人 MCP 伺服器或公開 MCP 伺服器。

啟用必要的 API

在部署 Agent Gateway 和 Gemini Enterprise 應用程式的 Google Cloud 專案中，啟用最低限度的必要 API：

• Compute Engine API (compute.googleapis.com)：提供核心網路基礎架構、子網路、轉送和 Private Service Connect 網路連結。
• Network Connectivity API (networkconnectivity.googleapis.com)：管理跨專案和共用虛擬私有雲網路端點。
• 網路安全 API (networksecurity.googleapis.com)：建立並強制執行閘道流量的授權政策 (authzPolicies)。
• Network Services API (networkservices.googleapis.com)：管理 Agent Gateway 資源 (agentGateways) 和連線範本 (agentConnectivityTemplates)。
• Service Extensions API (serviceextensions.googleapis.com)：建立及管理 Identity-Aware Proxy (IAP) 委派授權的授權擴充功能 (authzExtensions)。
• 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 伺服器資料儲存庫設定虛擬私有雲連線，請確認用於佈建的身分和服務代理具備必要角色。

獨立專案部署作業

在獨立專案中，閘道、網路連結和虛擬私有雲網路位於同一個專案，因此適用標準 Agent Gateway 權限 (以及 Discovery Engine 編輯者 roles/discoveryengine.editor，用於建立自訂 MCP 伺服器資料儲存庫)。詳情請參閱「必要的角色」。

Shared VPC 或跨專案部署

如果您使用共用虛擬私有雲或跨專案設定，其中目標虛擬私有雲網路、子網路或私人 DNS 區域位於中央主專案 (TARGET_VPC_PROJECT_ID)，則主專案所需的角色取決於您建立 Private Service Connect 網路連結的位置：

• 服務專案 (建議)：在與 Agent Gateway 相同的服務專案中建立網路連結，並指向主專案的子網路。這種做法遵循最小權限原則，因為 Agent Gateway 服務代理只需要主專案的 roles/compute.networkUser。
• 主專案：直接在中央主專案中建立網路連結。由於閘道會跨專案邊界連線，服務代理需要較高的管理權限 (roles/compute.networkAdmin 或具備 compute.networkAttachments.update 的自訂角色)，才能接受主專案中的連線。

除了標準 Agent Gateway 權限外，請在主專案中授予下列角色：

將角色授予 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 相同。如果是 Shared VPC 或跨專案部署，則為主專案 ID (TARGET_VPC_PROJECT_ID)。
• AGENT_GATEWAY_PROJECT_NUMBER：部署 Agent Gateway 的專案編號。

(選用) 註冊 OAuth 應用程式

如果私人 MCP 伺服器需要 OAuth 2.0 驗證，請向識別資訊提供者將 Gemini Enterprise 註冊為 OAuth 用戶端應用程式。

建立網路連結

在私人虛擬私有雲網路中建立 Private Service Connect 網路連結。Agent Gateway 會使用這個網路連結，在虛擬私有雲網路中部署 Private Service Connect 介面，用於輸出。

1. 請確認您已完成下列事前準備：

   • 您已在建立網路連結的專案中啟用 Compute Engine API。
   • 符合下列所有條件的子網路：
     • 這個值會根據 Gemini Enterprise 應用程式位置而定： us-central1：global 或 us 多區域應用程式。 europe-west1：eu 多區域應用程式。
     • IP 位址範圍至少為 /28。
     • 已啟用Private Google Access。
     • 未用於其他網路連結。
   • 必要的 IAM 角色：
     • 在您建立網路連結的專案中，具備 Compute 網路管理員 (roles/compute.networkAdmin) 角色。
     • 如果子網路位於 Shared VPC 主專案：子網路的運算網路使用者 (roles/compute.networkUser)。您必須在附加至主專案的服務專案中建立網路連結。

2. 前往 Google Cloud 控制台的「Network attachments」(網路連結) 頁面。

   前往「Network attachments」(網路連結)

3. 按一下「Create network attachment」(建立網路連結)。

4. 在「Name」(名稱) 欄位中，輸入描述性名稱，例如 cymbal-mcp-vpc-attachment。

5. 選取符合步驟 1 必要條件的「Network」(網路)、「Region」(區域) 和「Subnetwork」(子網路)。

6. 在「Connection preference」(連線偏好設定) 下方，選取「Automatically accept all connections」(自動接受所有連線)。

7. 按一下「Create network attachment」(建立網路連結)。

8. 建立完成後，請複製網路連結的資源 URI，以便在下一個步驟使用。URI 格式如下：

   projects/PROJECT_ID/regions/LOCATION/networkAttachments/ATTACHMENT_NAME
   

(選用) 設定 Cloud NAT，以便透過靜態 IP 輸出

如果您的用途是靜態 IP 輸出至公開或外部 MCP 伺服器，且要求必須來自保留的 IP 位址，請在指派給網路連結的子網路上設定 Cloud NAT：

1. 預留靜態外部 IPv4 位址：在網路連結所在的區域，預留區域性靜態 IP 位址：

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

2. 建立 Cloud Router：如果虛擬私有雲網路在該區域中沒有 Cloud Router，請建立一個：

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

3. 建立 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：虛擬私有雲網路的名稱。
   • NAT_NAME：新 Cloud NAT 閘道的名稱。
   • SUBNET_NAME：：指派給 網路連結的子網路。

詳情請參閱「設定及管理 Cloud NAT」。

建立代理程式連線範本

定義代理連線範本，封裝虛擬私有雲輸出設定，包括網路連結、DNS 對接和輸出轉送模式。您可以使用 gcloud CLI 建立連線範本和 Agent Gateway。如要進一步瞭解連線能力範本架構和轉送選項，請參閱「設定 Agent Gateway 的虛擬私有雲連線能力」。

1. 建立名為 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。如果網路連結與閘道位於不同專案 (例如 Shared VPC 主專案)，請指定完整資源路徑。
   • DOMAIN_NAME：(選用) 私人 DNS 對接的一或多個網域字尾 (例如 cymbal.internal. 或 run.app.)。針對要對接的每個網域字尾，在 domains 下方新增清單項目。每個值都必須以半形句號 (.) 結尾，並有授權給目標網路的對應私人 Cloud DNS 代管區域。如果 MCP 伺服器使用公用網域或分割水平 DNS，則不需要 DNS 對接，可以省略 dnsPeeringConfig。如要瞭解根網域對接、VPC Service Controls 和其他進階 DNS 情境，請參閱「設定 Agent Gateway 的連線能力」。
   • TARGET_VPC_NETWORK_URI：目標虛擬私有雲網路的資源 URI，格式為 projects/PROJECT_ID/global/networks/NETWORK_NAME。這個網路必須與您建立網路連結的虛擬私有雲網路完全相同。
   • VPC_EGRESS_MODE：輸出流量轉送設定。設為 PRIVATE_RANGES_ONLY (預設) 可透過虛擬私有雲網路轉送傳送至私人 IP 範圍 (RFC 1918、RFC 6598、Class E) 的流量，設為 ALL_TRAFFIC 則可透過虛擬私有雲網路轉送所有傳出的代理流量 (包括公開網際網路位址)。
   • tlsConfig：(選用) 透過 HTTPS 連線至使用私人 CA 或自行簽署憑證的私人端點時，用於驗證伺服器憑證的 TLS 設定：
     • TRUST_CONFIG_NAME：Certificate Manager TrustConfig 資源的名稱，其中包含您的私密 CA 憑證或信任錨點。
     • ADDITIONAL_ROOTS_OPTION：指定除了自訂信任設定外，是否要信任公開信任的 CA 根憑證。設為 PUBLICLY_TRUSTED_ROOTS (預設) 可同時信任由 trustConfig 參數驗證的憑證，以及所有公開信任的 CA。設為 NO_ADDITIONAL_ROOTS，則只信任由 trustConfig 參數驗證的憑證。如需在 Certificate Manager 中建立 TrustConfig 資源的操作說明，請參閱「設定 Agent Gateway 的虛擬私有雲連線」。

2. 執行下列指令，建立代理連線範本：

   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 流量」。

1. 建立名為 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。

2. 執行下列指令，建立 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 授權。否則，請使用基本授權，允許所有輸出流量通過閘道。

更新防火牆規則

Agent Gateway 輸出至虛擬私有雲網路時，不需要輸出防火牆規則，因為虛擬私有雲網路預設允許輸出流量。如果您已設定拒絕輸出的防火牆規則 (例如封鎖傳往網際網路流量的規則)，請新增規則，允許從網路連結子網路輸出。如要透過靜態 IP 輸出至公開 MCP 伺服器，這項規則必須允許流量傳送至伺服器的公開 IP 位址。

如果連線至託管於虛擬私有雲網路中的私人 MCP 伺服器，您也必須建立輸入防火牆規則，允許來自網路連結子網路的傳入連線：

1. 前往 Google Cloud 控制台的「Firewall」(防火牆) 頁面。
2. 按一下「Create firewall rule」(建立防火牆規則)。
3. 在「Name」(名稱) 欄位中輸入名稱，例如 allow-cymbal-mcp-gateway-ingress。
4. 選取私人 MCP 伺服器運作的虛擬私有雲網路。
5. 將「流量方向」設為「輸入」。
6. 將「相符時執行的動作」設為「允許」。
7. 在「Targets」(目標) 中，依據網路部署模式選取「Specified target tags」(指定的目標標記) 或「All instances in the network」(網路中的所有執行個體)。
8. 在「Source IPv4 ranges」(來源 IPv4 範圍) 中，輸入與網路連結相關聯的子網路 IP 位址範圍。
9. 在「Protocols and ports」(通訊協定和通訊埠) 下方，選取「Specified protocols and ports」(指定的通訊協定和通訊埠)，並指定私人 MCP 伺服器使用的 TCP 通訊埠，例如 tcp:443 或 tcp:8080。
10. 點選「建立」。

驗證閘道設定

確認閘道、代理程式連線範本和 Private Service Connect 網路連結已正確連結並接受：

1. 確認閘道參照代理程式連線能力範本：

   gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
       --location=LOCATION \
       --project=AGENT_GATEWAY_PROJECT_ID
   

   輸出內容包含 agentConnectivityTemplate 欄位，參照您建立的範本。如果缺少這個欄位，表示閘道不會透過虛擬私有雲網路轉送流量。請確認閘道 YAML 檔案中的 agentConnectivityTemplate 值正確無誤，然後再次匯入檔案。

2. 確認代理程式連線範本參照網路連結：

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

   在輸出內容中，確認 egressNetworkConfig.networkAttachment 指向網路連結資源 URI。

3. 確認網路連結顯示已接受的連線：

   gcloud compute network-attachments describe ATTACHMENT_NAME \
       --region=LOCATION \
       --project=PROJECT_ID
   

   在輸出內容中，確認 connectionEndpoints 列出含有 status: ACCEPTED 的項目。

疑難排解常見閘道錯誤

如果 Gemini Enterprise 無法透過閘道連線至自訂 MCP 伺服器，請檢查對話回合或 Cloud Logging 傳回的 HTTP 狀態碼：

後續步驟

• 完成必要設定後，請參閱「建立自訂 MCP 伺服器資料儲存庫」，瞭解如何建立自訂 MCP 伺服器資料儲存庫。
• 如要瞭解詳細的 Agent Gateway 管理選項，請參閱「設定 Agent Gateway 的虛擬私有雲連線」。