Mise en place du projet MCP — Claude sur Google Cloud (Vertex AI / Agent Platform)

SDK Python v2. Cette section est écrite pour la version 2 du SDK mcp (2.3.0, la plus récente au 5 novembre 2026) : MCPServer remplace FastMCP, les champs des objets du protocole passent en snake_case (input_schema, is_error, mime_type…) et les URI de ressources sont de simples chaînes. Le projet de démarrage du cours officiel (cli_project.zip, dans les téléchargements de la leçon « Project setup » de Claude Academy) installe, lui, la version 1 ; si vous partez de ce projet, la leçon « Passer au SDK v2 et à la spécification 2026-07-28 » du cours Introduction au MCP détaille la migration.

Avant de construire notre serveur et notre client MCP, il faut préparer l’environnement de projet. Cette section utilise Python avec le SDK MCP officiel, et uv comme gestionnaire de paquets. Comptez quelques minutes : l’installation est courte, et toute la suite de la section s’appuiera sur ce socle. À la fin de cette leçon, vous aurez un projet vide mais prêt, avec ses quatre fichiers et ses deux dépendances.

Prérequis

Trois choses sont nécessaires : Python 3.10 ou supérieur (c’est l’exigence du SDK mcp 2.3.0 sur PyPI), uv installé sur votre machine (guide d’installation), et Node 22.19 ou supérieur pour l’inspecteur de la leçon 53, qui est un outil Node lancé par npx. Si vous avez l’habitude de pip et venv, uv joue le même rôle en réunissant création d’environnement, résolution de dépendances et exécution de scripts dans un seul outil.

Structure du projet

Le projet que nous allons construire est une interface CLI (ligne de commande) qui permet à Claude d’interagir avec un système de gestion de documents via MCP. Quatre fichiers suffisent, et chacun correspond à une brique du protocole vue dans la partie précédente.

mon-projet-mcp/
├── mcp_server.py      ← Le serveur MCP (outils, ressources, prompts)
├── mcp_client.py      ← Le client MCP
├── main.py            ← L'interface CLI principale
├── pyproject.toml     ← Dépendances
└── README.md

D'après la leçon « Project setup » (Claude Academy, Claude on Google Cloud).

Retenez cette répartition, elle vous servira de repère jusqu’à la fin de la section : mcp_server.py accueillera successivement les outils, les ressources puis les prompts, mcp_client.py recevra les méthodes qui les consomment, et main.py reste la couche visible par l’utilisateur, celle qui affiche l’invite et parle à Claude.

Installation des dépendances

Avec uv, la création de l’environnement et l’installation des dépendances tiennent en quelques commandes :

# Créer un nouveau projet
uv init mon-projet-mcp
cd mon-projet-mcp

# Ajouter les dépendances
uv add "mcp[cli]>=2,<3" "anthropic[vertex]"

Deux paquets suffisent : mcp, en version 2, apporte le SDK du protocole, côté serveur comme côté client ; son extra cli installe la commande mcp (sous-commandes version, dev, run, install), dont mcp dev lance l’inspecteur ; sans cet extra, la commande répond « typer is required ». Et anthropic[vertex] fournit le client AnthropicVertex, qui permettra à main.py d’envoyer les conversations à Claude sur Vertex, avec les identifiants Google Cloud de la leçon 2 : aucune clé d’API n’est nécessaire.

Fichier pyproject.toml

La commande uv add met à jour votre pyproject.toml, qui contiendra les dépendances suivantes :

[project]
name = "mon-projet-mcp"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
    "mcp[cli]>=2,<3",
    "anthropic[vertex]>=2.5.0",
]

La ligne requires-python n’est pas décorative : le SDK MCP s’appuie sur des fonctionnalités de typage et d’asynchrone qui exigent Python 3.10 au minimum. Si vous obtenez une erreur de résolution à cette étape, vérifiez d’abord la version de Python utilisée par votre environnement.

Activer l’environnement

# Activer l'environnement virtuel
source .venv/bin/activate  # Linux/macOS
# ou
.venv\Scripts\activate     # Windows

Cette activation devient importante dès la leçon sur l’inspecteur : la commande mcp dev doit trouver le SDK dans l’environnement courant, faute de quoi elle échouera sans que la cause soit évidente. En cas de doute, réactivez l’environnement avant de lancer une commande.

