Guide

FastMCP : le chemin le plus rapide vers un serveur MCP en Python

FastMCP transforme une fonction Python en outil pour un modèle. Deux versions, composition, proxy, authentification, tests, contexte et alternatives.

L'équipe CodeWorlds14 min de lecture ·

Pratique Vibe coding avec Claude Code dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article11

FastMCP transforme une fonction Python ordinaire en outil accessible à un modèle. Le schéma des arguments vient des annotations de type, la description de la docstring, et la couche de transport, la validation et la conformité au protocole sont dans la bibliothèque. Tu écris la logique, le reste se branche tout seul.

D'où viennent les deux versions et pourquoi c'est important

L'histoire du projet explique la confusion que tu rencontreras en cherchant de la documentation.

La première version de FastMCP s'est révélée assez pratique pour être intégrée au kit de développement Python officiel dès 2024. Le code qui utilise mcp.server.fastmcp est cette version, mais le chemin d'import est resté sur la branche 1.x, qui ne reçoit plus que des correctifs de sécurité depuis fin juillet 2026. Dans la version deux du kit officiel, la classe s'appelle MCPServer et se trouve dans mcp.server.mcpserver, donc les anciens exemples trouvés en ligne cessent de fonctionner après une mise à jour.

Le projet a toutefois continué à évoluer comme paquet séparé, et celui-ci porte aujourd'hui des fonctionnalités que la version intégrée n'a pas : la composition de serveurs, la génération d'un serveur à partir d'une description OpenAPI et le proxy d'appels vers d'autres serveurs. Un client et l'authentification figuraient autrefois sur cette liste, mais la version deux du kit officiel, publiée le 28 juillet 2026, a ajouté les deux, donc ils ne décident plus du choix.

Un repère pratique pour choisir : pour un serveur simple avec quelques outils, la version du kit officiel suffit. Pour tout ce qui va en production ou sert de nombreux clients, prends le paquet séparé, car sinon tu écrirais toi-même les fonctionnalités manquantes.

Il est aussi utile de savoir que le nom circule dans deux écosystèmes, et qu'en TypeScript il désigne plus d'une chose à la fois. La même équipe publie sa propre bibliothèque @prefecthq/fastmcp-ts, et séparément le registre npm contient un paquet fastmcp développé par d'autres personnes. Ce ne sont ni le même outil ni des interfaces compatibles, donc en cherchant de la documentation, vérifie de quel langage et de quel paquet il s'agit, car les exemples de code de l'un ne se transposeront pas à l'autre.

La version stable de fin juillet 2026 porte le numéro 3.4.5, et un jour plus tard la première bêta de la version quatre est apparue. Sa direction de développement répond directement à un changement du protocole lui-même, abordé plus bas.

Ton premier serveur

Bash
pip install fastmcp
Python
from fastmcp import FastMCP

mcp = FastMCP("orders")

@mcp.tool
def order_status(number: str) -> dict:
    """Returns order status by number in ORD-12345 format.

    Call this when the user asks about a specific order and supplied its number.
    """
    return db.orders.fetch(number)

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

C'est tout le serveur. L'annotation de type des arguments fournit le schéma, la docstring fournit la description et le décorateur enregistre l'outil. Le modèle voit exactement ce que tu as écrit dans la docstring, donc la première phrase doit dire ce que fait la fonction et la deuxième quand l'appeler.

Les ressources et les modèles de prompt fonctionnent de la même façon avec un autre décorateur.

Python
@mcp.resource("terms://{section}")
def terms(section: str) -> str:
    """Contents of the named terms of service section."""
    return read_section(section)

La différence entre les deux est de fond et pas cosmétique. Un outil a un effet, donc le client demande généralement l'accord de l'utilisateur. Une ressource est une lecture, donc le client peut la récupérer sans aide. L'article sur le protocole MCP traite cette séparation plus en profondeur.

Composition et proxy

Deux fonctionnalités distinguent ce paquet d'une implémentation minimale, et toutes deux résolvent des problèmes qui apparaissent vers ton troisième serveur.

