Menghosting server MCP di Cloud Run

Panduan ini menunjukkan cara menghosting server Model Context Protocol (MCP) dengan transpor HTTP yang dapat di-stream di Cloud Run, dan memberikan panduan untuk mengautentikasi klien MCP. Jika Anda baru menggunakan MCP, baca referensi berikut:

MCP adalah protokol terbuka yang menstandarkan cara agen AI berinteraksi dengan lingkungannya. Agen AI menghosting klien MCP, dan alat serta resource yang berinteraksi dengannya adalah server MCP. Klien MCP dapat berkomunikasi dengan server MCP melalui dua jenis transpor yang berbeda:

Anda dapat menghosting klien dan server MCP di mesin lokal yang sama, menghosting klien MCP secara lokal dan membuatnya berkomunikasi dengan server MCP jarak jauh yang dihosting di platform cloud seperti Cloud Run, atau menghosting klien dan server MCP di platform cloud.

Cloud Run mendukung penghostingan server MCP dengan transpor HTTP yang dapat di-stream, tetapi tidak mendukung server MCP dengan transpor stdio.

Diagram berikut menunjukkan cara klien MCP mengambil intent agen AI dan mengirim permintaan standar ke server MCP, dengan menentukan alat yang akan dieksekusi. Setelah server MCP mengeksekusi tindakan dan mengambil hasilnya, server MCP akan menampilkan hasilnya kembali ke klien MCP dalam format yang konsisten.

Server MCP berinteraksi dengan agen AI melalui klien MCP.
Gambar 1.Server MCP yang dihosting di Cloud Run berinteraksi dengan klien MCP, yang berinteraksi dengan agen AI.

Panduan di halaman ini berlaku jika Anda mengembangkan server MCP sendiri atau jika Anda menggunakan server MCP yang ada.

Sebelum memulai

  1. Sign in to your Google Cloud account. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  6. Siapkan lingkungan pengembangan Cloud Run di Google Cloud project Anda.
  7. Pastikan Anda memiliki izin yang sesuai untuk men-deploy layanan, serta peran Cloud Run Admin (roles/run.admin) dan Pengguna Akun Layanan (roles/iam.serviceAccountUser) yang diberikan ke akun Anda.

    8. Pelajari cara memberikan peran

    Konsol

    1. Di Google Cloud konsol, buka halaman IAM.

      Buka IAM
    2. Pilih project.
    3. Klik Grant access.

    4. Di kolom New principals, masukkan ID pengguna Anda. ID ini biasanya adalah alamat email yang digunakan untuk men-deploy layanan Cloud Run.

    5. Di daftar Select a role, pilih peran.
    6. Untuk memberikan peran tambahan, klik Add another role dan tambahkan setiap peran tambahan.
    7. Klik Save.

    gcloud

    Untuk memberikan peran IAM yang diperlukan ke akun Anda di project Anda:

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

    Ganti:

    • PROJECT_NUMBER dengan nomor Google Cloud project Anda.
    • PROJECT_ID dengan ID Google Cloud project Anda.
    • PRINCIPAL dengan akun yang Anda tambahkan binding-nya. ID ini biasanya adalah alamat email yang digunakan untuk men-deploy layanan Cloud Run.
    • ROLE dengan peran yang Anda tambahkan ke akun deployer account.

Menghosting server MCP SSE atau HTTP yang dapat di-stream dari jarak jauh

Server MCP yang menggunakan peristiwa yang dikirim server (SSE) atau transpor HTTP yang dapat di-stream dapat dihosting dari jarak jauh dari klien MCP-nya.

Untuk men-deploy jenis server MCP ini ke Cloud Run, Anda dapat men-deploy server MCP sebagai image container atau sebagai kode sumber (biasanya Node.js atau Python), bergantung pada cara server MCP dikemas.

Image container

Server MCP jarak jauh yang didistribusikan sebagai image container adalah server web yang memproses permintaan HTTP di port tertentu, yang berarti server tersebut mematuhi kontrak runtime container Cloud Run dan dapat di-deploy ke layanan Cloud Run.

Untuk men-deploy server MCP yang dikemas sebagai image container, Anda harus memiliki URL image container dan port tempat server tersebut menerima permintaan. Server ini dapat di-deploy menggunakan perintah gcloud CLI berikut:

gcloud run deploy --image IMAGE_URL --port PORT

Ganti:

  • IMAGE_URL dengan URL image container, misalnya us-docker.pkg.dev/cloudrun/container/mcp.
  • PORT dengan port yang diprosesnya, misalnya 3000.

Sumber

