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 en flux. Avec le transport HTTP en flux, le serveur MCP fonctionne comme un processus indépendant capable de gérer plusieurs connexions client.

Objectifs

Au cours de ce tutoriel, vous allez :

Préparer votre projet Python avec le gestionnaire de packages uv.
Créer un serveur MCP pour les opérations mathématiques.
Déployer une application sur Cloud Run.
Authentifier le client MCP.
Tester le serveur MCP distant.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud:

Obtenez une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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.

Activez les API Artifact Registry, Cloud Run Admin et Cloud Build.
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.
Activer les API

Configurez votre environnement de développement Cloud Run dans votre Google Cloud projet.
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) sont attribués à votre compte.
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.

Découvrez comment attribuer les rôles

Console

Dans la console Google Cloud , accédez à la page IAM.
Accéder à IAM
Sélectionnez le projet.
Cliquez sur Accorder l'accès.
Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail utilisée pour déployer le service Cloud Run.
Dans la liste Sélectionner un rôle, sélectionnez un rôle.
Pour attribuer des rôles supplémentaires, cliquez sur Add another role , puis ajoutez chaque rôle supplémentaire.
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 : votre Google Cloud projet numéro.
PROJECT_ID: ID de votre Google Cloud projet.
PRINCIPAL : adresse e-mail du compte auquel vous attribuez le rôle.
ROLE : rôle que vous ajoutez au compte du déployeur.

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.
Installez Uv, un gestionnaire de packages et de projets Python.

Préparer votre projet Python

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

Créez un dossier nommé mcp-on-cloudrun pour stocker le code source à déployer :
```
  mkdir mcp-on-cloudrun
  cd mcp-on-cloudrun
```

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

Créez les fichiers supplémentaires suivants :
- server.py pour le code source du serveur MCP
- test_server.py pour tester le serveur distant
- Un fichier Dockerfile pour le déploiement sur Cloud Run
```
touch server.py test_server.py Dockerfile
```
La structure de votre répertoire de projet doit être la 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.

Exécutez la commande suivante pour ajouter FastMCP en tant que dépendance dans le fichier pyproject.toml :
```
uv add fastmcp==2.13.1 --no-sync
```

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

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 une application sur Cloud Run

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

Image de conteneur

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

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

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

Déployez l'image de conteneur du serveur MCP sur 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'indicateur --no-allow-unauthenticated, tout client MCP qui se connecte à votre serveur MCP distant doit s'authentifier.

Attribuez le rôle Demandeur Cloud Run (roles/run.invoker) au compte de service. Cette liaison de stratégie Identity and Access Management garantit qu'un mécanisme de sécurité renforcé est utilisé pour authentifier votre client MCP local.
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 testez le serveur MCP distant et vous y connectez à 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'ajout et de soustraction, procédez comme suit :

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

Créez un fichier de test nommé 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())

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

Effectuer un nettoyage

Pour éviter que des frais supplémentaires ne soient facturés sur votre Google Cloud compte, supprimez toutes les ressources que vous avez déployées avec ce tutoriel.

Supprimer le projet

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous souhaitez le conserver sans les modifications que vous avez ajoutées dans ce tutoriel, supprimez les ressources que vous avez créées pour ce tutoriel.

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

Attention : La suppression d'un projet aura les effets suivants :

Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Dans la Google Cloud console, accédez à la page Gérer les ressources.
Accéder à la page "Gérer les ressources"
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez Arrêter pour supprimer le projet.

Supprimer les ressources du tutoriel

Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel. Les services Cloud Run n'entraînent pas de coûts tant qu'ils ne reçoivent pas de requêtes.

Pour supprimer votre service Cloud Run, exécutez la commande suivante :
```
gcloud run services delete SERVICE-NAME
```
Remplacez SERVICE-NAME par le nom du service.

Vous pouvez également supprimer des services Cloud Run à partir de la Google Cloud console.
Supprimez la configuration régionale gcloud par défaut que vous avez ajoutée lors de la configuration du tutoriel :
```
 gcloud config unset run/region
```
Supprimez la configuration du projet :
```
 gcloud config unset project
```

Créer et déployer un serveur MCP distant sur Cloud Run Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Objectifs

Coûts

Avant de commencer

Découvrez comment attribuer les rôles

Console

gcloud

Préparer votre projet Python

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

Déployer une application sur Cloud Run

Image de conteneur

Source

Authentifier le client MCP

Tester le serveur MCP distant

Effectuer un nettoyage

Supprimer le projet

Supprimer les ressources du tutoriel

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