Membangun dan men-deploy Server MCP jarak jauh di Cloud Run

Tutorial ini menunjukkan cara membuat dan men-deploy server Model Context Protocol (MCP) jarak jauh di Cloud Run menggunakan transportasi HTTP yang dapat di-streaming. Dengan transpor HTTP yang dapat di-streaming, server MCP beroperasi sebagai proses independen yang dapat menangani beberapa koneksi klien.

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. Make sure 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. Make sure 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, dan peran Admin Cloud Run (roles/run.admin) serta Pengguna Akun Layanan (roles/iam.serviceAccountUser) diberikan ke akun Anda.
  8. Berikan peran Cloud Run Invoker (roles/run.invoker) ke akun Anda. Peran ini memungkinkan server MCP jarak jauh mengakses layanan Cloud Run.

    9. 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: nomor project Google Cloud Anda.
    • PROJECT_ID: ID project Google Cloud Anda.
    • PRINCIPAL: alamat email akun yang Anda beri peran.
    • ROLE: peran yang Anda tambahkan ke akun deployer.

  9. Jika Anda dikenai kebijakan organisasi pembatasan domain yang membatasi pemanggilan yang tidak diautentikasi untuk project, Anda perlu mengakses layanan yang di-deploy seperti yang dijelaskan di bagian Menguji layanan pribadi.

  10. Instal Uv, pengelola project dan paket Python.

    11. Menyiapkan project Python

    Langkah-langkah berikut menjelaskan cara menyiapkan project Python dengan uv pengelola paket.

    1. Buat folder bernama mcp-on-cloudrun untuk menyimpan kode sumber yang akan di-deploy:

        mkdir mcp-on-cloudrun
  cd mcp-on-cloudrun

    2. Buat project Python dengan alat uv untuk menghasilkan file pyproject.toml:

        uv init --name "mcp-on-cloudrun" --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.10

      Perintah uv init membuat file pyproject.toml berikut:

      [project]
name = "mcp-server"
version = "0.1.0"
description = "Example of deploying an MCP server on Cloud Run"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

    3. Buat file baru tambahan berikut:

      • server.py untuk kode sumber server MCP
      • test_server.py untuk menguji server jarak jauh
      • Dockerfile untuk men-deploy ke Cloud Run
      touch server.py test_server.py Dockerfile

      Direktori project Anda harus berisi struktur berikut:

      ├── mcp-on-cloudrun
│   ├── pyproject.toml
│   ├── server.py
│   ├── test_server.py
│   └── Dockerfile

    Membuat server MCP untuk operasi matematika

    Untuk memberikan konteks yang berharga dalam meningkatkan penggunaan LLM dengan MCP, siapkan server MCP matematika dengan FastMCP. FastMCP menyediakan cara cepat untuk membangun server dan klien MCP dengan Python.

    Ikuti langkah-langkah berikut untuk membuat server MCP untuk operasi matematika seperti penjumlahan dan pengurangan.

    1. Jalankan perintah berikut untuk menambahkan FastMCP sebagai dependensi dalam file pyproject.toml:

      uv add fastmcp==2.8.0 --no-sync

    2. Tambahkan kode sumber server MCP matematika berikut dalam file server.py:

      import asyncio
import logging
import os

from fastmcp import FastMCP 

logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

mcp = FastMCP("MCP Server on Cloud Run")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Use this to add two numbers together.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'add' called with numbers '{a}' and '{b}'")
    return a + b

