使用 OpenTelemetry 檢測自行代管的 MCP 伺服器

本文將說明如何檢測及部署自行代管的 Model Context Protocol (MCP) 伺服器，以收集遙測資料。本文中的範例會使用 FastMCP 建構 MCP 伺服器，並使用 Cloud Run 部署 MCP 伺服器。FastMCP 包含 OpenTelemetry 檢測，可從所有 MCP 作業收集遙測資料。

本文說明下列步驟：

1. 使用 uv 套件管理工具準備 Python 專案。
2. 建立 MCP 伺服器來執行數學運算。
3. 部署至 Cloud Run。
4. 驗證 MCP 用戶端。
5. 測試自行代管的 MCP 伺服器。
6. 查看遙測資料。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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. 啟用 Artifact Registry、Cloud Run、Cloud Build、Telemetry、Cloud Logging、Cloud Monitoring 和 Cloud Trace API。

   啟用 API 時所需的角色

   如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

   啟用 API

2. 在 Google Cloud 專案中設定 Cloud Run 開發環境。
3. 請確認您具備部署服務的適當權限，且帳戶已獲派 Cloud Run 管理員 (roles/run.admin) 和服務帳戶使用者 (roles/iam.serviceAccountUser) 角色。
4. 將 Cloud Run Invoker (roles/run.invoker) 角色授予您的帳戶。這個角色可讓自行託管的 MCP 伺服器存取 Cloud Run 服務。

瞭解如何授予角色

控制台

1. 前往 Google Cloud 控制台的「IAM」頁面。

   前往「IAM」頁面
2. 選取專案。
3. 按一下 「授予存取權」。

4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。這通常是部署 Cloud Run 服務時使用的電子郵件地址。

5. 在「Select a role」(選取角色) 清單中，選取角色。
6. 如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
7. 按一下「儲存」。

gcloud

如要在專案中授予帳戶必要的 IAM 角色，請按照下列步驟操作：

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL \
       --role=ROLE
   

更改項目：

• PROJECT_ID：專案的 ID。
• PRINCIPAL：要授予角色的主體 ID。主體 ID 通常採用以下格式： PRINCIPAL-TYPE:ID。 例如：user:[e-mail]。如需 PRINCIPAL 的完整格式清單，請參閱「主體 ID」。
• ROLE：IAM 角色。

5. 如果專案受到網域限制組織政策限制，無法進行未經驗證的呼叫，則必須按照「測試私人服務」一文的說明存取已部署的服務。

6. 安裝 Python 套件和專案管理員 Uv。

準備 Python 專案

下列步驟說明如何使用 uv 套件管理工具設定 Python 專案。

1. 建立名為 mcp-on-cloudrun 的資料夾，用於儲存部署作業的原始碼：

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

