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 mencakup instrumentasi OpenTelemetry yang mengumpulkan telemetri dari semua operasi MCP.

Dokumen ini menjelaskan langkah-langkah berikut:

Siapkan project Python Anda dengan uv pengelola paket.
Buat server MCP untuk operasi matematika.
Deploy ke Cloud Run.
Autentikasi klien MCP.
Uji server MCP yang dihosting sendiri.
Lihat data telemetri Anda.

Sebelum memulai

Login ke akun Google Cloud Anda. 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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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

Di konsol Google Cloud , buka halaman IAM.
Buka IAM
Pilih project.
Klik Grant access.
Di kolom New principals, masukkan ID pengguna Anda. Identitas ini biasanya berupa alamat email yang digunakan untuk men-deploy layanan Cloud Run.
Di daftar Select a role, pilih peran.
Untuk memberikan peran tambahan, klik Tambahkan peran lain, lalu tambahkan setiap peran tambahan.
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_ID: ID project.
PRINCIPAL: ID untuk akun utama yang ingin Anda berikan peran. ID utama biasanya memiliki bentuk berikut: PRINCIPAL-TYPE:ID. Misalnya, user:my-user@example.com. Untuk mengetahui daftar lengkap format yang dapat dimiliki PRINCIPAL, lihat ID utama.
ROLE: Peran IAM.

Jika Anda dikenai kebijakan organisasi pembatasan domain yang membatasi pemanggilan yang tidak terautentikasi untuk project, Anda harus mengakses layanan yang di-deploy seperti yang dijelaskan di bagian Menguji layanan pribadi.
Instal Uv, pengelola project dan paket Python.

Menyiapkan project Python

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

Buat folder bernama mcp-on-cloudrun untuk menyimpan kode sumber yang akan di-deploy:
```
  mkdir mcp-on-cloudrun
  cd mcp-on-cloudrun
```

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 = []

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.

Jalankan perintah berikut untuk menambahkan FastMCP sebagai dependensi dalam file pyproject.toml:
```
uv add fastmcp==2.13.1 --no-sync
```

Tambahkan kode penyiapan OpenTelemetry berikut di 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.")

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

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

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

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

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, setiap klien MCP yang terhubung ke server MCP yang dihosting sendiri harus melakukan autentikasi.

Berikan peran Cloud Run Invoker (roles/run.invoker) ke akun layanan. Pengikatan kebijakan Identity and Access Management ini memastikan bahwa mekanisme keamanan yang kuat digunakan untuk mengautentikasi klien MCP lokal Anda.
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 dengan 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:

Sebelum menjalankan server pengujian, jalankan proxy Cloud Run.

Buat file pengujian bernama test_server.py, lalu 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())

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 rekaman aktivitas yang dihasilkan oleh server MCP yang dihosting sendiri.

Sebelum memulai

Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan rekaman aktivitas, minta administrator 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 rekaman aktivitas, lihat artikel berikut:

Data log

Di konsol Google Cloud , buka 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 konsol Google Cloud , buka halaman Metrics explorer:

Buka Metrics explorer

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

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

Data rekaman aktivitas

Di konsol Google Cloud , buka halaman Trace explorer:

Buka Trace explorer

Anda juga dapat menemukan halaman ini dengan menggunakan kotak penelusuran.

Screenshot berikut menggambarkan panel Detail di halaman Trace Explorer, yang menampilkan rentang rekaman aktivitas yang dihasilkan dari operasi tools/call:

Panel detail yang menampilkan rekaman aktivitas dan rentang terkaitnya.

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

Langkah berikutnya

Pelajari lebih lanjut opsi yang tersedia 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.

Menginstrumentasi server MCP yang dihosting sendiri dengan OpenTelemetry Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Pelajari cara memberikan peran

Konsol

gcloud

Menyiapkan project Python

Membuat server MCP untuk operasi matematika

Men-deploy ke Cloud Run

Image container

Sumber

Mengautentikasi klien MCP

Menguji server MCP yang dihosting sendiri

Melihat data telemetri Anda

Sebelum memulai

Melihat telemetri

Data log

Data metrik

Data rekaman aktivitas

Langkah berikutnya

Menginstrumentasi server MCP yang dihosting sendiri dengan OpenTelemetry