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 transmisible. Con el transporte HTTP transmisible, el servidor de MCP opera como un proceso independiente que puede controlar varias conexiones de clientes.

Objetivos

En este instructivo, podrás:

Preparar tu proyecto de Python con el administrador de paquetes uv.
Crear un servidor de MCP para operaciones matemáticas.
Implementar en Cloud Run.
Autenticar el cliente de MCP.
Probar el servidor de MCP remoto.

Costos

En este documento, usas los siguientes componentes facturables de Google Cloud

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios Google Cloud nuevos decumplan con los requisitos para acceder a una prueba gratuita.

Antes de comenzar

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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.

Habilita las APIs de Artifact Registry, Cloud Run Admin y Cloud Build.
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.
Habilitar las API

Configura tu entorno de desarrollo de Cloud Run en tu Google Cloud proyecto.
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.
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.

Obtén información para otorgar los roles

Console

En la Google Cloud consola de, dirígete a la página IAM.
Ir a IAM
Selecciona el proyecto.
Haz clic en Grant access.
En el campo Principales nuevas, ingresa tu identificador de usuario. Por lo general, es la dirección de correo electrónico que se usa para implementar el servicio de Cloud Run.
En la lista Seleccionar un rol, elige uno.
Para otorgar roles adicionales, haz clic en Agregar otro rol y agrega uno más.
Haz clic en Guardar.

gcloud

Para otorgar los roles de IAM necesarios a tu cuenta en tu proyecto, haz lo siguiente:

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

Reemplaza lo siguiente:

PROJECT_NUMBER: Es el número del proyecto de Google Cloud
PROJECT_ID: Es el ID del Google Cloud proyecto de.
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.

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.
Instala Uv, un administrador de proyectos y paquetes de Python.

Prepara tu proyecto de Python

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

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
```

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

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 implementar en Cloud Run
```
touch server.py test_server.py Dockerfile
```
El directorio de tu proyecto debe contener 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 un contexto valioso para mejorar el uso de LLMs con MCP, configura un servidor de MCP matemático 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 la suma y la resta.

Ejecuta el siguiente comando para agregar FastMCP como una dependencia en el archivo pyproject.toml:
```
uv add fastmcp==2.13.1 --no-sync
```

Agrega el siguiente código fuente del servidor de MCP matemático en el 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),
        )
    )

Incluye el siguiente código en el Dockerfile para usar la herramienta uv para 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.

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

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

Implementa la imagen de 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.

Otorga el rol de invocador de Cloud Run (roles/run.invoker) a la cuenta de servicio. Esta vinculación de políticas de Identity and Access Management garantiza que se use un mecanismo de seguridad sólido para autenticar tu cliente de MCP local.
Ejecuta el proxy de Cloud Run para crear un túnel autenticado al 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 indicaciones 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

Para probar el servidor de MCP remoto y conectarte a él, usa el cliente de FastMCP y accede a la URL http://127.0.0.1:8080/mcp.

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

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

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

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

Limpia

Para evitar cargos adicionales en tu Google Cloud cuenta de, borra todos los recursos que implementaste con este instructivo.

Borra el proyecto

Si creaste un proyecto nuevo para este instructivo, bórralo. Si usaste un proyecto existente y necesitas conservarlo sin los cambios que agregaste en este instructivo, borra los recursos que creaste para el instructivo.

La manera más fácil de eliminar la facturación es borrar el proyecto que tú creaste para el instructivo.

Para borrar el proyecto, sigue estos pasos:

Precaución: Borrar un proyecto tiene estas consecuencias:

Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

En la Google Cloud consola, ve a la página Administrar recursos.
Ir a Administrar recursos
En la lista de proyectos, elige el proyecto que tú quieres borrar y haz clic en Borrar.
En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

Elimina recursos de instructivos

Borra el servicio de Cloud Run que implementaste en este instructivo. Los servicios de Cloud Run no generan costos hasta que reciben solicitudes.

Para borrar tu servicio de Cloud Run, ejecuta el siguiente comando:
```
gcloud run services delete SERVICE-NAME
```
Reemplaza SERVICE-NAME por el nombre del servicio.

También puedes borrar los servicios de Cloud Run desde la Google Cloud consola.
Quita la configuración de región predeterminada de gcloud que agregaste durante la configuración en el instructivo:
```
 gcloud config unset run/region
```
Quita la configuración del proyecto:
```
 gcloud config unset project
```

Compila e implementa un servidor de MCP remoto en Cloud Run Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Objetivos

Costos

Antes de comenzar

Obtén información para otorgar los roles

Console

gcloud

Prepara tu proyecto de Python

Crea un servidor de MCP para operaciones matemáticas

Implementa en Cloud Run

Imagen de contenedor

Fuente

Autentica el cliente de MCP

Prueba el servidor de MCP remoto

Limpia

Borra el proyecto

Elimina recursos de instructivos

Compila e implementa un servidor de MCP remoto en Cloud Run