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

Objectifs

Au cours de ce tutoriel, vous allez :

1. Préparez votre projet Python avec le gestionnaire de paquets uv.
2. Créez un serveur MCP pour les opérations mathématiques.
3. Déployer sur Cloud Run
4. Authentifiez le client MCP.
5. Testez le serveur MCP distant.

Coûts

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

• Artifact Registry
• Cloud Build
• Cloud Run

Pour obtenir 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 compte Google Cloud . 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Activez les API Artifact Registry, Cloud Run Admin et Cloud Build, si ce n'est pas déjà fait.

   Rôles requis pour activer les API

   Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

   Activer les API

2. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
3. 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.
4. 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

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 utilisée 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 tous les rôles supplémentaires.
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 accordez le rôle.
• ROLE : rôle que vous ajoutez au compte du déployeur.

5. 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.

6. 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.

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

     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 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 se présenter comme suit :

   ├── 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.13.1 --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.14-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 :

Remarque : Seuls les services Cloud Run peuvent être exposés en tant que serveurs MCP. Les jobs Cloud Run ne peuvent pas faire office de serveurs MCP.

Image de 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 sur Cloud Run :

   gcloud run deploy mcp-server \
       --image us-central1-docker.pkg.dev/PROJECT_ID/remote-mcp-servers/mcp-server:latest \
       --functional-type=mcp-server \
       --region=us-central1 \
       --no-allow-unauthenticated
   

Source

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

Déployez à partir de la source en exécutant la commande suivante :

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

Vérifier l'enregistrement dans Agent Registry

Lorsque vous déployez un service avec --functional-type=mcp-server, il est automatiquement enregistré dans le registre d'agents en tant qu'outil.

Pour vérifier votre inscription, accédez à l'onglet Serveurs MCP dans la console Google Cloud.

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.

1. Attribuez le rôle Demandeur Cloud Run (roles/run.invoker) à l'identité de votre agent. Pour obtenir des instructions, consultez S'authentifier auprès des serveurs MCP sur Cloud Run.
2. Utilisez Identity-Aware Proxy pour protéger vos serveurs MCP et activer OAuth. Pour obtenir des instructions, consultez Authentifier les serveurs MCP.

3. 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 et vous connectez 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'ajout 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.content[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.content[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
   

Opération réussie : vous avez déployé un serveur MCP distant sur Cloud Run et l'avez testé à l'aide du client FastMCP.

Effectuer un nettoyage

Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Google Cloud , 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 devez le conserver sans les modifications apportées lors du présent tutoriel, supprimez les ressources 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.

1. Dans la console Google Cloud , accédez à la page Gérer les ressources.

   Accéder à la page "Gérer les ressources"

2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Supprimer les ressources du tutoriel

1. Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel. Les services Cloud Run n'entraînent pas de frais 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 consoleGoogle Cloud .

2. Supprimez la configuration régionale par défaut gcloud que vous avez ajoutée lors de la configuration du tutoriel :

    gcloud config unset run/region
   

3. Supprimez la configuration du projet :

    gcloud config unset project
   

Étapes suivantes

• Découvrez comment déployer des applications d'IA sur Cloud Run.

• En savoir plus sur l'hébergement de serveurs MCP sur Cloud Run

• Découvrez comment utiliser un serveur MCP pour déployer du code sur Cloud Run.