La composition te permet d'assembler un serveur à partir de plusieurs plus petits. Au lieu de trente outils dans un seul fichier, tu as trois modules thématiques, testés séparément et combinés au démarrage. Sur un projet plus grand, c'est la différence entre du code maintenable et un fichier que personne ne veut ouvrir.

Le proxy te permet d'exposer le serveur de quelqu'un d'autre sous ta propre adresse, en filtrant des outils ou en ajoutant de l'authentification au passage. C'est pratique pour partager un serveur avec une équipe quand le serveur lui-même n'a aucun contrôle d'accès.

Avant d'envelopper le serveur de quelqu'un d'autre, vérifie toutefois s'il porte déjà ses propres restrictions. Le serveur GitHub répartit ses outils en jeux d'outils activés par une variable d'environnement et a un mode lecture seule, donc un proxy ajouterait surtout un élément de plus à maintenir. Le gain se voit avec des serveurs qui exposent tout à la fois et ne demandent jamais qui demande.

Python
from fastmcp import FastMCP

main = FastMCP("company")
main.mount(orders_server, namespace="orders")
main.mount(customers_server, namespace="customers")

Lors de la composition, fixe tôt une convention de nommage. L'espace de noms donné au moment du montage devient une partie du nom d'outil que voit le modèle, donc orders_status se lit mieux que srv1_get. L'ancien nom de cet argument, prefix, fonctionne encore mais déclenche un avertissement de dépréciation. Renommer plus tard signifie que toutes les configurations de clients enregistrées cessent de correspondre.

Une autre commodité est de générer un serveur à partir d'une description OpenAPI existante. Si ton API est documentée, tu obtiens un jeu d'outils sans les écrire à la main, ce qui, avec cinquante endpoints, fait gagner une journée de travail. Relis et élague toutefois le résultat, car les descriptions automatiques tirées de la documentation de l'API disent rarement au modèle quand utiliser un outil.

L'absence d'état du protocole et ce qui en découle

La spécification du protocole du 28 juillet 2026 a retiré les sessions de la couche du protocole. C'est une bonne nouvelle pour le déploiement, car un serveur évolue comme un service ordinaire sans état, mais cela soulève une question pour les applications qui ont besoin d'état.

C'est précisément ce que traite la version quatre : construire des applications avec état sur un protocole sans session. L'état cesse d'appartenir à une connexion et devient quelque chose que tu stockes délibérément et lies à un identifiant transporté dans la requête.

En pratique, cela demande un changement de façon de penser. Avant, tu pouvais garder le contexte de la conversation dans la mémoire du processus qui servait une connexion. Maintenant il doit vivre quelque part que toutes les instances peuvent atteindre : une base de données, un magasin clé-valeur ou un jeton transmis par le client.

Avec des serveurs existants, vérifie s'ils s'appuient sur la durée de vie de la connexion. Si c'est le cas, la migration est généralement simple mais demande de décider délibérément où l'état doit vivre.

Authentification et déploiement

Un serveur local n'a pas besoin d'authentification, car le client le lance comme sous-processus. Un serveur distant en a toujours besoin, et la bibliothèque fournit des mécanismes plutôt que de te laisser faire.

La configuration couvre les fournisseurs d'identité et le contrôle d'accès au niveau des outils individuels, donc le même serveur peut exposer différents ensembles de fonctions à différents utilisateurs. Cela compte avec les outils qui modifient des données, où les lectures peuvent être largement accessibles et les écritures étroitement.

Côté déploiement, il y a la publication depuis un dépôt avec des aperçus de branche et un retour arrière rapide, ainsi qu'un registre privé de serveurs au sein d'une organisation. Ce dernier élément résout un problème qui arrive plus tôt qu'on ne le pense : au bout de six mois, personne ne sait combien de serveurs tournent dans l'entreprise ni à qui ils appartiennent.

L'alternative est l'auto-déploiement sur n'importe quelle plateforme qui sert du HTTP, Cloudflare par exemple, ou des conteneurs. L'absence d'état du protocole signifie que tu n'as pas besoin d'attacher un client à une instance.

Tests

