Comment créer votre premier serveur MCP?

Le Model Context Protocol (MCP) est une norme ouverte qui permet à un assistant d’IA d’utiliser des données et des actions externes au moyen de petits programmes appelés serveurs. Le côté assistant, comme Claude Desktop, est le client. Un serveur peut offrir trois types d’éléments : des outils (tools, des actions que le modèle peut demander d’exécuter), des ressources (resources, des données qu’il peut lire) et des prompts (des gabarits réutilisables). La plupart des gens commencent par un outil, parce que c’est la façon la plus simple de donner une nouvelle capacité à un assistant.

Il ne faut pas beaucoup de code. Le SDK Python officiel comprend FastMCP, un utilitaire qui transforme une fonction Python ordinaire en outil MCP. Le nom de la fonction devient le nom de l’outil, ses annotations de type décrivent les entrées, et sa docstring (le texte entre triples guillemets) devient la description que le modèle lit pour décider s’il l’utilise.

Ce qu’il vous faut

• Une version récente de Python et uv, un gestionnaire de projets Python rapide que recommande le README du SDK. (Un simple pip install mcp fonctionne aussi.)
• Un éditeur de texte et un terminal.
• Node.js, seulement si vous voulez lancer l’Inspector seul avec npx.
• Claude Desktop, si vous voulez connecter le serveur terminé à un assistant.

Étape par étape : un outil « jours restants »

Notre serveur répondra à une question que les modèles de langage ratent souvent : combien de jours reste-t-il avant une date donnée. Un modèle ne peut pas connaître de façon fiable la date du jour ni compter les jours du calendrier; une fonction de trois lignes, oui.

1. Créez le projet et ajoutez le SDK.

uv init days-server
cd days-server
uv add "mcp[cli]"

La partie [cli] installe l’outil en ligne de commande mcp dont vous vous servirez pour les tests.

2. Écrivez server.py.

# server.py
from datetime import date
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Days Until")

@mcp.tool()
def days_until(target: str) -> str:
    """Compte les jours entre aujourd'hui et une date donnée au format AAAA-MM-JJ.
    Renvoie un nombre négatif si la date est passée."""
    try:
        when = date.fromisoformat(target)
    except ValueError:
        return "Donne la date au format AAAA-MM-JJ, par exemple 2025-12-25."
    delta = (when - date.today()).days
    return f"{delta} jours du {date.today().isoformat()} au {target}."

if __name__ == "__main__":
    mcp.run()

Trois détails comptent. La docstring est écrite pour le modèle; elle dit donc exactement quel est le format d’entrée. Une mauvaise entrée renvoie un message utile au lieu de faire planter le programme, ce qui permet au modèle de se corriger. Et la fonction fait une seule chose, ce qui la rend facile à tester.

3. Testez-le avec l’Inspector (section suivante).

4. Connectez-le à Claude Desktop.

uv run mcp install server.py

Cette commande inscrit le serveur dans Claude Desktop, qui garde sa liste de serveurs MCP dans un fichier appelé claude_desktop_config.json. Quittez complètement Claude Desktop et rouvrez-le : il se connecte aux serveurs au démarrage. Demandez ensuite « Combien de jours reste-t-il avant le 25 décembre? » et Claude devrait proposer d’appeler days_until. Claude Desktop vous demande de confirmer avant les opérations sensibles, et le serveur ne tourne que sur votre propre ordinateur.

Si quelque chose ne va pas

• L’outil n’apparaît pas dans Claude Desktop. Assurez-vous d’avoir complètement quitté l’application, et pas seulement fermé la fenêtre. Ses journaux (sur Mac, dans ~/Library/Logs/Claude/, dans les fichiers qui commencent par mcp) indiquent si le serveur a démarré.
• Le serveur démarre, mais l’outil échoue. Exécutez-le dans l’Inspector et lisez-y le message d’erreur; c’est beaucoup plus rapide que de tester par une conversation.
• Le modèle n’appelle jamais votre outil. Améliorez la docstring. Dites clairement ce que fait l’outil et quand l’utiliser.

Comment le tester avant de le connecter à un assistant?

Utilisez le MCP Inspector, l’outil officiel pour vérifier et déboguer un serveur pendant que vous le construisez. Il joue le rôle d’un client, se connecte à votre serveur et vous montre exactement ce qu’un assistant verrait : la liste des outils, leurs descriptions et leurs champs d’entrée, et les résultats bruts. Comme aucun modèle de langage n’intervient, vous testez votre code seul, sans vous demander si le modèle a mal compris.

Le SDK lance l’Inspector pour vous :

uv run mcp dev server.py

La commande lance votre serveur avec l’Inspector, qui fait tourner une petite page Web dans votre navigateur (par défaut sur le port 5173) et un mandataire (proxy) local qui communique avec votre serveur (le port 3000 par défaut). Ouvrez l’adresse qu’il affiche, connectez-vous et affichez la liste des outils. Vous devriez voir days_until avec la docstring que vous avez écrite. Exécutez-le avec une date valide, puis avec une valeur erronée comme 25/12/2025, et vérifiez que vous obtenez votre message d’erreur convivial plutôt qu’un plantage.

Si votre serveur est écrit dans un autre langage, ou si vous voulez lancer l’Inspector seul, démarrez-le avec npx @modelcontextprotocol/inspector suivi de la commande qui lance votre serveur; vous pouvez transmettre des variables d’environnement avec -e KEY=value. Une mise en garde du README de l’Inspector : son mandataire peut lancer des programmes sur votre machine; gardez-le donc sur votre propre ordinateur et ne l’exposez jamais à un réseau non fiable.

Une bonne habitude consiste à garder une courte liste d’entrées de test (un cas normal, un cas limite comme la date du jour, et une mauvaise entrée) et à les exécuter dans l’Inspector chaque fois que vous modifiez le serveur. Ce n’est que lorsque les trois se comportent comme prévu qu’il vaut la peine de connecter le serveur à un assistant.