1. Introduction
Présentation
Dans cet atelier, vous allez créer et déployer un serveur MCP (Model Context Protocol). Les serveurs MCP sont utiles pour permettre aux LLM d'accéder à des outils et services externes. Vous allez le configurer en tant que service sécurisé et prêt pour la production sur Cloud Run, accessible depuis plusieurs clients. Vous vous connecterez ensuite au serveur MCP distant depuis la CLI Gemini.
Objectifs de l'atelier
Nous allons utiliser FastMCP pour créer un serveur MCP zoo qui comporte deux outils : get_animals_by_species et get_animal_details. FastMCP fournit un moyen rapide et Pythonique de créer des serveurs et des clients MCP.
Points abordés
- Déployez le serveur MCP sur Cloud Run.
- Sécurisez le point de terminaison de votre serveur en exigeant une authentification pour toutes les requêtes. Vous vous assurez ainsi que seuls les clients et agents autorisés peuvent communiquer avec lui.
- Se connecter au point de terminaison de votre serveur MCP sécurisé depuis la CLI Gemini
2. Configuration du projet
- Si vous ne possédez pas encore de compte Google, vous devez en créer un.
- Utilisez un compte personnel au lieu d'un compte professionnel ou scolaire. Il est possible que des restrictions s'appliquent aux comptes professionnels et scolaires, ce qui vous empêche d'activer les API nécessaires pour cet atelier.
- Connectez-vous à la console Google Cloud.
- Activez la facturation dans la console Cloud.
- Cet atelier devrait vous coûter moins de 1 USD en ressources Cloud.
- Vous pouvez suivre les étapes à la fin de cet atelier pour supprimer les ressources et éviter ainsi que des frais supplémentaires ne vous soient facturés.
- Les nouveaux utilisateurs peuvent bénéficier d'un essai sans frais pour un crédit de 300$.
- Créez un projet ou choisissez d'en réutiliser un.
3. Ouvrir l'éditeur Cloud Shell
- Cliquez sur ce lien pour accéder directement à l'éditeur Cloud Shell.
- Si vous êtes invité à autoriser l'accès à un moment donné aujourd'hui, cliquez sur Autoriser pour continuer.
- Si le terminal ne s'affiche pas en bas de l'écran, ouvrez-le :
- Cliquez sur Afficher.
- Cliquez sur Terminal
.
- Dans le terminal, définissez votre projet à l'aide de la commande suivante :
- Format :
gcloud config set project [PROJECT_ID] - Exemple :
gcloud config set project lab-project-id-example - Si vous ne vous souvenez pas de l'ID de votre projet :
- Vous pouvez lister tous vos ID de projet avec la commande suivante :
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- Vous pouvez lister tous vos ID de projet avec la commande suivante :
- Format :
- Le message suivant doit s'afficher :
Updated property [core/project].
WARNINGs'affiche et que vous êtes invité àDo you want to continue (Y/n)?, cela signifie probablement que vous avez saisi l'ID de projet de manière incorrecte. Appuyez surn, puis surEnter, et réessayez d'exécuter la commandegcloud config set project.
4. Activer les API
Dans le terminal, activez les API :
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Si vous êtes invité à autoriser l'accès, cliquez sur Autoriser pour continuer.
L'exécution de cette commande peut prendre quelques minutes, mais un message semblable à celui qui suit devrait s'afficher pour vous indiquer que l'opération s'est correctement déroulée :
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
5. Préparer votre projet Python
- Créez un dossier nommé
mcp-on-cloudrunpour stocker le code source du déploiement :mkdir mcp-on-cloudrun && cd mcp-on-cloudrun - Créez un projet Python avec l'outil
uvpour générer un fichierpyproject.toml:uv init --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.13uv initcrée un fichierpyproject.tomlpour votre projet.Pour afficher le contenu du fichier, exécutez la commande suivante :cat pyproject.toml[project] name = "mcp-on-cloudrun" version = "0.1.0" description = "Example of deploying an MCP server on Cloud Run" requires-python = ">=3.13" dependencies = []
6. Créer le serveur MCP du zoo
Pour fournir un contexte utile afin d'améliorer l'utilisation des LLM avec MCP, configurez un serveur MCP Zoo avec FastMCP, un framework standard pour travailler avec le protocole MCP (Model Context Protocol). FastMCP permet de créer rapidement des serveurs et des clients MCP avec Python. Ce serveur MCP fournit des données sur les animaux d'un zoo fictif. Par souci de simplicité, nous stockons les données en mémoire. Pour un serveur MCP de production, vous souhaiterez probablement fournir des données provenant de sources telles que des bases de données ou des API.
- Exécutez la commande suivante pour ajouter FastMCP en tant que dépendance dans le fichier
pyproject.toml:uv add fastmcp==2.11.1 --no-syncuv.locksera ajouté à votre projet. - Créez et ouvrez un fichier
server.pypour le code source du serveur MCP :cloudshell edit server.pycloudshell editouvre le fichierserver.pydans l'éditeur au-dessus du terminal. - Ajoutez le code source du serveur MCP Zoo suivant dans le fichier
server.py:import asyncio import logging import os from typing import List, Dict, Any from fastmcp import FastMCP logger = logging.getLogger(__name__) logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO) mcp = FastMCP("Zoo Animal MCP Server 🦁🐧🐻") # Dictionary of animals at the zoo ZOO_ANIMALS = [ { "species": "lion", "name": "Leo", "age": 7, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Nala", "age": 6, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Simba", "age": 3, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "King", "age": 8, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "penguin", "name": "Waddles", "age": 2, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pip", "age": 4, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Skipper", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Chilly", "age": 3, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pingu", "age": 6, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Noot", "age": 1, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "elephant", "name": "Ellie", "age": 15, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Peanut", "age": 12, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Dumbo", "age": 5, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Trunkers", "age": 10, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "bear", "name": "Smokey", "age": 10, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Grizzly", "age": 8, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Barnaby", "age": 6, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Bruin", "age": 12, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "giraffe", "name": "Gerald", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Longneck", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Patches", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Stretch", "age": 6, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Speedy", "age": 2, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Dash", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Gazelle", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Swift", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "polar bear", "name": "Snowflake", "age": 7, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Blizzard", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Iceberg", "age": 9, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "walrus", "name": "Wally", "age": 10, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Tusker", "age": 12, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Moby", "age": 8, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Flippers", "age": 9, "enclosure": "The Walrus Cove", "trail": "Polar Path" } ] @mcp.tool() def get_animals_by_species(species: str) -> List[Dict[str, Any]]: """ Retrieves all animals of a specific species from the zoo. Can also be used to collect the base data for aggregate queries of animals of a specific species - like counting the number of penguins or finding the oldest lion. Args: species: The species of the animal (e.g., 'lion', 'penguin'). Returns: A list of dictionaries, where each dictionary represents an animal and contains details like name, age, enclosure, and trail. """ logger.info(f">>> 🛠️ Tool: 'get_animals_by_species' called for '{species}'") return [animal for animal in ZOO_ANIMALS if animal["species"].lower() == species.lower()] @mcp.tool() def get_animal_details(name: str) -> Dict[str, Any]: """ Retrieves the details of a specific animal by its name. Args: name: The name of the animal. Returns: A dictionary with the animal's details (species, name, age, enclosure, trail) or an empty dictionary if the animal is not found. """ logger.info(f">>> 🛠️ Tool: 'get_animal_details' called for '{name}'") for animal in ZOO_ANIMALS: if animal["name"].lower() == name.lower(): return animal return {} if __name__ == "__main__": logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}") asyncio.run( mcp.run_async( transport="http", host="0.0.0.0", port=os.getenv("PORT", 8080), ) )
Votre code est terminé ! Il est temps de déployer le serveur MCP sur Cloud Run.
7. Déployer sur Cloud Run
Déployez maintenant un serveur MCP sur Cloud Run directement à partir du code source.
- Créez et ouvrez un
Dockerfilepour le déploiement sur Cloud Run :cloudshell edit Dockerfile - Incluez le code suivant dans le fichier Dockerfile pour utiliser l'outil
uvafin d'exécuter le fichierserver.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"] - Exécutez la commande
gcloudpour déployer l'application sur Cloud Run.gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp--no-allow-unauthenticatedpour exiger une authentification. C'est important pour des raisons de sécurité. Si vous n'exigez pas d'authentification, n'importe qui peut appeler votre serveur MCP et potentiellement endommager votre système. - Confirmez la création d'un dépôt Artifact Registry. Comme il s'agit de votre premier déploiement sur Cloud Run à partir du code source, vous verrez le message suivant :
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [europe-west1] will be created. Do you want to continue (Y/n)?
Yet appuyez surEnter. Un dépôt Artifact Registry sera alors créé pour votre déploiement. Cette opération est nécessaire pour stocker le conteneur Docker du serveur MCP pour le service Cloud Run. - Au bout de quelques minutes, un message semblable à celui-ci s'affichera :
Service [zoo-mcp-server] revision [zoo-mcp-server-12345-abc] has been deployed and is serving 100 percent of traffic.
Vous avez déployé votre serveur MCP. Vous pouvez maintenant l'utiliser.
8. Ajouter le serveur MCP distant à la CLI Gemini
Maintenant que vous avez déployé un serveur MCP à distance, vous pouvez vous y connecter à l'aide de diverses applications telles que Google Code Assist ou la CLI Gemini. Dans cette section, nous allons établir une connexion à votre nouveau serveur MCP distant à l'aide de la CLI Gemini.
- Autorisez votre compte utilisateur à appeler le serveur MCP distant.
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \ --member=user:$(gcloud config get-value account) \ --role='roles/run.invoker' - Enregistrez vos identifiants Google Cloud et votre numéro de projet dans des variables d'environnement à utiliser dans le fichier de paramètres Gemini :
export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") export ID_TOKEN=$(gcloud auth print-identity-token) - Ouvrez le fichier de paramètres de la CLI Gemini.
cloudshell edit ~/.gemini/settings.json - Remplacer votre fichier de paramètres de la CLI Gemini pour ajouter le serveur MCP Cloud Run
{ "mcpServers": { "zoo-remote": { "httpUrl": "https://zoo-mcp-server-$PROJECT_NUMBER.europe-west1.run.app/mcp/", "headers": { "Authorization": "Bearer $ID_TOKEN" } } }, "selectedAuthType": "cloud-shell", "hasSeenIdeIntegrationNudge": true }
- Démarrer la CLI Gemini dans Cloud Shell
geminiEnterpour accepter certains paramètres par défaut.
- Demander à Gemini de lister les outils MCP disponibles dans son contexte
/mcp - Demander à Gemini de trouver quelque chose dans le zoo
Where can I find penguins?zoo-remoteet vous demandera si vous souhaitez autoriser l'exécution de MCP. - Utilisez la flèche vers le bas, puis appuyez sur
Enterpour sélectionner.Yes, always allow all tools from server "zoo-remote"
Le résultat doit afficher la bonne réponse et une zone indiquant que le serveur MCP a été utilisé.
Vous avez réussi ! Vous avez bien déployé un serveur MCP distant sur Cloud Run et l'avez testé à l'aide de la Gemini CLI.
Lorsque vous êtes prêt à mettre fin à votre session, saisissez /quit, puis appuyez sur Enter pour quitter l'interface de ligne de commande Gemini.
Débogage
Si vous voyez une erreur semblable à celle-ci :
🔍 Attempting OAuth discovery for 'zoo-remote'... ❌ 'zoo-remote' requires authentication but no OAuth configuration found Error connecting to MCP server 'zoo-remote': MCP server 'zoo-remote' requires authentication. Please configure OAuth or check server settings.
Il est probable que le jeton d'identité ait expiré et qu'il faille à nouveau définir ID_TOKEN.
- Saisissez
/quit, puis appuyez surEnterpour quitter Gemini CLI. - Définir votre projet dans votre terminal
gcloud config set project [PROJECT_ID] - Redémarrez à l'étape 2 ci-dessus.
9. (Facultatif) Valider les appels d'outils dans les journaux du serveur
Pour vérifier que votre serveur MCP Cloud Run a été appelé, consultez les journaux de service.
gcloud run services logs read zoo-mcp-server --region europe-west1 --limit=5
Un journal de sortie doit confirmer qu'un appel d'outil a été effectué. 🛠️
2025-08-05 19:50:31 INFO: 169.254.169.126:39444 - "POST /mcp/ HTTP/1.1" 200 OK 2025-08-05 19:50:31 [INFO]: Processing request of type CallToolRequest 2025-08-05 19:50:31 [INFO]: >>> 🛠️ Tool: 'get_animals_by_species' called for 'penguin'
10. (Facultatif) Ajouter une invite MCP au serveur
Une invite MCP peut accélérer votre workflow pour les requêtes que vous exécutez souvent en créant un raccourci pour une requête plus longue.
La CLI Gemini convertit automatiquement les requêtes MCP en commandes slash personnalisées. Vous pouvez ainsi appeler une requête MCP en saisissant /prompt_name, où prompt_name correspond au nom de votre requête MCP.
Créez un prompt MCP pour trouver rapidement un animal dans le zoo en saisissant /find animal dans l'interface de ligne de commande Gemini.
- Ajoutez ce code à votre fichier
server.pyau-dessus de la protection principale (if __name__ == "__main__":).@mcp.prompt() def find(animal: str) -> str: """ Find which exhibit and trail a specific animal might be located. """ return ( f"Please find the exhibit and trail information for {animal} in the zoo. " f"Respond with '[animal] can be found in the [exhibit] on the [trail].'" f"Example: Penguins can be found in The Arctic Exhibit on the Polar Path." ) - Redéployer votre application sur Cloud Run
gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp - Actualiser votre ID_TOKEN pour votre serveur MCP distant
export ID_TOKEN=$(gcloud auth print-identity-token) - Une fois la nouvelle version de votre application déployée, démarrez la CLI Gemini.
gemini - Dans l'invite, utilisez la nouvelle commande personnalisée que vous avez créée :
/find --animal="lions"
Vous devriez voir que Gemini CLI appelle l'outil get_animals_by_species et met en forme la réponse comme indiqué dans l'invite MCP.
╭───────────────────────────╮
│ > /find --animal="lion" │
╰───────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✔ get_animals_by_species (zoo-remote MCP Server) get_animals_by_species (zoo-remote MCP Server) │
│ │
│ [{"species":"lion","name":"Leo","age":7,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"Nala","age":6,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"Simba","age":3,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"King","age":8,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah Heights"}] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ Lions can be found in The Big Cat Plains on the Savannah Heights.
Objectifs ambitieux pour vous tester
Pour un défi supplémentaire, essayez de suivre les mêmes étapes pour créer une requête permettant d'obtenir des anecdotes sur des espèces animales spécifiques du zoo.
Pour aller encore plus loin et tester ce que vous avez appris, trouvez une idée d'outil que vous utiliseriez fréquemment et déployez un deuxième serveur MCP à distance. Ajoutez-le ensuite à vos paramètres Gemini CLI pour voir s'il fonctionne.
11. Conclusion
Félicitations ! Vous avez bien déployé un serveur MCP distant sécurisé et vous y êtes connecté.
Passer à l'atelier suivant
Cet atelier est le premier d'une série en trois parties. Dans le deuxième atelier, vous utiliserez le serveur MCP que vous avez créé avec un agent ADK.
Utiliser un serveur MCP sur Cloud Run avec un agent ADK
(Facultatif) Effectuer un nettoyage
Si vous ne passez pas à l'atelier suivant et que vous souhaitez nettoyer ce que vous avez créé, vous pouvez supprimer votre projet Cloud pour éviter des frais supplémentaires.
Bien que Cloud Run ne facture pas lorsque le service n'est pas utilisé, il se peut que des frais vous soient facturés pour le stockage de l'image de conteneur dans Artifact Registry. La suppression de votre projet Cloud arrête la facturation de toutes les ressources utilisées dans ce projet.
Si vous le souhaitez, supprimez le projet :
gcloud projects delete $GOOGLE_CLOUD_PROJECT
Vous pouvez également supprimer les ressources inutiles de votre disque Cloud Shell. Vous pouvez :
- Supprimez le répertoire du projet de l'atelier de programmation :
rm -rf ~/mcp-on-cloudrun - Avertissement ! Cette prochaine action est irréversible. Si vous souhaitez supprimer tous les éléments de votre Cloud Shell pour libérer de l'espace, vous pouvez supprimer l'intégralité de votre répertoire personnel. Veillez à ce que tout ce que vous souhaitez conserver soit enregistré ailleurs.
sudo rm -rf $HOME