C'est le domaine où le paquet séparé apporte le plus et, en même temps, celui que les gens utilisent le moins.

Le client intégré à la bibliothèque te permet d'appeler ton propre serveur dans un test sans lancer de processus séparé. Le test ressemble à un test unitaire ordinaire tout en couvrant tout le chemin : enregistrement de l'outil, validation des arguments et forme de la réponse.

Python
from fastmcp import Client

async def test_status_returns_data():
    async with Client(mcp) as client:
        result = await client.call_tool("order_status", {"number": "ORD-12345"})
        assert "status" in result.data

Trois choses méritent d'être testées. Que l'outil apparaisse dans la liste, car une faute de frappe dans le décorateur ne lève aucune erreur. Que la validation rejette les mauvais arguments, car le modèle en enverra. Que la réponse garde une forme stable, car l'agent construit les étapes suivantes dessus.

Séparément, lance l'outil d'inspection avant de brancher le serveur à un assistant. Il montre la liste des outils telle que le modèle la verra et te permet d'appeler chacun à la main. Cette étape détecte les mauvaises descriptions plus vite que n'importe quel test.

Contexte d'appel et rappels vers le client

Un outil qui s'exécute isolé de celui qui l'a appelé suffit pour les cas simples. Une intégration sérieuse a besoin d'accéder aux informations sur l'appel et de pouvoir reparler au client.

Le contexte injecté dans la fonction donne accès à l'identité de l'appelant, aux événements de journalisation visibles côté client et au suivi de progression pendant les opérations plus longues.

Python
from fastmcp import FastMCP, Context

mcp = FastMCP("reports")

@mcp.tool
async def build_report(month: str, ctx: Context) -> str:
    """Generates a sales report for the given month in YYYY-MM format."""
    await ctx.info(f"Collecting data for {month}")
    data = await fetch_data(month)
    await ctx.report_progress(progress=50, total=100)
    return assemble_report(data)

Le suivi de progression compte en pratique, car sans lui une opération d'une minute ressemble pour l'utilisateur à un blocage. Le client affiche alors une barre de progression au lieu du silence.

Un mécanisme distinct permet de poser une question à l'utilisateur en cours d'exécution. Si un outil a besoin d'une information qu'il n'a pas reçue dans ses arguments, il peut la demander au lieu de deviner ou de renvoyer une erreur. Cela résout le problème classique des opérations qui ont besoin d'une confirmation ou d'un choix parmi plusieurs enregistrements correspondants.

Une troisième option demande au client d'appeler un modèle. Le serveur n'a pas besoin de sa propre clé de fournisseur, car il utilise celle que l'application appelante détient déjà. Cela simplifie la configuration et place le coût là où il est de toute façon facturé.

FastMCP face aux alternatives

ApprocheAvantageInconvénientÀ choisir quand
FastMCP en paquet séparéComposition, OpenAPI, proxy, outils de testPlus de dépendances, versions qui évoluent viteServeur de production, nombreux clients
La version du kit officielMoins de dépendances, un client et l'authentification depuis la version deuxPas de composition, d'OpenAPI ni de proxyServeur local simple
Implémenter à partir de zéroContrôle total, pas de dépendancesTu gères le protocole et ses changementsEnvironnement inhabituel ou autre langage
Un serveur fourni par l'éditeurAucun travailPérimètre fixé par l'éditeurIntégration avec un service populaire

Pour choisir entre les paquets, pèse le rythme des changements. Le paquet séparé sort souvent des versions, ce qui donne un accès rapide aux nouvelles capacités et demande de figer une version dans ton fichier de dépendances si tu préfères éviter les surprises au moment du build.

Avant d'écrire quoi que ce soit, vérifie si un serveur pour ton service existe déjà. De nombreuses plateformes publient le leur, et en écrire un autre répète un travail que quelqu'un a déjà fait.

Du script au serveur, le chemin habituel

La plupart des serveurs naissent de la même façon, et connaître ce chemin raccourcit une première tentative.

Tout commence par un script qui fait quelque chose de répétitif : récupérer des données d'un système interne, générer un résumé, vérifier un statut. Tu le lances à la main, et à chaque exécution tu te rappelles les arguments qu'il prend.

