Menghosting server MCP di Cloud Run

Panduan ini menunjukkan cara menghosting server Model Context Protocol (MCP) dengan transportasi HTTP yang dapat di-streaming di Cloud Run, dan memberikan panduan untuk mengautentikasi klien MCP. Jika Anda baru menggunakan MCP, baca Panduan pengantar untuk mengetahui konteks selengkapnya.

MCP adalah protokol terbuka yang menstandardisasi 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 hosting server MCP dengan transpor HTTP yang dapat di-streaming, tetapi tidak mendukung server MCP dengan transpor stdio.

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

Sebelum memulai

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

    8. Pelajari cara memberikan peran

    Konsol

    1. Di konsol Google Cloud , buka halaman IAM.

      Buka IAM
    2. Pilih project.
    3. Klik Berikan akses.

    4. Di kolom Akun utama baru, masukkan ID pengguna Anda. Ini biasanya berupa alamat email Akun Google yang digunakan untuk men-deploy layanan Cloud Run.

    5. Di daftar Pilih peran, pilih peran.
    6. Untuk memberikan peran tambahan, klik Tambahkan peran lain, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

    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 project Google Cloud Anda.
    • PROJECT_ID dengan Google Cloud project ID Anda.
    • PRINCIPAL dengan akun yang Anda tambahkan binding-nya. Biasanya, alamat email Akun Google yang digunakan untuk men-deploy layanan Cloud Run.
    • ROLE dengan peran yang Anda tambahkan ke akun deployer.

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

    Server MCP yang menggunakan Server-sent events (SSE) atau transpor HTTP yang dapat di-streaming 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 diharapkan menerima permintaan. Hal 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

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

    Mengautentikasi klien MCP lokal

    Jika agen AI yang menghosting klien MCP berjalan di komputer 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 peran IAM Cloud Run Invoker (roles/run.invoker). Pengikatan 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 suatu 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. Contoh, europe-west1.

    Perintah proxy Cloud Run membuat proxy lokal di port 3000 yang meneruskan permintaan ke server MCP jarak jauh dan menyuntikkan 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 transport 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 Google Auth untuk Python. Token ini harus memiliki klaim audiens yang benar dan cocok dengan URL *.run.app layanan penerima, 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 transportasi, gunakan metode autentikasi lain.

    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 antar layanan

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

    Menggunakan Cloud Service Mesh

    Agen yang menghosting klien MCP dapat terhubung ke server MCP jarak jauh menggunakan Cloud Service Mesh.

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

    Langkah berikutnya