Cloud Run에 원격 MCP 서버 빌드 및 배포

이 튜토리얼에서는 스트리밍 가능한 HTTP 전송을 사용하여 Cloud Run에 원격 모델 컨텍스트 프로토콜 (MCP) 서버를 빌드하고 배포하는 방법을 보여줍니다. 스트리밍 가능한 HTTP 전송을 사용하면 MCP 서버가 여러 클라이언트 연결을 처리할 수 있는 독립 프로세스로 작동합니다.

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. 다음과 같은 새 파일을 추가로 만듭니다.

   • MCP 서버 소스 코드의 경우 server.py
   • test_server.py를 사용하여 원격 서버를 테스트합니다.
   • Cloud Run에 배포하기 위한 Dockerfile

   touch server.py test_server.py Dockerfile
   

   프로젝트 디렉터리에는 다음 구조가 포함되어야 합니다.

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

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

MCP로 LLM 사용을 개선하는 데 유용한 컨텍스트를 제공하려면 FastMCP로 수학 MCP 서버를 설정하세요. FastMCP는 Python으로 MCP 서버와 클라이언트를 빠르게 빌드하는 방법을 제공합니다.

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

1. 다음 명령어를 실행하여 pyproject.toml 파일에 FastMCP를 종속 항목으로 추가합니다.

   uv add fastmcp==2.8.0 --no-sync
   

2. 다음 수학 MCP 서버 소스 코드를 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. 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 서버를 배포하려면 다음 안내를 따르세요.

1. 컨테이너 이미지를 저장할 Artifact Registry 저장소를 만듭니다.

   gcloud artifacts repositories create remote-mcp-servers \
   --repository-format=docker \
   --location=us-central1 \
   --description="Repository for remote MCP servers" \
   --project=PROJECT_ID
   

2. Cloud Build로 컨테이너 이미지를 빌드하고 Artifact Registry에 푸시합니다.

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

3. MCP 서버 컨테이너 이미지를 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
   

소스

소스에서 원격 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) 역할을 부여합니다. 이 Identity and Access Management 정책 바인딩은 강력한 보안 메커니즘이 로컬 MCP 클라이언트를 인증하는 데 사용되도록 합니다.

2. 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 서버를 테스트하고 연결합니다.

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

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

2. test_server.py라는 테스트 파일을 만들고 다음 코드를 추가합니다.

   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. 새 터미널에서 테스트 서버를 실행합니다.

   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 서버를 Cloud Run에 배포하고 FastMCP 클라이언트를 사용하여 테스트했습니다.