在 Cloud Run 上託管 MCP 伺服器

本指南說明如何在 Cloud Run 上，透過可串流的 HTTP 傳輸方式，代管 Model Context Protocol (MCP) 伺服器，並提供 MCP 用戶端驗證指南。如果您是第一次使用 MCP，請參閱簡介指南，瞭解相關背景資訊。

MCP 是一項開放通訊協定，可將 AI 代理與環境的互動方式標準化。AI 代理程式會代管 MCP 用戶端，而與其互動的工具和資源則是 MCP 伺服器。MCP 用戶端可透過兩種不同的傳輸類型與 MCP 伺服器通訊：

您可以在同一部本機電腦上託管 MCP 用戶端和伺服器，在本機託管 MCP 用戶端並與託管於 Cloud Run 等雲端平台的遠端 MCP 伺服器通訊，或是在雲端平台上託管 MCP 用戶端和伺服器。

Cloud Run 支援使用可串流的 HTTP 傳輸方式代管 MCP 伺服器，但不支援使用 stdio 傳輸方式的 MCP 伺服器。

如果您要開發自己的 MCP 伺服器，或使用現有的 MCP 伺服器，請參閱本頁面的指引。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 在 Google Cloud 專案中設定 Cloud Run 開發環境。
  7. 請確認您擁有部署服務的適當權限，且帳戶已獲授「Cloud Run 管理員」 (roles/run.admin) 和「服務帳戶使用者」 (roles/iam.serviceAccountUser) 角色。

    8. 瞭解如何授予角色

    控制台

    1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理)IAM 頁面。

      前往「IAM」頁面
    2. 選取專案。
    3. 按一下 「授予存取權」。

    4. 在「New principals」(新增主體) 欄位中輸入使用者 ID。這通常是部署 Cloud Run 服務時使用的 Google 帳戶電子郵件地址。

    5. 在「Select a role」(選取角色) 清單中，選取角色。
    6. 如要授予其他角色，請按一下 「新增其他角色」，然後新增每個其他角色。
    7. 按一下「儲存」。

    gcloud

    如要在專案中授予帳戶必要的 IAM 角色，請按照下列步驟操作：

       gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL \
       --role=ROLE

    取代：

    • 將 PROJECT_NUMBER 改成您的 Google Cloud 專案編號。
    • 將 PROJECT_ID 改成您的 Google Cloud 專案 ID。
    • PRINCIPAL，並為該帳戶新增繫結。這通常是部署 Cloud Run 服務時使用的 Google 帳戶電子郵件地址。
    • ROLE，並將角色新增至部署者帳戶。

    代管遠端 SSE 或可串流的 HTTP MCP 伺服器

    使用伺服器推送事件 (SSE) 或可串流的 HTTP 傳輸的 MCP 伺服器，可從 MCP 用戶端遠端代管。

    如要將這類 MCP 伺服器部署到 Cloud Run，您可以視 MCP 伺服器的封裝方式，將 MCP 伺服器部署為容器映像檔或原始碼 (通常是 Node.js 或 Python)。

    容器映像檔

    以容器映像檔形式發布的遠端 MCP 伺服器是網路伺服器，會監聽特定通訊埠上的 HTTP 要求，因此符合 Cloud Run 的容器執行階段合約，並可部署至 Cloud Run 服務。

    如要部署封裝為容器映像檔的 MCP 伺服器，您必須擁有容器映像檔的網址，以及伺服器預期接收要求的連接埠。您可以使用下列 gcloud CLI 指令部署這些函式：

    gcloud run deploy --image IMAGE_URL --port PORT

    取代：

    • IMAGE_URL，例如 us-docker.pkg.dev/cloudrun/container/mcp。
    • PORT，並指定監聽的通訊埠，例如 3000。

    來源

    如果遠端 MCP 伺服器不是以容器映像檔的形式提供，則可以從來源部署至 Cloud Run，特別是當伺服器是以 Node.js 或 Python 編寫時。

    1. 複製 MCP 伺服器的 Git 存放區： 

      git clone https://github.com/ORGANIZATION/REPOSITORY.git

    2. 前往 MCP 伺服器的根目錄： 

      cd REPOSITORY

    3. 使用下列 gcloud CLI 指令部署至 Cloud Run： 

      gcloud run deploy --source .

    將 HTTP MCP 伺服器部署至 Cloud Run 後，MCP 伺服器會取得 HTTPS 網址，通訊則可使用 Cloud Run 內建的 HTTP 回應串流支援。

    驗證 MCP 用戶端

    視您代管 MCP 用戶端的位置而定，請參閱相關章節：

    驗證本機 MCP 用戶端

    如果代管 MCP 用戶端的 AI 代理程式在本機上執行，請使用下列其中一種方法驗證 MCP 用戶端：

    詳情請參閱驗證的 MCP 規格。

    IAM 叫用者權限

    根據預設，Cloud Run 服務的網址會要求所有要求都必須使用「Cloud Run 叫用者」(roles/run.invoker) IAM 角色授權。這項 IAM 政策繫結可確保使用強大的安全機制，驗證本機 MCP 用戶端。

    將 MCP 伺服器部署至某個區域的 Cloud Run 服務後，請在本機電腦上執行 Cloud Run Proxy，使用自己的憑證安全地向用戶端公開遠端 MCP 伺服器：

    gcloud run services proxy MCP_SERVER_NAME --region REGION --port=3000

    取代：

    • MCP_SERVER_NAME 改為您的 Cloud Run 服務名稱。
    • 將 REGION 改成服務部署所在的 Google Cloud 區域。例如：europe-west1。

    Cloud Run Proxy 指令會在通訊埠 3000 上建立本機 Proxy，將要求轉送至遠端 MCP 伺服器，並插入您的身分。

    使用下列項目更新 MCP 用戶端的 MCP 設定檔：

    {
  "mcpServers": {
    "cloud-run": {
      "url": "http://localhost:3000/sse"
    }
  }
}

    如果 MCP 用戶端不支援 url 屬性，請使用 mcp-remote npm 套件：

    {
  "mcpServers": {
    "cloud-run": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/sse"
      ]
    }
  }
}

    OIDC ID 權杖

    視 MCP 用戶端是否公開標頭，或使用提供自訂驗證傳輸的方式而定，您可能會考慮使用 OIDC ID 權杖驗證 MCP 用戶端。

    您可以使用各種 Google 驗證程式庫，從執行階段環境取得 ID 權杖，例如 Python 專用 Google 驗證程式庫。除非使用自訂目標對象，否則這個權杖必須具有正確的目標對象聲明，與接收服務的 *.run.app URL 相符。您也必須在用戶端要求中加入 ID 權杖，例如 Authorization: Bearer <token value>。

    如果 MCP 用戶端未公開標頭或傳輸作業，請改用其他驗證方法。

    驗證在 Cloud Run 上執行的 MCP 用戶端

    如果代管 MCP 用戶端的 AI 代理程式在 Cloud Run 上執行，請使用下列其中一種方法驗證 MCP 用戶端：

    將 MCP 伺服器部署為補充資訊容器

    MCP 伺服器可以部署為 Sidecar，MCP 用戶端會在其中執行。

    由於 MCP 用戶端和 MCP 伺服器位於同一個執行個體，因此這個用途不需要進行特定驗證。用戶端可以使用 http://localhost:PORT 上的通訊埠連線至 MCP 伺服器。將 PORT 替換為與傳送要求至 Cloud Run 服務時所用通訊埠不同的通訊埠。

    驗證服務對服務

    如果 MCP 伺服器和 MCP 用戶端以不同的 Cloud Run 服務執行，請參閱「驗證服務對服務」。

    使用 Cloud Service Mesh

    代管 MCP 用戶端的代理程式可以使用 Cloud Service Mesh 連線至遠端 MCP 伺服器。

    您可以將 MCP 伺服器服務設定為網格上的簡短名稱，MCP 用戶端即可使用該簡短名稱與 MCP 伺服器通訊 http://mcp-server。驗證作業由網格管理。

    後續步驟