Aller au contenu

Cercle IA .tech · Technique

Cercle IA TechMCP

Guide

Créer un client MCP en Python avec le SDK officiel

Écrire son propre client MCP en Python : se connecter à un serveur stdio, lister les outils, les appeler et gérer les erreurs, tutoriel officiel.

Mis à jour le

Écrire un client MCP (Model Context Protocol), c'est écrire la moitié du protocole qu'un hôte comme Claude Desktop fait pour vous : lancer un serveur, lister ses outils, les proposer à un modèle et relayer les appels. Le tutoriel officiel de modelcontextprotocol.io, lu le 16/11/2026, construit un petit assistant en ligne de commande qui fait cela. Voici sa structure et ses pièges, avec des extraits commentés et un exemple de connexion adapté.

Pour donner un objectif au client, choisissez une opération dans la documentation MCP d’ALMA. Préparez les droits et les données d’essai, puis vérifiez la découverte des outils avant leur appel.

Ce qu'il faut avant de commencer

Pour la version Python, le tutoriel demande : Mac ou Windows, Python récent, uv, le SDK Python MCP en version 2.0.0 ou supérieure et une clé d'API Anthropic, rangée dans un fichier .env qu'on ajoute à .gitignore. Il suppose aussi que vous avez suivi le tutoriel du serveur ; si ce n'est pas fait, voir créer un serveur MCP en Python. Le tutoriel existe aussi pour TypeScript, Java, Kotlin, C#, Ruby et Rust.

Préparez un projet séparé ; la contrainte de version ci-dessous reprend le minimum demandé :

uv init mcp-client
cd mcp-client
uv venv
source .venv/bin/activate
uv add "mcp>=2.0.0" anthropic python-dotenv
touch client.py

Décrire le serveur, puis se connecter

L'objet central est Client : « le seul objet par lequel votre programme parle au serveur ». Lister les outils, en appeler un, lire une ressource sont des méthodes de cet objet. Le serveur à lancer se décrit avec StdioServerParameters, qui est de la configuration, pas une connexion. Selon l'extension du script (.py ou .js), le tutoriel choisit la commande python ou node.

Avant d'ajouter le modèle, vérifiez la découverte seule. Cette adaptation complète utilise l'interpréteur Python du client pour lancer le serveur ; ses dépendances doivent donc être disponibles dans cet environnement :

import asyncio
import sys
from pathlib import Path
from mcp import Client, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    if len(sys.argv) != 2:
        raise SystemExit("Usage : uv run client.py /chemin/serveur.py")
    script = Path(sys.argv[1]).resolve(strict=True)
    params = StdioServerParameters(command=sys.executable, args=[str(script)])
    async with Client(stdio_client(params)) as client:
        listing = await client.list_tools()
        print([tool.name for tool in listing.tools])

if __name__ == "__main__":
    asyncio.run(main())

stdio_client() crée le transport (l'autre transport, Streamable HTTP, sert aux serveurs distants) et Client l'ouvre dans le bloc async with. Entrer dans le bloc lance le serveur et négocie la version du protocole ; en sortir déconnecte et arrête le sous-processus.

La boucle d'appel d'outils

Pour chaque question de l'utilisateur, la fonction process_query suit ces étapes, d'après le tutoriel :

  1. envoyer la question et la description des outils au modèle ;
  2. relever tous les blocs tool_use de la réponse ;
  3. s'il n'y en a aucun, rendre le texte ; sinon appeler chaque outil avec client.call_tool ;
  4. construire un tool_result par appel et renvoyer le tout dans un seul message utilisateur ;
  5. recommencer jusqu'à une réponse sans appel d'outil, ou jusqu'à MAX_TOOL_TURNS (10).

La conversion des outils MCP vers le format attendu par l'API du modèle se résume à trois champs :

available_tools = [{
    "name": tool.name,
    "description": tool.description,
    "input_schema": tool.input_schema
} for tool in tool_list.tools]

Et l'appel lui-même :

result = await client.call_tool(tool_use.name, tool_use.input)

Chaque résultat Claude doit porter le tool_use_id de l'appel correspondant. Le tutoriel conserve aussi la réponse complète de l'assistant avant d'ajouter les résultats : ne perdez pas les blocs nécessaires à la conversation. Son adaptation ne récupère que les contenus MCP textuels ; pour des images ou des résultats structurés, prévoyez une conversion explicite.

Le premier exemple de cette page n'appelle aucun modèle et n'utilise donc pas de clé Anthropic. La boucle complète, elle, fait des appels API facturables. Le plafond de dix tours limite une boucle, pas le coût total ni la durée d'un outil bloqué. Ajoutez délais et permissions avant de brancher un outil d'écriture.

Les erreurs : le point à ne pas rater

Le tutoriel transmet result.is_error dans le bloc tool_result envoyé au modèle. Cette erreur de traitement est distincte d'une exception de transport ou d'une erreur JSON-RPC, que le programme doit intercepter. Le modèle lit l'échec et peut corriger ses paramètres. C'est la même logique que dans la spécification des outils, détaillée dans outils, ressources et prompts. Gardez aussi le plafond de tours : sans lui, une requête qui ne converge jamais tournerait sans fin.

Dépannage relevé dans le tutoriel

  • Chemin du serveur : utilisez un chemin absolu si le relatif échoue ; sous Windows, barres obliques ou barres inverses doublées.
  • Le tutoriel évoque une première réponse pouvant prendre 30 secondes. C'est un repère de démonstration, pas un délai maximal garanti : mesurez séparément démarrage, appel au modèle et outil.
  • FileNotFoundError : vérifier le chemin du script. Connection refused signale un échec de connexion réseau ; pour un lancement stdio, commencez par examiner la sortie d'erreur du processus. Délai dépassé : le tutoriel suggère d'augmenter read_timeout_seconds sur le Client.
  • Les noms d'outils doivent suivre le format de la spécification.

Et pour un modèle de l'API Claude ?

Si vous voulez seulement que l'API de Claude appelle un serveur distant sans écrire de client, regardez le connecteur MCP de l'API Claude : c'est une autre voie, qui évite la boucle ci-dessus.

Questions fréquentes

Quelle version du SDK Python faut-il pour le tutoriel client ?

Le tutoriel officiel demande le SDK Python MCP en version 2.0.0 ou supérieure, avec uv et une clé d'API Anthropic, relevé le 16/11/2026.

Que se passe-t-il si un outil plante côté serveur ?

Une erreur métier renvoyée comme résultat porte is_error dans le SDK Python. Une panne de transport ou une erreur de protocole peut lever une exception : le client doit aussi la traiter.

Pourquoi limiter le nombre de tours d'outils ?

Le tutoriel fixe MAX_TOOL_TURNS à 10 pour qu'une requête qui ne se termine jamais rende quand même la main.

Références du carnet

Pages consultées pour écrire cet article :

  1. Site d’ALMA : référence MCP
  2. https://modelcontextprotocol.io/docs/2026-07-28/develop/build-client.md

À lire aussi