Créer et déployer un serveur MCP distant sur Cloud Run

Ce tutoriel explique comment créer et déployer un serveur MCP (Model Context Protocol) distant sur Cloud Run à l'aide du transport HTTP flux. Avec le transport HTTP diffusable, le serveur MCP fonctionne comme un processus indépendant capable de gérer plusieurs connexions client.

Avant de commencer

  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. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
  7. Assurez-vous de disposer des autorisations appropriées pour déployer des services et que les rôles Administrateur Cloud Run (roles/run.admin) et Utilisateur du compte de service (roles/iam.serviceAccountUser) vous ont été attribués.
  8. Attribuez le rôle Demandeur Cloud Run (roles/run.invoker) à votre compte. Ce rôle permet au serveur MCP distant d'accéder au service Cloud Run.

    9. Découvrez comment attribuer les rôles.

    Console

    1. Dans la console Google Cloud , accédez à la page IAM.

      Accéder à IAM
    2. Sélectionnez le projet.
    3. Cliquez sur Accorder l'accès.

    4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail du compte Google utilisé pour déployer le service Cloud Run.

    5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
    6. Pour attribuer des rôles supplémentaires, cliquez sur Ajouter un autre rôle et ajoutez chaque rôle supplémentaire.
    7. Cliquez sur Enregistrer.

    gcloud

    Pour attribuer les rôles IAM requis à votre compte dans votre projet :

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

    Remplacez :

    • PROJECT_NUMBER : numéro de votre projet Google Cloud .
    • PROJECT_ID : ID de votre projet Google Cloud .
    • PRINCIPAL : adresse e-mail du compte auquel vous attribuez le rôle.
    • ROLE : rôle que vous ajoutez au compte du déployeur.

  9. Si vous êtes soumis à une règle d'administration de restriction de domaine limitant les appels non authentifiés pour votre projet, vous devez accéder au service déployé comme décrit dans la section Tester les services privés.

  10. Installez Uv, un gestionnaire de packages et de projets Python.

    11. Préparer votre projet Python

    Les étapes suivantes décrivent comment configurer votre projet Python avec le gestionnaire de packages uv.

    1. Créez un dossier nommé mcp-on-cloudrun pour stocker le code source à déployer :

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

    2. Créez un projet Python avec l'outil uv pour générer un fichier pyproject.toml :

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

      La commande uv init crée le fichier pyproject.toml suivant :

      [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. Créez les fichiers supplémentaires suivants :

      • server.py pour le code source du serveur MCP
      • test_server.py pour tester le serveur distant
      • Fichier Dockerfile pour le déploiement sur Cloud Run
      touch server.py test_server.py Dockerfile

      Le répertoire de votre projet doit contenir la structure suivante :

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

    Créer un serveur MCP pour les opérations mathématiques

    Pour fournir un contexte utile afin d'améliorer l'utilisation des LLM avec MCP, configurez un serveur MCP mathématique avec FastMCP. FastMCP permet de créer rapidement des serveurs et des clients MCP avec Python.

    Suivez ces étapes pour créer un serveur MCP pour les opérations mathématiques telles que l'addition et la soustraction.

    1. Exécutez la commande suivante pour ajouter FastMCP en tant que dépendance dans le fichier pyproject.toml :

      uv add fastmcp==2.8.0 --no-sync

    2. Ajoutez le code source du serveur MCP mathématique suivant dans le fichier 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. Incluez le code suivant dans le fichier Dockerfile pour utiliser l'outil uv afin d'exécuter le fichier 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"]

    Déployer dans Cloud Run

    Vous pouvez déployer le serveur MCP en tant qu'image de conteneur ou en tant que code source :

    Image du conteneur

    Pour déployer un serveur MCP empaqueté en tant qu'image de conteneur, suivez ces instructions.

    1. Créez un dépôt Artifact Registry pour stocker l'image de conteneur :

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

    2. Créez l'image de conteneur et transférez-la vers Artifact Registry avec Cloud Build :

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

    3. Déployez l'image de conteneur du serveur MCP dans 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

    Source

    Vous pouvez déployer des serveurs MCP distants sur Cloud Run à partir de leurs sources.

    Déployez votre code depuis la source en exécutant la commande suivante :

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

    Authentifier le client MCP

    Si vous avez déployé votre service avec l'option --no-allow-unauthenticated, tout client MCP qui se connecte à votre serveur MCP distant doit s'authentifier.

    1. Attribuez le rôle Demandeur Cloud Run (roles/run.invoker) au compte de service. Cette association de stratégie Identity and Access Management garantit qu'un mécanisme de sécurité renforcé est utilisé pour authentifier votre client MCP local.

    2. Exécutez le proxy Cloud Run pour créer un tunnel authentifié vers le serveur MCP distant sur votre machine locale :

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

      Si le proxy Cloud Run n'est pas encore installé, cette commande vous invite à le télécharger. Suivez les instructions pour télécharger et installer le proxy.

    Cloud Run authentifie tout le trafic vers http://127.0.0.1:8080 et transfère les requêtes au serveur MCP distant.

    Tester le serveur MCP distant

    Vous pouvez tester et vous connecter au serveur MCP distant à l'aide du client FastMCP et en accédant à l'URL http://127.0.0.1:8080/mcp.

    Pour tester et appeler le mécanisme d'addition et de soustraction, procédez comme suit :

    1. Avant d'exécuter le serveur de test, exécutez le proxy Cloud Run.

    2. Créez un fichier de test appelé test_server.py et ajoutez le code suivant :

      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. Dans un nouveau terminal, exécutez le serveur de test :

      uv run test_server.py

      Vous devriez obtenir le résultat suivant :

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

    Étapes suivantes