La première étape enveloppe la fonction dans un décorateur et écrit la docstring pour qu'un modèle comprenne quand l'utiliser. C'est littéralement quelques minutes, et l'effet est immédiat : tu n'as plus besoin de te rappeler la syntaxe, car tu décris la tâche avec des mots.

La deuxième étape arrive quand il y a plusieurs outils. Il devient alors rentable de les répartir par thème et de composer un serveur plutôt que d'empiler des fonctions dans un fichier. Pendant que tu y es, ajoute une gestion d'erreurs qui renvoie un message lisible, car un agent s'en sort avec « pas d'autorisation pour cette ressource » et ne s'en sort pas avec un plantage.

La troisième étape partage le serveur avec une équipe. Cela met fin à l'édition locale et démarre un déploiement distant avec authentification et permissions restreintes. C'est aussi le moment où les descriptions d'outils cessent d'être ton affaire privée, car un modèle les lit pour plusieurs personnes.

La quatrième étape, que peu envisagent au départ, est l'élagage. Au bout de six mois, certains outils ne servent plus et d'autres font la même chose sous deux noms. Une revue trimestrielle garde l'ensemble à une taille où le modèle choisit encore avec précision.

Erreurs courantes

La première est d'écrire des docstrings pour un développeur plutôt que pour un modèle. Le modèle lit le même texte, donc une phrase qui dit quand appeler l'outil compte plus qu'une description de l'implémentation.

La deuxième est de renvoyer une réponse d'API brute. Trois cents lignes de JSON au lieu de cinq champs augmentent le coût et réduisent la précision des étapes suivantes de l'agent.

La troisième est l'absence de gestion d'erreurs. Une exception arrête l'agent sans aucune information sur ce qui s'est mal passé, alors qu'un message lisible lui permet d'essayer autrement.

La quatrième est d'exposer un serveur distant sans authentification. Tout ce que tu as donné au modèle, tu le donnes à quiconque connaît l'adresse.

La cinquième est de garder l'état dans la mémoire du processus. Avec un protocole sans session, la requête suivante peut atteindre une autre instance, donc l'état doit vivre quelque part que toutes peuvent atteindre.

FAQ

FastMCP est-il la même chose que le kit de développement officiel ?

En partie. La première version du projet a été intégrée au kit Python officiel en 2024 et y vit comme module, même si la version deux du kit a renommé la classe MCPServer. Le paquet séparé continue d'évoluer et ajoute la composition de serveurs, l'intégration OpenAPI et le proxy que la version intégrée n'a pas. Un client et l'authentification, le kit officiel les a développés de son côté.

Quelle version dois-je utiliser ?

Pour un serveur local simple avec quelques outils, la version du kit officiel suffit. Pour un serveur de production, un serveur distant ou un serveur qui sert de nombreux utilisateurs, prends le paquet séparé, car sinon tu écriras toi-même ces mêmes fonctionnalités.

Ai-je besoin d'une version précise de Python ?

La bibliothèque demande Python 3.10 ou plus récent. Sur des projets plus anciens, cela peut être un vrai obstacle, donc vérifie-le avant de planifier une intégration.

Qu'est-ce que l'absence d'état du protocole change ?

Un serveur distant ne garde aucune session, donc chaque requête peut être servie par une instance différente. Cela facilite le déploiement et le passage à l'échelle, alors que l'état de l'application doit être stocké délibérément, dans une base de données ou un jeton, plutôt que dans la mémoire du processus. La version quatre de la bibliothèque traite exactement ce scénario.

Comment brancher un serveur terminé à un assistant ?

Tu indiques dans la configuration du client comment le lancer ou où le trouver, et le même serveur fonctionne ensuite dans l'application Claude, dans Cursor et dans des bibliothèques d'agents comme LangChain. C'est tout l'intérêt du protocole : tu écris l'intégration une seule fois.

La documentation se trouve sur gofastmcp.com, et le code source dans le dépôt GitHub, que le projet gère sous la bannière de Prefect.

À lire aussi