Tutoriel : construire son premier serveur MCP en Python

Guide pas à pas pour créer son propre serveur MCP en Python : exposer des outils et des ressources à un LLM, tester avec l'inspecteur, puis brancher le serveur à un hôte comme Claude Desktop.

Dans le premier article sur les serveurs Model Context Protocol nous avons posé les bases sur : son architecture hôte / client / serveur et ses trois primitives (outils, ressources, prompts). Place à la pratique. Dans ce tutoriel, nous construisons de bout en bout un petit serveur MCP en Python qui expose un outil et une ressource, puis nous le branchons à un hôte pour voir un modèle s’en servir.

I. Prérequis et installation  

Il vous faut Python 3.10 ou plus. Le SDK officiel fournit aussi un utilitaire en ligne de commande très pratique pour tester et installer un serveur.

# Création d'un environnement isolé
python -m venv .venv
source .venv/bin/activate      # sous Windows : .venv\Scripts\activate

# Installation du SDK MCP avec ses outils CLI
pip install "mcp[cli]"

Le paquet mcp[cli] ajoute la commande mcp, que nous utiliserons pour lancer l’inspecteur et installer le serveur dans un hôte.

II. Le squelette d’un serveur avec FastMCP  

Le SDK propose FastMCP, une API déclarative où l’on décore de simples fonctions Python. Créons un fichier server.py :

from mcp.server.fastmcp import FastMCP

# Le nom identifie le serveur auprès de l'hôte
mcp = FastMCP("Gestionnaire de tâches")

if __name__ == "__main__":
    # Dans sa configuration la plus courante, FastMCP utilise stdio comme transport par défaut. (entrée/sortie standard)
    mcp.run()

C’est tout ce qu’il faut pour un serveur valide… mais vide. Il ne fait encore rien d’utile : ajoutons-lui des capacités.

III. Exposer un outil (tool)  

Un outil est une fonction que le modèle peut appeler pour agir. On l’expose avec le décorateur @mcp.tool(). Deux détails comptent énormément :

• Les annotations de type (titre: str) : elles génèrent le schéma que le modèle lit pour savoir comment appeler l’outil.
• La docstring : elle décrit l’outil au modèle. Soignez-la comme un mode d’emploi.

# Un stockage en mémoire pour l'exemple (perdu au redémarrage)
taches: list[str] = []

@mcp.tool()
def ajouter_tache(titre: str) -> str:
    """Ajoute une tâche à la liste et renvoie une confirmation.

    Args:
        titre: L'intitulé de la tâche à créer.
    """
    taches.append(titre)
    return f"Tâche ajoutée : « {titre} » (total : {len(taches)})"

Le modèle décidera de lui-même quand invoquer ajouter_tache, en s’appuyant sur le nom, la docstring et les types. (Si l’hôte l’autorise et si la requête utilisateur s’y prête.)

IV. Exposer une ressource (resource)  

Une ressource fournit des données en lecture seule pour enrichir le contexte. Contrairement à un outil, elle ne provoque pas d’effet de bord : elle ne fait que renvoyer de l’information, identifiée par une URI.

@mcp.resource("taches://liste")
def lister_taches() -> str:
    """Renvoie la liste des tâches enregistrées, une par ligne."""
    if not taches:
        return "Aucune tâche pour le moment."
    return "\n".join(f"- {t}" for t in taches)

Une URI peut aussi être paramétrée. Les accolades capturent une variable passée à la fonction :

@mcp.resource("taches://{index}")
def detail_tache(index: int) -> str:
    """Renvoie le détail d'une tâche à partir de son numéro (commençant à 1)."""
    if 1 <= index <= len(taches):
        return taches[index - 1]
    return f"Aucune tâche au numéro {index}."

Règle simple à garder en tête : un outil agit, une ressource informe.

V. Tester son serveur avec l’inspecteur MCP  

Avant de brancher quoi que ce soit à un modèle, vérifions le serveur de façon isolée. L’inspecteur MCP est une interface web qui se connecte à votre serveur et permet de lister puis d’exécuter ses outils et ressources à la main.

mcp dev server.py

La commande démarre le serveur et ouvre l’inspecteur dans le navigateur. Vous pouvez alors :

• voir la liste des outils (ajouter_tache) et ressources (taches://liste) ;
• appeler un outil avec des paramètres et observer la réponse ;
• lire une ressource et vérifier son contenu.

C’est l’équivalent d’un test manuel : un excellent réflexe avant toute intégration.

VI. Brancher le serveur à un hôte (Claude Desktop)  

Une fois le serveur validé, connectons-le à un véritable hôte. La façon la plus rapide :

# Selon votre version du SDK
mcp install server.py
# ou configuration manuelle

Le SDK fournit des commandes pour faciliter l’intégration avec certains hôtes. En arrière plan, elle ajoute une entrée dans le fichier claude_desktop_config.json. Mais selon votre version, vous pourrez devoir ajouter manuellement l’entrée dans la configuration de Claude Desktop.

{
  "mcpServers": {
    "gestionnaire-taches": {
      "command": "python",
      "args": ["/chemin/absolu/vers/server.py"]
    }
  }
}

Après redémarrage de l’hôte, le serveur apparaît dans l’interface. Demandez alors au modèle, en langage naturel, d’« ajouter une tâche : préparer la présentation » : il choisira l’outil ajouter_tache, vous demandera votre accord, puis l’exécutera. La boucle est bouclée.

VII. Bonnes pratiques et pièges courants  

• Décrivez tout précisément. Le modèle ne voit que les noms, types et docstrings. Une description vague mène à des appels erronés.
• Validez les entrées. Ne faites jamais confiance aux paramètres : vérifiez les bornes, les formats, les valeurs nulles.
• Pensez à la sécurité. Un outil qui écrit sur le disque ou appelle une API distante doit limiter sa portée. N’exposez que le strict nécessaire.
• Gardez les outils petits et ciblés. Un outil = une action claire ; c’est plus facile à décrire, à tester et à raisonner.
• N’utilisez le stockage en mémoire que pour apprendre. En production, une base de données ou un fichier remplacera notre liste taches.

Conclusion  

En quelques dizaines de lignes, nous avons construit un serveur MCP fonctionnel : un outil pour agir, une ressource pour informer, un test via l’inspecteur, et un branchement à un hôte. Le plus remarquable est que toute la logique métier vit dans le serveur — pas dans le modèle — ce qui la rend testable, versionnable et réutilisable avec n’importe quel client compatible.

Dans le prochain article, nous quitterons le poste local pour aborder l’intégration dans un écosystème : transports distants, authentification, et bonnes pratiques de sécurité pour exposer un serveur MCP au-delà de sa propre machine.

🔗 Ressource utile  

• SDK Python officiel de MCP (GitHub)
• Documentation : créer un serveur MCP
• Inspecteur MCP
• Serveurs de référence MCP