@mcp.tool()
def subtract(a: int, b: int) -> int:
    """Use this to subtract two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The difference of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'subtract' called with numbers '{a}' and '{b}'")
    return a - b

if __name__ == "__main__":
    logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}")
    # Could also use 'sse' transport, host="0.0.0.0" required for Cloud Run.
    asyncio.run(
        mcp.run_async(
            transport="streamable-http",
            host="0.0.0.0",
            port=os.getenv("PORT", 8080),
        )
    )

    3. Sertakan kode berikut dalam Dockerfile untuk menggunakan alat uv dalam menjalankan file server.py:

      # Use the official Python image
FROM python:3.13-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Install the project into /app
COPY . /app
WORKDIR /app

# Allow statements and log messages to immediately appear in the logs
ENV PYTHONUNBUFFERED=1

# Install dependencies
RUN uv sync

EXPOSE $PORT

# Run the FastMCP server
CMD ["uv", "run", "server.py"]

    Men-deploy ke Cloud Run

    Anda dapat men-deploy server MCP sebagai image container atau sebagai kode sumber:

    Image container

    Untuk men-deploy server MCP yang dikemas sebagai image container, ikuti petunjuk ini.

    1. Buat repositori Artifact Registry untuk menyimpan image container:

      gcloud artifacts repositories create remote-mcp-servers \
--repository-format=docker \
--location=us-central1 \
--description="Repository for remote MCP servers" \
--project=PROJECT_ID

    2. Bangun image container dan kirimkan ke Artifact Registry dengan Cloud Build:

      gcloud builds submit --region=us-central1 --tag us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest

    3. Deploy image container server MCP ke Cloud Run:

      gcloud run deploy mcp-server \
--image us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest \
--region=us-central1 \
--no-allow-unauthenticated

    Sumber

    Anda dapat men-deploy server MCP jarak jauh ke Cloud Run dari sumbernya.

    Deploy dari sumber dengan menjalankan perintah berikut:

    gcloud run deploy mcp-server --no-allow-unauthenticated --region=us-central1 --source .

    Mengautentikasi klien MCP

    Jika Anda men-deploy layanan dengan tanda --no-allow-unauthenticated, setiap klien MCP yang terhubung ke server MCP jarak jauh Anda harus melakukan autentikasi.

    1. Berikan peran Cloud Run Invoker (roles/run.invoker) ke akun layanan. Binding kebijakan Identity and Access Management ini memastikan bahwa mekanisme keamanan yang kuat digunakan untuk mengautentikasi klien MCP lokal Anda.

    2. Jalankan proxy Cloud Run untuk membuat tunnel yang diautentikasi ke server MCP jarak jauh di mesin lokal Anda:

      gcloud run services proxy mcp-server --region=us-central1

      Jika proxy Cloud Run belum diinstal, perintah ini akan meminta Anda untuk mendownload proxy. Ikuti perintah untuk mendownload dan menginstal proxy.

    Cloud Run mengautentikasi semua traffic ke http://127.0.0.1:8080 dan meneruskan permintaan ke server MCP jarak jauh.

    Menguji server MCP jarak jauh

    Anda menguji dan terhubung ke server MCP jarak jauh menggunakan klien FastMCP dan mengakses URL http://127.0.0.1:8080/mcp.

    Untuk menguji dan memanggil mekanisme penambahan dan pengurangan, ikuti langkah-langkah berikut:

    1. Sebelum menjalankan server pengujian, jalankan proxy Cloud Run.

    2. Buat file pengujian bernama test_server.py, lalu tambahkan kode berikut:

      import asyncio

from fastmcp import Client

async def test_server():
    # Test the MCP server using streamable-http transport.
    # Use "/sse" endpoint if using sse transport.
    async with Client("http://localhost:8080/mcp") as client:
        # List available tools
        tools = await client.list_tools()
        for tool in tools:
            print(f">>> 🛠️  Tool found: {tool.name}")
        # Call add tool
        print(">>> 🪛  Calling add tool for 1 + 2")
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(f"<<< ✅ Result: {result[0].text}")
        # Call subtract tool
        print(">>> 🪛  Calling subtract tool for 10 - 3")
        result = await client.call_tool("subtract", {"a": 10, "b": 3})
        print(f"<<< ✅ Result: {result[0].text}")

if __name__ == "__main__":
    asyncio.run(test_server())

    3. Di terminal baru, jalankan server pengujian:

      uv run test_server.py

      Anda akan melihat output berikut:

       🛠️ Tool found: add
 🛠️ Tool found: subtract
 🪛 Calling add tool for 1 + 2
 ✅ Result: 3
 🪛 Calling subtract tool for 10 - 3
 ✅ Result: 7

    Langkah berikutnya