Brancher Claude sur Vertex

Les leçons suivantes s’appuient sur le projet de démarrage du cours officiel, qui fournit l’interface en ligne de commande de main.py. Ce projet a été écrit pour l’API Claude et pour une ancienne version du SDK. Sur Vertex, avec le SDK actuel, trois retouches suffisent.

Dans .env, remplacez ANTHROPIC_API_KEY par l’identifiant de votre projet et la région : le client AnthropicVertex lit seul ces deux variables. Choisissez aussi un modèle actuel ; le claude-haiku-4-5 du projet d’origine s’écrirait claude-haiku-4-5@20251001 sur Vertex (leçon 3).

CLAUDE_MODEL="claude-sonnet-5-5"
ANTHROPIC_VERTEX_PROJECT_ID="votre-projet"
CLOUD_ML_REGION="global"
USE_UV=1

Dans core/claude.py, créez le client Vertex, et retirez temperature des paramètres que chat envoie : le SDK 2.x ne l’accepte plus (leçon 6). L’option thinking du projet envoie budget_tokens, que les modèles actuels refusent : laissez-la désactivée, ou passez à la réflexion adaptative (leçon 43).

from anthropic import AnthropicVertex

class Claude:
    def __init__(self, model: str):
        self.client = AnthropicVertex()   # lit ANTHROPIC_VERTEX_PROJECT_ID et CLOUD_ML_REGION
        self.model = model

Dans main.py, supprimez la vérification de ANTHROPIC_API_KEY, qui n’existe plus.

Données du projet

Notre serveur MCP gérera des documents en mémoire. Pour cet exemple, nous utilisons un dictionnaire Python simple :

docs = {
    "deposition.md": "Ce document couvre le témoignage d'Angela Smith.",
    "rapport.pdf": "Ce rapport détaille l'état d'une tour de condensation.",
    "finances.docx": "Ces finances décrivent le budget et les dépenses du projet.",
    "perspectives.pdf": "Ce document présente les performances futures projetées.",
    "plan.md": "Ce plan décrit les étapes de mise en œuvre du projet.",
    "spec.txt": "Ces spécifications définissent les exigences techniques."
}

Ce choix est délibéré. Une clé de dictionnaire fait office d’identifiant de document, la valeur fait office de contenu, et l’ensemble tient dans une variable que vous pouvez inspecter d’un coup d’œil. Rien ne vous distraira du protocole lui-même. Dans une application réelle, ces documents proviendraient d’une base de données, d’un système de fichiers ou d’une API externe, mais le code MCP qui les expose, lui, ne changerait presque pas.

À vous de jouer

Créez le projet avec les commandes ci-dessus, puis vérifiez l’installation : uv run mcp version doit afficher une version 2.x, et uv run python -c "from mcp.server.mcpserver import MCPServer" ne doit rien afficher.
Créez les quatre fichiers vides et collez le dictionnaire docs dans mcp_server.py.
Vérifiez node --version : si vous êtes sous 22.19, mettez Node à jour maintenant plutôt qu’à la leçon 53.

Sources officielles : Defining tools with MCP (Claude Academy, projet de démarrage) · Paquet mcp sur PyPI · Installation (SDK Python) · uv · MCP Inspector (prérequis Node)

Points clés à retenir

Python 3.10+, uv et Node 22.19+ ; deux dépendances : mcp[cli]>=2,<3 et anthropic[vertex].
Le projet de démarrage passe sur Vertex en trois retouches : .env, client AnthropicVertex() sans temperature, plus de vérification de clé.
Quatre fichiers : mcp_server.py (outils, ressources, prompts), mcp_client.py (le client), main.py (la CLI), pyproject.toml.
L’extra cli fournit mcp dev, la commande qui lancera l’inspecteur ; sans lui, mcp répond « typer is required ».
Les documents vivent dans un dictionnaire en mémoire : rien ne vous distrait du protocole.

L’environnement est prêt. Nous allons maintenant définir les outils dans le serveur MCP, les tester avec l’inspecteur, implémenter le client, puis ajouter des ressources et des prompts. Chaque leçon reprend le fichier là où la précédente l’a laissé, alors gardez ce projet ouvert.