OpenTelemetry를 사용하여 자체 호스팅 MCP 서버 계측

이 문서에서는 자체 호스팅 모델 컨텍스트 프로토콜 (MCP) 서버를 계측하고 배포하여 원격 분석을 수집하는 단계를 설명합니다. 이 문서의 예에서는 FastMCP를 사용하여 MCP 서버를 빌드하고 Cloud Run을 사용하여 MCP 서버를 배포합니다. FastMCP에는 모든 MCP 작업에서 원격 분석을 수집하는 OpenTelemetry 계측이 포함됩니다.

이 문서에서는 다음 단계를 설명합니다.

uv 패키지 관리자로 Python 프로젝트를 준비합니다.
수학 연산을 위한 MCP 서버를 만듭니다.
Cloud Run에 배포
MCP 클라이언트 인증
자체 호스팅 MCP 서버 테스트
원격 분석 데이터 보기

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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.

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.

Artifact Registry, Cloud Run, Cloud Build, Telemetry, Cloud Logging, Cloud Monitoring, Cloud Trace API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기
API 사용 설정

Google Cloud 프로젝트에서 Cloud Run 개발 환경을 설정합니다.
서비스를 배포할 적절한 권한이 있고 Cloud Run 관리자(roles/run.admin) 및 서비스 계정 사용자(roles/iam.serviceAccountUser) 역할이 계정에 부여되어 있는지 확인합니다.
계정에 Cloud Run 호출자(roles/run.invoker) 역할을 부여합니다. 이 역할을 통해 자체 호스팅 MCP 서버가 Cloud Run 서비스에 액세스할 수 있습니다.

역할 부여 방법 알아보기

콘솔

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
IAM으로 이동
프로젝트를 선택합니다.
액세스 권한 부여를 클릭합니다.
새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Cloud Run 서비스를 배포하는 데 사용되는 이메일 주소입니다.
역할 선택 목록에서 역할을 선택합니다.
역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
저장을 클릭합니다.

gcloud

프로젝트에서 계정에 필요한 IAM 역할을 부여하려면 다음 안내를 따르세요.

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

다음과 같이 바꿉니다.

PROJECT_ID: 프로젝트 식별자
PRINCIPAL: 역할을 부여할 주 구성원의 식별자. 주 구성원 식별자는 일반적으로 PRINCIPAL-TYPE:ID 형식입니다. 예를 들면 user:my-user@example.com입니다. PRINCIPAL 형식 전체 목록은 주 구성원 식별자를 참조하세요.
ROLE: IAM 역할

프로젝트에서 인증되지 않은 호출을 제한하는 도메인 제한 조직 정책이 적용되는 경우 비공개 서비스 테스트에 설명된 대로 배포된 서비스에 액세스해야 합니다.
Python 패키지 및 프로젝트 매니저인 Uv를 설치합니다.

Python 프로젝트 준비

다음 단계에서는 uv 패키지 관리자를 사용하여 Python 프로젝트를 설정하는 방법을 설명합니다.

배포할 소스 코드를 저장할 mcp-on-cloudrun이라는 폴더를 만듭니다.
```
  mkdir mcp-on-cloudrun
  cd mcp-on-cloudrun
```

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

다음과 같은 새 파일을 추가로 만듭니다.
- 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는 Python으로 MCP 서버와 클라이언트를 빠르게 빌드하는 방법을 제공합니다.

덧셈, 뺄셈과 같은 수학 연산을 위한 MCP 서버를 만들려면 다음 단계를 따르세요.

다음 명령어를 실행하여 pyproject.toml 파일에 FastMCP를 종속 항목으로 추가합니다.
```
uv add fastmcp==2.13.1 --no-sync
```

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.")

다음 수학 MCP 서버 소스 코드를 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),
        )
    )

server.py 파일을 실행하는 데 uv 도구를 사용하려면 Dockerfile에 다음 코드를 포함하세요.

# 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 서버를 배포하려면 다음 안내를 따르세요.

컨테이너 이미지를 저장할 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

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

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 클라이언트에서 인증을 수행해야 합니다.

서비스 계정에 Cloud Run 호출자(roles/run.invoker) 역할을 부여합니다. 이 Identity and Access Management 정책 바인딩은 강력한 보안 메커니즘을 사용하여 로컬 MCP 클라이언트를 인증하게 합니다.
Cloud Run 프록시를 실행하여 로컬 머신의 자체 호스팅 MCP 서버로 인증된 터널을 만듭니다.
```
gcloud run services proxy mcp-server --region=us-central1
```
Cloud Run 프록시가 아직 설치되지 않은 경우 이 명령어는 프록시를 다운로드하라는 메시지를 표시합니다. 표시되는 메시지에 따라 프록시를 다운로드하고 설치합니다.

Cloud Run은 http://127.0.0.1:8080으로 향하는 모든 트래픽을 인증하고 요청을 자체 호스팅 MCP 서버로 전달합니다.

자체 호스팅 MCP 서버 테스트

FastMCP 클라이언트를 사용하고 URL http://127.0.0.1:8080/mcp에 액세스하여 자체 호스팅 MCP 서버를 테스트하고 연결합니다.

덧셈 및 뺄셈 메커니즘을 테스트하고 호출하려면 다음 단계를 따르세요.

테스트 서버를 실행하기 전에 Cloud Run 프록시를 실행합니다.

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

새 터미널에서 테스트 서버를 실행합니다.

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 서버에서 생성하는 로그, 측정항목, 트레이스 데이터를 보는 방법을 설명합니다.

시작하기 전에

로그, 측정항목, trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

로그 뷰어(roles/logging.viewer)
모니터링 뷰어(roles/monitoring.viewer)
Cloud Trace 사용자(roles/cloudtrace.user)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

원격 분석 보기

로그, 측정항목, trace 데이터를 보는 방법을 알아보려면 다음을 참고하세요.

로그 데이터

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

로그 탐색기 페이지 사용에 대한 자세한 내용은 로그 보기 및 분석을 참고하세요.

측정항목 데이터

Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.

측정항목 탐색기로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.

측정항목 탐색기 페이지 사용에 대한 자세한 내용은 측정항목 탐색기로 차트 만들기를 참고하세요.

Trace 데이터

Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.

Trace 탐색기로 이동

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

다음 스크린샷은 Trace 탐색기 페이지의 세부정보 창을 보여줍니다. 이 창에는 tools/call 작업에서 생성된 추적 스팬이 표시됩니다.

trace와 연결된 스팬을 보여주는 세부정보 창

Trace 탐색기 페이지 사용에 대한 자세한 내용은 trace 찾기 및 탐색을 참고하세요.

다음 단계

원격 분석 데이터를 보고, 탐색하고, 분석할 수 있는 옵션에 대해 자세히 알아보세요.
Cloud Run에서 MCP 서버 호스팅에 대해 자세히 알아보세요.
MCP 서버를 사용하여 Cloud Run에 코드를 배포하는 방법을 알아봅니다.

OpenTelemetry를 사용하여 자체 호스팅 MCP 서버 계측 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

역할 부여 방법 알아보기

콘솔

gcloud

Python 프로젝트 준비

수학 연산을 위한 MCP 서버 만들기

Cloud Run에 배포

컨테이너 이미지

소스

MCP 클라이언트 인증

자체 호스팅 MCP 서버 테스트

원격 분석 데이터 보기

시작하기 전에

원격 분석 보기

로그 데이터

측정항목 데이터

Trace 데이터

다음 단계

OpenTelemetry를 사용하여 자체 호스팅 MCP 서버 계측