Server MCP jarak jauh yang tidak disediakan sebagai image container dapat di- deploy ke Cloud Run dari sumbernya, terutama jika ditulis dalam Node.js atau Python.

  1. Buat clone repositori Git server MCP: 

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

  2. Buka root server MCP: 

    cd REPOSITORY

  3. Deploy ke Cloud Run dengan perintah gcloud CLI berikut: 

    gcloud run deploy --source .

Setelah Anda men-deploy server MCP HTTP ke Cloud Run, server MCP akan mendapatkan URL HTTPS dan komunikasi dapat menggunakan dukungan bawaan Cloud Run untuk streaming respons HTTP.

Mengautentikasi klien MCP untuk agen AI

Bergantung pada tempat Anda menghosting klien MCP, lihat bagian yang relevan untuk Anda:

Mengautentikasi klien MCP lokal

Jika agen AI yang menghosting klien MCP berjalan di mesin lokal, gunakan salah satu metode berikut untuk mengautentikasi klien MCP:

Untuk mengetahui informasi selengkapnya, lihat spesifikasi MCP tentang Autentikasi.

Izin pemanggil IAM

Secara default, URL layanan Cloud Run mengharuskan semua permintaan diotorisasi dengan Cloud Run Invoker (roles/run.invoker) peran IAM. Binding kebijakan IAM ini memastikan bahwa mekanisme keamanan yang kuat digunakan untuk mengautentikasi klien MCP lokal Anda.

Setelah men-deploy server MCP ke layanan Cloud Run di region, jalankan proxy Cloud Run di mesin lokal Anda untuk mengekspos server MCP jarak jauh ke klien Anda secara aman menggunakan kredensial Anda sendiri:

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

Ganti:

  • MCP_SERVER_NAME dengan nama layanan Cloud Run Anda.
  • REGION dengan Google Cloud region tempat Anda men-deploy layanan. Misalnya, europe-west1.

Perintah proxy Cloud Run membuat proxy lokal di port 3000 yang meneruskan permintaan ke server MCP jarak jauh dan menyisipkan identitas Anda.

Perbarui file konfigurasi MCP klien MCP Anda dengan hal berikut:

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

Jika klien MCP Anda tidak mendukung atribut url, gunakan paket npm mcp-remote:

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

Token ID OIDC

Bergantung pada apakah klien MCP mengekspos header atau menggunakan cara untuk menyediakan transpor yang diautentikasi kustom, Anda dapat mempertimbangkan untuk mengautentikasi klien MCP dengan token ID OIDC.

Anda dapat menggunakan berbagai library autentikasi Google untuk mendapatkan token ID dari lingkungan runtime, misalnya Library Autentikasi Google untuk Python. Token ini harus memiliki klaim audiens yang benar yang cocok dengan URL layanan penerima *.run.app, kecuali jika Anda menggunakan audiens kustom. Anda juga harus menyertakan token ID dalam permintaan klien, seperti Authorization: Bearer <token value>.

Jika klien MCP tidak mengekspos header atau transpor, gunakan metode autentikasi yang berbeda.

Mengautentikasi klien MCP yang berjalan di Cloud Run

Jika agen AI yang menghosting klien MCP berjalan di Cloud Run, gunakan salah satu metode berikut untuk mengautentikasi klien MCP:

Men-deploy server MCP sebagai sidecar

Server MCP dapat di-deploy sebagai sidecar tempat klien MCP berjalan.

Tidak ada autentikasi khusus yang diperlukan untuk kasus penggunaan ini, karena klien MCP dan server MCP berada di instance yang sama. Klien dapat terhubung ke server MCP menggunakan port di http://localhost:PORT. Ganti PORT dengan port yang berbeda dari port yang digunakan untuk mengirim permintaan ke layanan Cloud Run.

Mengautentikasi layanan ke layanan

Jika server MCP dan klien MCP berjalan sebagai layanan Cloud Run yang berbeda, lihat Mengautentikasi layanan ke layanan.

Menggunakan Cloud Service Mesh

Agen yang menghosting klien MCP dapat terhubung ke server MCP jarak jauh menggunakan Cloud Service Mesh. Penggunaan mesh layanan menyederhanakan orkestrasi layanan mikro dengan menangani autentikasi dan pengelolaan traffic secara otomatis.

Anda dapat mengonfigurasi layanan server MCP agar memiliki nama pendek di mesh, dan klien MCP dapat berkomunikasi dengan server MCP menggunakan nama pendek http://mcp-server. Autentikasi dikelola oleh mesh.

Langkah berikutnya