Menginstrumentasi server MCP yang dihosting sendiri dengan OpenTelemetry

Dokumen ini menguraikan langkah-langkah untuk menginstrumentasi dan men-deploy server Model Context Protocol (MCP) yang dihosting sendiri, sehingga memungkinkan pengumpulan telemetri. Contoh dalam dokumen ini membangun server MCP menggunakan FastMCP dan men-deploy server MCP menggunakan Cloud Run. FastMCP menyertakan instrumentasi OpenTelemetry yang mengumpulkan telemetri dari semua operasi MCP.

Dokumen ini menjelaskan langkah-langkah berikut:

1. Menyiapkan project Python Anda dengan pengelola paket uv.
2. Membuat server MCP untuk operasi matematika.
3. Men-deploy ke Cloud Run.
4. Mengautentikasi klien MCP.
5. Menguji server MCP yang dihosting sendiri.
6. Melihat data telemetri Anda.

Sebelum memulai

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Aktifkan Artifact Registry, Cloud Run, Cloud Build, Telemetry, Cloud Logging, Cloud Monitoring, dan Cloud Trace API.

   Peran yang diperlukan untuk mengaktifkan API

   Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

   Aktifkan API

2. Siapkan lingkungan pengembangan Cloud Run di Google Cloud project Anda.
3. Pastikan Anda memiliki izin yang sesuai untuk men-deploy layanan, serta peran Cloud Run Admin (roles/run.admin) dan Service Account User (roles/iam.serviceAccountUser) yang diberikan ke akun Anda.
4. Berikan peran Cloud Run Invoker (roles/run.invoker) ke akun Anda. Peran ini memungkinkan server MCP yang dihosting sendiri mengakses layanan Cloud Run.

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_ID: ID project.
• PRINCIPAL: ID untuk principal yang ingin Anda berikan peran. ID principal biasanya memiliki format berikut: PRINCIPAL-TYPE:ID. Misalnya, user:[e-mail]. Untuk mengetahui daftar lengkap format yang dapat dimiliki PRINCIPAL, lihat ID principal.
• ROLE: Peran IAM.

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

6. Instal Uv, pengelola project dan paket Python.

Menyiapkan project Python Anda

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

1. Buat folder bernama mcp-on-cloudrun untuk menyimpan kode sumber untuk deployment:

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

2. Buat project Python dengan alat uv untuk membuat 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.
   • otel_setup.py untuk mengonfigurasi OpenTelemetry.
   • test_server.py untuk menguji server yang dihosting sendiri.
   • Dockerfile untuk men-deploy ke Cloud Run.

   touch server.py otel_setup.py test_server.py Dockerfile
   

   Direktori project Anda harus berisi struktur berikut:

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

Membuat server MCP untuk operasi matematika

Di bagian ini, Anda akan menyiapkan 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 dan dependensi OpenTelemetry yang diperlukan dalam file pyproject.toml:

   uv add fastmcp==3.2.0 opentelemetry-api==1.40.0 opentelemetry-sdk==1.40.0 opentelemetry-exporter-otlp-proto-grpc==1.40.0 --no-sync
   

2. Tambahkan kode penyiapan OpenTelemetry berikut dalam file otel_setup.py:

   import logging
   import google.auth
   import google.auth.transport.requests
   import grpc
   from google.auth.transport.grpc import AuthMetadataPlugin
   from opentelemetry import trace
   from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
       OTLPSpanExporter,
   )
   from opentelemetry.sdk.resources import SERVICE_NAME, Resource
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   
   logger = logging.getLogger(__name__)
   
   
   def setup_opentelemetry(service_name: str) -> None:
       """Sets up OpenTelemetry to send traces to Google Cloud Observability."""
       credentials, project_id = google.auth.default()
       if not project_id:
           raise Exception("Could not determine Google Cloud project ID.")
   
       resource = Resource.create(
           attributes={
               SERVICE_NAME: service_name,
               "gcp.project_id": project_id,
           }
       )
   
       # Set up OTLP auth
       request = google.auth.transport.requests.Request()
       auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
       channel_creds = grpc.composite_channel_credentials(
           grpc.ssl_channel_credentials(),
           grpc.metadata_call_credentials(auth_metadata_plugin),
       )
   
       # Set up OpenTelemetry Python SDK
       tracer_provider = TracerProvider(resource=resource)
       tracer_provider.add_span_processor(
           BatchSpanProcessor(
               OTLPSpanExporter(
                   credentials=channel_creds,
                   endpoint="https://telemetry.googleapis.com:443/v1/traces",
               )
           )
       )
       trace.set_tracer_provider(tracer_provider)
       logger.info("OpenTelemetry successfully initialized.")
   
   

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

   from otel_setup import setup_opentelemetry
   setup_opentelemetry("mcp-server")
   
   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),
           )
       )
   

4. Sertakan kode berikut dalam Dockerfile untuk menggunakan alat uv guna 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 berikut.

1. Buat repositori Artifact Registry untuk menyimpan image container:

   gcloud artifacts repositories create self-hosted-mcp-servers \
   --repository-format=docker \
   --location=us-central1 \
   --description="Repository for self-hosted 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/self-hosted-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/self-hosted-mcp-servers/mcp-server:latest \
   --region=us-central1 \
   --no-allow-unauthenticated
   

Sumber

Anda dapat men-deploy server MCP yang dihosting sendiri 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, klien MCP yang terhubung ke server MCP yang dihosting sendiri harus diautentikasi.

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 yang dihosting sendiri 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 yang dihosting sendiri.

Menguji server MCP yang dihosting sendiri

Anda menguji dan terhubung ke server MCP yang dihosting sendiri 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 dan tambahkan kode berikut:

   from otel_setup import setup_opentelemetry
   setup_opentelemetry("test-server")
   
   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.content[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.content[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
   

Melihat data telemetri Anda

Bagian ini menjelaskan cara melihat data log, metrik, dan trace yang dihasilkan oleh server MCP yang dihosting sendiri.

Sebelum memulai

Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan trace, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

• Logs Viewer (roles/logging.viewer)
• Monitoring Viewer (roles/monitoring.viewer)
• Cloud Trace User (roles/cloudtrace.user)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Melihat telemetri

Untuk mempelajari cara melihat data log, metrik, dan trace, lihat hal berikut:

Data log

Di Google Cloud konsol, buka halaman segmen Logs Explorer:

Buka Logs Explorer

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Logging.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan halaman Logs Explorer, lihat Melihat dan menganalisis log.

Data metrik

Di Google Cloud konsol, buka halaman  Metrics explorer:

Buka Metrics explorer

Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan halaman Metrics Explorer, lihat Membuat diagram dengan Metrics Explorer.

Data trace

Di Google Cloud konsol, buka halaman Trace explorer:

Buka Trace explorer

Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

Screenshot berikut menggambarkan panel Details di halaman Trace Explorer, yang menampilkan rentang trace yang dihasilkan dari operasi tools/call:

Untuk mengetahui informasi selengkapnya tentang cara menggunakan halaman Trace Explorer, lihat Menemukan dan menjelajahi trace.

Langkah berikutnya

• Pelajari cara menyelidiki panggilan MCP menggunakan Cloud Trace.

• Pelajari lebih lanjut opsi yang Anda miliki untuk melihat, menjelajahi, dan menganalisis data telemetri Anda.

• Pelajari lebih lanjut cara menghosting server MCP di Cloud Run.

• Pelajari cara menggunakan server MCP untuk men-deploy kode ke Cloud Run.