Compila e implementa un servidor de MCP remoto en Cloud Run

En este instructivo, se muestra cómo compilar e implementar un servidor remoto del Protocolo de contexto del modelo (MCP) en Cloud Run con el transporte HTTP transmitible. Con el transporte HTTP transmitible, el servidor de MCP funciona como un proceso independiente que puede controlar varias conexiones de clientes.

Antes de comenzar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Configura tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.
  7. Asegúrate de tener los permisos adecuados para implementar servicios y los roles de administrador de Cloud Run (roles/run.admin) y usuario de cuenta de servicio (roles/iam.serviceAccountUser) otorgados a tu cuenta.
  8. Otorga el rol de Invocador de Cloud Run (roles/run.invoker) a tu cuenta. Este rol permite que el servidor de MCP remoto acceda al servicio de Cloud Run.

    9. Obtén más información para otorgar los roles

    Console

    1. En la consola de Google Cloud , ve a la página IAM.

      Ir a IAM
    2. Selecciona el proyecto.
    3. Haz clic en Grant access.

    4. En el campo Principales nuevas, ingresa tu identificador de usuario. Por lo general, esta es la dirección de correo electrónico de la Cuenta de Google que se usa para implementar el servicio de Cloud Run.

    5. En la lista Seleccionar un rol, elige un rol.
    6. Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega cada rol adicional.
    7. Haz clic en Guardar.

    gcloud

    Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, sigue estos pasos:

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

    Reemplaza lo siguiente:

    • PROJECT_NUMBER: Es el número de tu proyecto Google Cloud .
    • PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
    • PRINCIPAL: Es la dirección de correo electrónico de la cuenta a la que le otorgas el rol.
    • ROLE: Es el rol que agregas a la cuenta del implementador.

  9. Si estás bajo una política de la organización de restricción de dominios que restringe las invocaciones no autenticadas para tu proyecto, deberás acceder al servicio implementado como se describe en Prueba servicios privados.

  10. Instala Uv, un administrador de proyectos y paquetes de Python.

    11. Prepara tu proyecto de Python

    En los siguientes pasos, se describe cómo configurar tu proyecto de Python con el administrador de paquetes uv.

    1. Crea una carpeta llamada mcp-on-cloudrun para almacenar el código fuente de la implementación:

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

    2. Crea un proyecto de Python con la herramienta uv para generar un archivo pyproject.toml:

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

      El comando uv init crea el siguiente archivo 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. Crea los siguientes archivos nuevos adicionales:

      • server.py para el código fuente del servidor de MCP
      • test_server.py para probar el servidor remoto
      • Un Dockerfile para la implementación en Cloud Run
      touch server.py test_server.py Dockerfile

      El directorio de tu proyecto debe tener la siguiente estructura:

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

    Crea un servidor de MCP para operaciones matemáticas

    Para proporcionar contexto valioso para mejorar el uso de LLM con MCP, configura un servidor de MCP de matemáticas con FastMCP. FastMCP proporciona una forma rápida de compilar servidores y clientes de MCP con Python.

    Sigue estos pasos para crear un servidor de MCP para operaciones matemáticas, como sumas y restas.

    1. Ejecuta el siguiente comando para agregar FastMCP como dependencia en el archivo pyproject.toml:

      uv add fastmcp==2.8.0 --no-sync

    2. Agrega el siguiente código fuente del servidor del MCP de Math al archivo 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. Incluye el siguiente código en el Dockerfile para usar la herramienta uv y ejecutar el archivo 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"]

    Implementa en Cloud Run

    Puedes implementar el servidor de MCP como una imagen de contenedor o como código fuente:

    Imagen de contenedor

    Para implementar un servidor de MCP empaquetado como una imagen de contenedor, sigue estas instrucciones.

    1. Crea un repositorio de Artifact Registry para almacenar la imagen de contenedor:

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

    2. Compila la imagen de contenedor y envíala a Artifact Registry con Cloud Build:

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

    3. Implementa la imagen del contenedor del servidor de MCP en 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

    Fuente

    Puedes implementar servidores de MCP remotos en Cloud Run desde sus fuentes.

    Para realizar la implementación desde la fuente, ejecuta el siguiente comando:

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

    Autentica el cliente de MCP

    Si implementaste tu servicio con la marca --no-allow-unauthenticated, cualquier cliente de MCP que se conecte a tu servidor de MCP remoto debe autenticarse.

    1. Otorga el rol de Cloud Run Invoker (roles/run.invoker) a la cuenta de servicio. Esta vinculación de política de Identity and Access Management garantiza que se use un mecanismo de seguridad sólido para autenticar tu cliente de MCP local.

    2. Ejecuta el proxy de Cloud Run para crear un túnel autenticado hacia el servidor de MCP remoto en tu máquina local:

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

      Si el proxy de Cloud Run aún no está instalado, este comando te solicitará que lo descargues. Sigue las instrucciones para descargar e instalar el proxy.

    Cloud Run autentica todo el tráfico a http://127.0.0.1:8080 y reenvía las solicitudes al servidor de MCP remoto.

    Prueba el servidor de MCP remoto

    Probarás y te conectarás al servidor de MCP remoto con el cliente de FastMCP y accederás a la URL http://127.0.0.1:8080/mcp.

    Para probar e invocar el mecanismo de suma y resta, sigue estos pasos:

    1. Antes de ejecutar el servidor de prueba, ejecuta el proxy de Cloud Run.

    2. Crea un archivo de prueba llamado test_server.py y agrega el siguiente código:

      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. En una terminal nueva, ejecuta el servidor de prueba:

      uv run test_server.py

      Deberías ver el siguiente resultado:

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

    ¿Qué sigue?