2. 使用 uv 工具建立 Python 專案，產生 pyproject.toml 檔案：

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

   uv init 指令會建立下列 pyproject.toml 檔案：

   [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. 建立下列其他新檔案：

   • server.py，取得 MCP 伺服器原始碼。
   • otel_setup.py，設定 OpenTelemetry。
   • test_server.py 測試自行託管的伺服器。
   • 用於部署至 Cloud Run 的 Dockerfile。

   touch server.py otel_setup.py test_server.py Dockerfile
   

   專案目錄應包含下列結構：

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

建立 MCP 伺服器以執行數學運算

在本節中，您將使用 FastMCP 設定數學 MCP 伺服器。FastMCP 提供快速建構 MCP 伺服器和用戶端的方法 (使用 Python)。

請按照下列步驟建立 MCP 伺服器，用於加法和減法等數學運算。

1. 執行下列指令，將 FastMCP 新增為 pyproject.toml 檔案中的依附元件：

   uv add fastmcp==2.13.1 --no-sync
   

2. 在 otel_setup.py 檔案中新增下列 OpenTelemetry 設定程式碼：

   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. 在 server.py 檔案中新增下列數學 MCP 伺服器原始碼：

   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. 在 Dockerfile 中加入下列程式碼，即可使用 uv 工具執行 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"]
   

部署至 Cloud Run

您可以將 MCP 伺服器部署為容器映像檔 或原始碼：

容器映像檔

如要部署封裝為容器映像檔的 MCP 伺服器，請按照下列操作說明進行。

1. 建立 Artifact Registry 存放區來儲存容器映像檔：

   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. 使用 Cloud Build 建構容器映像檔並推送至 Artifact Registry：

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

3. 將 MCP 伺服器容器映像檔部署至 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
   

來源

您可以從來源將自行代管的 MCP 伺服器部署至 Cloud Run。

執行下列指令，從來源部署：

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

驗證 MCP 用戶端

如果您使用 --no-allow-unauthenticated 旗標部署服務，連線至自架 MCP 伺服器的任何 MCP 用戶端都必須通過驗證。

1. 將 Cloud Run 叫用者 (roles/run.invoker) 角色授予服務帳戶。這項身分與存取權管理政策繫結可確保使用強大的安全機制，驗證本機 MCP 用戶端。

2. 執行 Cloud Run Proxy，在本機電腦上建立通過驗證的通道，連線至自行託管的 MCP 伺服器：

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

   如果尚未安裝 Cloud Run Proxy，這項指令會提示您下載 Proxy。按照提示下載並安裝 Proxy。

Cloud Run 會驗證傳送至 http://127.0.0.1:8080 的所有流量，並將要求轉送至自行代管的 MCP 伺服器。

測試自行託管的 MCP 伺服器

您可以使用 FastMCP 用戶端測試及連線至自行代管的 MCP 伺服器，並存取 http://127.0.0.1:8080/mcp 網址。

如要測試及叫用加減機制，請按照下列步驟操作：

1. 執行測試伺服器前，請執行 Cloud Run Proxy。

2. 建立名為 test_server.py 的測試檔案，並加入下列程式碼：

   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. 在新的終端機中執行測試伺服器：

   uv run test_server.py
   

   您應該會看到以下的輸出內容：

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

查看遙測資料

本節說明如何查看自行託管的 MCP 伺服器產生的記錄、指標和追蹤記錄資料。

事前準備

如要取得查看記錄、指標和追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 記錄檢視器 (roles/logging.viewer)
• Monitoring 檢視者 (roles/monitoring.viewer)
• Cloud Trace 使用者 (roles/cloudtrace.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

查看遙測資料

如要瞭解如何查看記錄、指標和追蹤記錄資料，請參閱下列文章：

記錄檔資料

前往 Google Cloud 控制台的 segment「Logs Explorer」頁面：

前往「Logs Explorer」(記錄檔探索工具)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

如要進一步瞭解如何使用「Logs Explorer」頁面，請參閱「查看及分析記錄檔」。

指標資料

前往 Google Cloud 控制台的 「指標探索器」頁面：

前往 Metrics Explorer

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

如要進一步瞭解如何使用「Metrics Explorer」頁面，請參閱「使用 Metrics Explorer 建立圖表」一文。

追蹤資料

前往 Google Cloud 控制台的 「Trace Explorer」頁面：

前往「Trace explorer」(Trace 探索工具)

您也可以透過搜尋列找到這個頁面。

以下螢幕截圖顯示「Trace Explorer」(追蹤記錄探索器) 頁面中的「Details」(詳細資料) 窗格，其中顯示從 tools/call 作業產生的追蹤記錄範圍：

如要進一步瞭解如何使用「Trace 探索工具」頁面，請參閱「尋找及探索追蹤記錄」。

後續步驟

• 進一步瞭解如何查看、探索及分析遙測資料。

• 進一步瞭解在 Cloud Run 託管 MCP 伺服器。

• 瞭解如何使用 MCP 伺服器將程式碼部署至 Cloud Run。