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.

Tujuan

Dalam tutorial ini, Anda akan:

  1. Siapkan project Python Anda dengan pengelola paket uv.
  2. Buat server MCP untuk operasi matematika.
  3. Deploy ke Cloud Run.
  4. Autentikasi klien MCP.
  5. Uji server MCP jarak jauh.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

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. Enable the Artifact Registry, Cloud Run Admin API, and Cloud Build APIs.

    Enable the APIs

  7. Siapkan lingkungan pengembangan Cloud Run di project Google Cloud Anda.
  8. 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.
  9. Berikan peran Cloud Run Invoker (roles/run.invoker) ke akun Anda. Peran ini memungkinkan server MCP jarak jauh mengakses layanan Cloud Run.

    10. Pelajari cara memberikan peran

    Konsol

    1. Di konsol Google Cloud , buka halaman IAM.

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

    4. Di kolom New principals, masukkan ID pengguna Anda. 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 Anda. Google Cloud
    • PROJECT_ID: ID project Google Cloud Anda.
    • PRINCIPAL: alamat email akun yang Anda beri peran.
    • ROLE: peran yang Anda tambahkan ke akun deployer.

  10. 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.

  11. Instal Uv, pengelola project dan paket Python.

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

Pembersihan

Untuk menghindari biaya tambahan pada akun Google Cloud Anda, hapus semua resource yang Anda deploy dengan tutorial ini.

Menghapus project

Jika Anda membuat project baru untuk tutorial ini, hapus project tersebut. Jika Anda menggunakan project yang ada dan perlu mempertahankannya tanpa perubahan yang Anda tambahkan dalam tutorial ini, hapus resource yang Anda buat untuk tutorial.

Cara termudah untuk menghilangkan penagihan adalah dengan menghapus project yang Anda buat untuk tutorial.

Untuk menghapus project:

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Menghapus resource tutorial

  1. Hapus layanan Cloud Run yang Anda deploy dalam tutorial ini. Layanan Cloud Run tidak menimbulkan biaya hingga menerima permintaan.

    Untuk menghapus layanan Cloud Run, jalankan perintah berikut:

    gcloud run services delete SERVICE-NAME

    Ganti SERVICE-NAME dengan nama layanan Anda.

    Anda juga dapat menghapus layanan Cloud Run dari Google Cloud console.

  2. Hapus konfigurasi region default gcloud yang Anda tambahkan selama penyiapan tutorial:

     gcloud config unset run/region

  3. Hapus konfigurasi project:

     gcloud config unset project