Publié le

Tutoriel Complet : Transformer les API FastAPI en Outils Intelligents avec FastAPI-MCP

50 min read
Auteurs
  • Profile picture of aithemes.net
    Nom
    aithemes.net
    Twitter

FastAPI-MCP est un framework qui étend FastAPI pour exposer de manière transparente vos points de terminaison d'API en tant qu'outils Model Context Protocol (MCP). Ce tutoriel vous guidera à travers tout, des bases à l'utilisation avancée de FastAPI-MCP, adapté aussi bien aux débutants complets qu'aux développeurs FastAPI expérimentés. Nous couvrirons les explications conceptuelles, la décomposition des composants, des exemples de code et des illustrations basées sur des projets. À la fin, vous saurez comment configurer FastAPI-MCP, le configurer, le sécuriser avec des dépendances (auth), l'intégrer avec des clients IA, le déployer et le tester dans des scénarios réels.

Image de l'article

Introduction à FastAPI-MCP

FastAPI est un framework web Python populaire pour construire rapidement des API avec une documentation OpenAPI automatique. MCP (Model Context Protocol), d'autre part, est une norme ouverte émergente qui définit comment les assistants IA (comme GPT-4, Claude d'Anthropic, etc.) communiquent avec les applications et les outils. Pensez à MCP comme un « port USB-C pour les applications IA » – une interface universelle qui permet aux modèles IA de découvrir et d'utiliser des outils externes ou des sources de données de manière standardisée. En utilisant MCP, les modèles IA peuvent :

  • Découvrir quels outils (opérations API) sont disponibles et ce qu'ils font.
  • Comprendre comment invoquer ces outils (leurs entrées/sorties).
  • Récupérer des données ou exécuter des opérations via ces outils de manière unifiée.

FastAPI-MCP comble le fossé entre vos API FastAPI et l'écosystème d'outillage IA. En termes simples, FastAPI-MCP transformera automatiquement vos points de terminaison FastAPI existants en outils compatibles MCP avec un effort minimal. Cela signifie que vous pouvez exposer votre API aux assistants IA (tels que Claude dans Cursor IDE, GPT dans des clients compatibles, etc.) afin qu'ils puissent appeler vos opérations API de manière sécurisée et transparente.

Pourquoi utiliser FastAPI-MCP ?

FastAPI-MCP offre une approche native à FastAPI, sans configuration pour l'intégration IA. Vous n'avez pas besoin de réécrire votre API ou de gérer des spécifications de plugin complexes – FastAPI-MCP utilise votre application FastAPI existante et construit automatiquement une interface MCP par-dessus. Les fonctionnalités clés incluent :

  • Intégration native des dépendances – Vous pouvez sécuriser les appels d'outils MCP en utilisant les mêmes dépendances Depends() (par exemple pour l'authentification) que vous utilisez dans FastAPI. Cela signifie que la logique d'authentification/autorisation existante peut être réutilisée pour les appels initiés par l'IA.
  • Préservation des schémas et de la documentation – Il préserve les modèles de requête/réponse et la documentation de vos points de terminaison, tout comme votre documentation OpenAPI/Swagger. Les agents IA obtiennent les mêmes informations sur les paramètres et les réponses que les développeurs humains.
  • Configuration nulle/minimale – Pointez simplement FastAPI-MCP vers votre application FastAPI et cela fonctionne immédiatement. Aucun mappage manuel ou décorateur spécial n'est nécessaire.
  • Conception FastAPI-first – Ce n'est pas seulement un convertisseur depuis OpenAPI ; il s'accroche directement au système de routage et de dépendances de FastAPI pour l'efficacité et la fidélité.
  • Support d'authentification intégré – Il prend en charge l'ajout d'exigences d'authentification (clés API, OAuth2) pour les points de terminaison MCP en utilisant les dépendances ou configurations FastAPI.
  • Déploiement flexible – Vous pouvez monter le serveur MCP sur la même application (même processus) ou le servir comme un service séparé ; les deux modes sont pris en charge.
  • Transport ASGI efficace – Par défaut, les appels MCP sont gérés en interne via ASGI (pas de saut HTTP supplémentaire), rendant la communication rapide et ne nécessitant même pas d'URL de base lorsqu'ils sont co-hébergés.

En résumé, FastAPI-MCP rend simple la transformation de votre API en une interface accessible à l'IA. Ensuite, nous allons nous plonger dans sa configuration étape par étape.

Démarrer avec FastAPI-MCP

Commençons de zéro et construisons une application FastAPI simple, puis activons MCP dessus. Cette section vous guidera à travers l'installation, la configuration de base et la confirmation que le serveur MCP est en cours d'exécution.

Installation

FastAPI-MCP est un package Python. Vous pouvez l'installer via pip ou uv (un gestionnaire de paquets Python rapide recommandé par les auteurs) :

# Utilisation de uv (si vous l'avez installé)
uv add fastapi-mcp

# Utilisation de pip
pip install fastapi-mcp

Cela installera également FastAPI (s'il ne l'est pas déjà) comme dépendance. Assurez-vous d'avoir Python 3.10+ (FastAPI-MCP nécessite Python 3.10 ou plus récent). Vous voudrez probablement aussi installer Uvicorn pour exécuter l'application, et toutes les autres dépendances FastAPI que vous prévoyez d'utiliser (comme pydantic, etc.). Par exemple :

pip install fastapi uvicorn

Vous êtes maintenant prêt à créer votre application FastAPI et à intégrer MCP.

Configuration et Implémentation de Base

Étape 1 : Créer une application FastAPI avec un point de terminaison. Si vous avez déjà une application FastAPI, vous pouvez l'utiliser ; sinon, créons-en une minimale. Dans un fichier (par exemple main.py), écrivez :

from fastapi import FastAPI

app = FastAPI()

# Définir un point de terminaison (opération) exemple comme vous le feriez normalement
@app.get("/items/{item_id}", operation_id="get_item")
async def read_item(item_id: int):
    """Récupérer un article par son ID"""
    return {"item_id": item_id, "name": f"Item {item_id}"}

Ceci définit un simple point de terminaison GET /items/{item_id} qui retourne un JSON avec l'ID et le nom de l'article. Nous lui avons donné un operation_id="get_item" explicite – c'est le nom qui identifiera ce point de terminaison comme un outil MCP (plus d'informations à ce sujet dans la section suivante). Si vous ne spécifiez pas operation_id, FastAPI en générera un automatiquement, mais il a tendance à être verbeux (par exemple "read_item_items__item_id__get"), ce qui est moins intuitif.

Étape 2 : Monter FastAPI-MCP sur l'application. Avec FastAPI-MCP, transformer l'API ci-dessus en un serveur MCP ne prend que quelques lignes de code. En continuant dans main.py :

from fastapi_mcp import FastApiMCP

# ... (Application FastAPI et points de terminaison comme ci-dessus) ...

# Créer une instance de serveur MCP pour notre application
mcp = FastApiMCP(
    app,
    name="My API MCP",                  # Nom optionnel pour le service MCP
    description="MCP server for my API" # Description optionnelle
    # base_url="http://localhost:8000"  # URL de base, non requise si on utilise le transport ASGI
)

# Monter le serveur MCP sur l'application FastAPI
mcp.mount()

C'est tout ! En appelant FastApiMCP(app) et mcp.mount(), nous attachons un service MCP entièrement fonctionnel à notre application FastAPI. Nous avons fourni un nom et une description lisibles par l'homme pour le serveur MCP (ces métadonnées aident les clients à l'identifier), et nous pourrions spécifier une base_url si nécessaire. Lorsqu'il est monté sur la même application, FastAPI-MCP utilise des appels ASGI directs, donc base_url est optionnel. (Si vous déployez le MCP séparément de l'API principale, une base_url garantit que le MCP sait où envoyer les requêtes – nous discuterons de ce scénario plus tard.)

Après le montage, FastAPI-MCP enregistre automatiquement une nouvelle route (par défaut au chemin /mcp) sur votre application FastAPI. C'est le point de terminaison auquel les clients MCP (agents IA ou outils) se connecteront.

Étape 3 : Exécuter l'application. Lancez votre application en utilisant Uvicorn (ou votre serveur ASGI préféré) :

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Cela démarre l'application FastAPI (avec notre route /items/{item_id}) et aussi le serveur MCP au point de terminaison /mcp.

Étape 4 : Tester le point de terminaison MCP. Ouvrez un navigateur (ou utilisez curl) et allez à http://127.0.0.1:8000/mcp. Vous ne verrez pas une réponse JSON typique ; au lieu de cela, parce que MCP utilise les Server-Sent Events (SSE) pour communiquer, votre navigateur pourrait garder la connexion ouverte et afficher un flux d'événements. Par exemple, vous pourriez voir quelque chose comme :

event: endpoint
data: /mcp/messages/?session_id=abcdef123456...

C'est normal – cela indique que le serveur MCP est en cours d'exécution et prêt. Essentiellement, le point de terminaison MCP établit immédiatement une session pour les clients via SSE. (Si vous voyez des données SSE brutes comme ci-dessus, c'est attendu car les navigateurs ne rendent pas nativement les flux SSE.)

Vous pouvez également vérifier que votre API originale fonctionne toujours : essayez http://127.0.0.1:8000/items/42 – cela devrait retourner {"item_id": 42, "name": "Item 42"} comme d'habitude. La fonctionnalité normale de l'application FastAPI est inchangée ; le serveur MCP est un add-on qui s'exécute aux côtés de votre API.

À ce stade, avec une configuration minimale, vous avez un service FastAPI compatible MCP. Les capacités de votre API (dans ce cas, le seul point de terminaison /items/{item_id}) sont maintenant découvrables et appelables par n'importe quel agent IA compatible MCP. Dans les sections suivantes, nous explorerons ce qui a été exposé exactement, comment le personnaliser et comment un client IA l'utiliserait.

Comprendre les Outils et Services MCP

Maintenant que notre serveur MCP est en cours d'exécution, clarifions ce que FastAPI-MCP a créé. En coulisses, FastAPI-MCP traite chaque opération API comme un Outil en termes MCP, et la collection d'outils servie au point de terminaison /mcp comme un Service (service serveur MCP). Voici une décomposition des composants :

  • Serveur MCP (Service) : C'est le service que nous avons monté à /mcp. Il agit comme une interface pour les clients IA. Lorsqu'un agent IA se connecte à /mcp (généralement via SSE), il peut interroger quels outils sont disponibles et les invoquer. Le serveur MCP s'occupe de lister vos points de terminaison et de router les appels vers eux.
  • Outils MCP : Ce sont les opérations individuelles (points de terminaison) de votre application FastAPI qui sont exposées. Chaque opération de chemin FastAPI devient un outil avec un nom, une description, un schéma de paramètres d'entrée et un schéma de sortie. Par défaut, FastAPI-MCP nomme chaque outil d'après l'operation_id du point de terminaison. Dans notre exemple, le point de terminaison /items/{item_id} a operation_id="get_item", donc un client IA verra un outil appelé "get_item" – il sait que cet outil attend un item_id: int et retourne un objet item.

Découverte d'Outils et Documentation

Un aspect puissant de FastAPI-MCP est qu'il découvre automatiquement tous vos points de terminaison FastAPI et expose leurs métadonnées à l'IA. Cela inclut : le chemin, la méthode HTTP, les paramètres d'entrée attendus (avec types/contraintes), et le modèle ou schéma de réponse. Essentiellement, il reflète ce qui se trouve dans votre documentation OpenAPI. Par exemple, si vous avez défini des modèles Pydantic pour la requête ou la réponse, ces schémas sont inclus dans la description de l'outil.

Cela signifie qu'un agent IA peut interroger le serveur MCP (généralement par une requête initiale "lister les outils") et obtenir une liste de noms et de descriptions d'outils. La description de chaque outil inclut ce qu'il fait et comment l'utiliser. FastAPI-MCP utilise la docstring et toute description que vous avez fournie dans la route FastAPI comme partie de la description de l'outil. Donc si vous avez documenté votre point de terminaison (comme nous l'avons fait avec une docstring pour read_item), l'IA le voit. Une API bien documentée aide l'IA à choisir et utiliser correctement les outils.

IDs d'Opération et Nommage des Outils : Comme mentionné, les noms des outils dérivent de operation_id. Si vous n'en définissez pas, FastAPI générera automatiquement un nom. Ces noms autogénérés fonctionnent, mais sont souvent longs et peu conviviaux. Pour les agents IA, il est bénéfique d'avoir des noms descriptifs et concis – c'est donc une meilleure pratique de définir operation_id pour chaque point de terminaison avec quelque chose de significatif. Par exemple, get_user_info pour un point de terminaison qui récupère les informations utilisateur (plutôt qu'un nom par défaut comme read_user_users__user_id__get). Des noms d'outils clairs facilitent la décision de l'IA sur quel outil utiliser pour une tâche donnée.

Si vous avez déjà une application FastAPI existante sans operation_ids, vous pouvez les ajouter sans changer la fonctionnalité (ils n'affectent que la documentation/les spécifications). Au minimum, assurez-vous que l'operation_id de chaque point de terminaison est unique dans toute l'application.

Comment les Agents IA Utilisent les Outils MCP

Un agent IA (client) connecté à votre serveur MCP va typiquement :

  1. Lister les outils disponibles – Le client demande la liste des outils au serveur MCP (c'est souvent une étape automatique lors de la connexion). Le serveur MCP répond avec les noms et descriptions de tous les points de terminaison/outils inclus. L'agent sait maintenant ce qu'il peut faire (par exemple, il voit un outil get_item qui récupère un article par ID).
  2. Choisir un outil et l'appeler – Lorsque le raisonnement de l'IA décide d'effectuer une action (disons, "récupérer l'article 42"), il invoquera l'outil MCP correspondant. En coulisses, cela signifie envoyer une requête via le protocole MCP (que FastAPI-MCP traduit en appelant votre point de terminaison FastAPI). Les paramètres d'entrée (comme item_id=42) sont passés, et FastAPI-MCP appelle la fonction read_item comme un appel API normal, puis retourne le résultat au client IA.
  3. Recevoir le résultat – L'IA obtient la réponse du point de terminaison (ici, {"item_id": 42, "name": "Item 42"}) via le canal MCP et peut l'utiliser dans sa conversation ou son calcul. Le protocole garantit que la réponse est structurée (suivant le schéma JSON de votre point de terminaison).

Tout cela se passe de manière sécurisée et en temps réel. Du point de vue du développeur, votre code de point de terminaison FastAPI ne change pas du tout – FastAPI-MCP gère la conversion de l'appel d'outil de l'IA en un appel de fonction normal à votre point de terminaison et le streaming de la réponse en retour.

Important : MCP utilise le streaming SSE par défaut pour les réponses, car certaines sorties d'outils peuvent être volumineuses ou streamées. FastAPI-MCP gère cela pour vous. Si un client se connecte via SSE, les résultats sont envoyés sous forme d'événements. Si un client ne peut pas gérer SSE, il pourrait utiliser un proxy (discuté plus tard). Dans tous les cas, en tant que développeur d'API, vous n'avez généralement pas besoin de vous soucier des détails du streaming – implémentez votre point de terminaison normalement (en retournant des données ou en utilisant StreamingResponse si vous streamez déjà). FastAPI-MCP l'adaptera aux exigences de MCP.

Structurer un Projet FastAPI-MCP

Que vous ajoutiez FastAPI-MCP à un projet existant ou que vous en commenciez un nouveau, vous devriez organiser votre code de manière maintenable. Dans les petites démos, tout dans un seul fichier est acceptable, mais pour les projets plus importants, considérez la structure suivante :

myproject/
├── app.py          # Application FastAPI et définitions des routes API
├── mcp_app.py      # (Optionnel) Application FastAPI séparée pour MCP si déployé séparément
├── routes/         # Package pour les modules de routes, si vous divisez vos points de terminaison
│   ├── __init__.py
│   └── items.py    # ex., définit les points de terminaison /items
├── models/         # Modèles de données (modèles Pydantic, etc.)
├── auth/           # Utilitaires d'authentification (s'il y en a)
└── ... (autres modules)

Configuration mono-application : Si vous prévoyez de servir le MCP sur la même instance d'application que votre API (ce qui est le plus simple), vous pouvez l'intégrer dans votre code d'application principal. Par exemple, dans app.py après avoir défini toutes vos routes, vous instanciez FastApiMCP(app) et appelez mcp.mount(). Il est souvent judicieux de créer le MCP après que toutes vos routes ont été ajoutées, afin qu'il capture chaque point de terminaison. De cette façon, vous n'avez pas à "rafraîchir" le MCP lorsque de nouvelles routes sont ajoutées (plus sur le rafraîchissement dans un instant).

Configuration multi-applications (style microservice) : Dans certains cas, vous pourriez vouloir exécuter le serveur MCP comme un service séparé de l'API principale. FastAPI-MCP prend cela en charge en vous permettant de monter le MCP sur une application FastAPI différente. Par exemple :

# fichier: api_app.py
from fastapi import FastAPI
api_app = FastAPI()
# ... définir tous vos points de terminaison API sur api_app ...

# fichier: mcp_app.py
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
from api_app import api_app  # importer l'autre application FastAPI

mcp_app = FastAPI()                 # application séparée juste pour MCP
mcp = FastApiMCP(api_app)           # créer MCP à partir de l'application API
mcp.mount(mcp_app)                  # monter les routes MCP sur l'application séparée

Ici, nous avons deux instances FastAPI : api_app (avec nos points de terminaison réguliers) et mcp_app (qui ne sert que l'interface MCP). Nous passons api_app dans FastApiMCP et le montons sur mcp_app. Nous exécuterions ensuite ces deux applications séparément (par exemple, uvicorn api_app:api_app sur un hôte/port et uvicorn mcp_app:mcp_app sur un autre). Le serveur MCP appellera l'autre application en interne. Dans ce scénario, puisqu'il s'agit de processus séparés, vous devriez définir la base_url dans FastApiMCP pour pointer vers l'hôte de l'API (ou fournir un client HTTP personnalisé) afin que le MCP sache comment atteindre l'application API. Alternativement, vous pouvez les exécuter dans le même processus en montant une application à l'intérieur de l'autre, mais c'est moins courant.

Quelle configuration choisir ? Pour de nombreux cas, monter MCP sur la même application (peut-être sous le chemin /mcp) est parfaitement acceptable et plus simple. Cela garde tout dans un seul service à déployer. Cependant, un déploiement séparé pourrait être utile si :

  • Vous voulez mettre à l'échelle ou sécuriser l'interface MCP indépendamment. Par exemple, si le service MCP est destiné à un usage interne par des agents IA, vous pourriez l'héberger sur un réseau interne séparé de l'API principale.
  • Vous voulez exécuter le serveur MCP sur un port ou un domaine différent (peut-être en raison d'exigences SSE ou client).
  • Votre API est très sensible aux performances et vous préférez isoler la surcharge de MCP (bien que MCP soit léger).

La flexibilité de FastAPI-MCP signifie que vous pouvez commencer avec un montage groupé (pour la commodité du développement) et le diviser plus tard sans changer le code de vos points de terminaison – ajustez simplement la façon dont vous créez et montez le serveur MCP.

Conseils sur la structure du projet : Gardez votre application FastAPI modulaire (utilisez des routeurs, des fichiers séparés pour la logique), car FastAPI-MCP n'a besoin que de l'objet FastAPI final. Si vous ajoutez de nouvelles routes après la configuration de MCP (par exemple, dynamiquement ou dans un cadre interactif), vous devrez rafraîchir le serveur MCP pour les prendre en compte (via mcp.setup_server() qui re-scanne les points de terminaison). Dans une application statique typique, assurez-vous simplement que toutes les routes sont définies avant de monter MCP. Si jamais vous oubliez et que vos nouveaux outils n'apparaissent pas, vous pouvez appeler mcp.setup_server() ou recréer l'instance MCP.

Configuration et Personnalisation

FastAPI-MCP fonctionne sans configuration par défaut, mais il offre plusieurs options pour personnaliser le comportement du serveur MCP et les outils exposés. Ici, nous discuterons de la configuration des métadonnées du serveur, de l'amélioration de la documentation des outils et du filtrage des points de terminaison exposés.

Métadonnées du Serveur (Nom & Description)

Lors de la création de FastApiMCP, vous pouvez passer un name et une description pour votre service MCP. Ceux-ci aident à identifier votre service auprès des clients. Par exemple :

mcp = FastApiMCP(app,
                 name="Inventory API MCP",
                 description="MCP interface for my Inventory API")

Dans le protocole MCP, le serveur peut présenter un nom/description que les clients pourraient afficher dans une interface. C'est optionnel mais recommandé de le définir, surtout si vous exécutez plusieurs services MCP. Par défaut, s'il n'est pas défini, il peut utiliser un nom générique. Définir une description claire (par exemple, "Points de terminaison pour gérer les articles d'inventaire") peut guider les agents IA ou les développeurs sur le but du service.

Descriptions des Outils et Schémas de Réponse

FastAPI-MCP utilise automatiquement votre documentation FastAPI (descriptions des opérations de chemin, documentation des schémas Pydantic, etc.) pour décrire chaque outil. Si vous souhaitez fournir des descriptions encore plus riches pour l'IA, FastAPI-MCP propose des indicateurs pour inclure plus de détails de schéma :

  • describe_all_responses=True : inclut la documentation de tous les codes de réponse possibles et des schémas pour le point de terminaison dans la description de l'outil. Normalement, la description d'un outil peut se concentrer sur la réponse de succès principale ; avec ceci, si vous avez plusieurs modèles de réponse (par exemple, des réponses d'erreur), ceux-ci seront également décrits.
  • describe_full_response_schema=True : inclut le schéma JSON complet du modèle de réponse dans la description de l'outil. Cela peut être très utile pour que les agents IA comprennent pleinement la structure de la sortie. Par exemple, si votre point de terminaison retourne un JSON imbriqué, l'IA connaîtra les champs et types exacts attendus.

Vous pouvez activer ces options lors de l'instanciation de FastApiMCP :

mcp = FastApiMCP(app,
                 describe_all_responses=True,
                 describe_full_response_schema=True)

Soyez conscient que des descriptions extrêmement verbeuses peuvent ou non aider un modèle IA – cela pourrait être bénéfique pour la précision, mais certains clients pourraient tronquer les descriptions très longues. Utilisez ces indicateurs au besoin, surtout si vos points de terminaison ont des sorties complexes dont l'IA devrait être consciente.

Filtrage des Points de Terminaison (Exposition Sélective)

Dans de nombreux cas, vous ne voudrez peut-être pas exposer chaque point de terminaison API aux agents IA. Par exemple, une application pourrait avoir des points de terminaison internes ou d'administration qui ne sont pas sûrs pour une IA à utiliser, ou simplement non pertinents. FastAPI-MCP vous permet d'inclure ou d'exclure des points de terminaison en utilisant leurs IDs d'opération ou leurs tags.

Vous disposez de quatre principaux paramètres optionnels pour filtrer les outils :

  • include_operations : une liste d'IDs d'opération à inclure. Seuls ceux-ci deviendront des outils MCP (tous les autres sont ignorés).
  • exclude_operations : une liste d'IDs d'opération à exclure (tout le reste sera inclus).
  • include_tags : inclut uniquement les points de terminaison qui ont l'un de ces tags FastAPI. Si vous organisez vos routes par tags (par exemple tags=["public"]), vous pourriez exposer uniquement les "publics".
  • exclude_tags : exclut les points de terminaison qui ont l'un de ces tags.

Note : Vous ne pouvez pas mélanger l'inclusion et l'exclusion du même type – par exemple, vous ne pouvez pas utiliser à la fois include_operations et exclude_operations. Vous pouvez cependant combiner les filtres d'opération avec les filtres de tag. La logique lors de la combinaison est l'union gourmande : les points de terminaison correspondant à n'importe quel critère d'inclusion sont inclus, puis tous ceux correspondant aux critères d'exclusion sont supprimés.

Exemples :

  • Exposer uniquement des points de terminaison spécifiques :

    mcp = FastApiMCP(app, include_operations=["get_item", "list_items"])

    Cela exposerait uniquement les outils nommés get_item et list_items (et aucun autre point de terminaison).

  • Exclure un point de terminaison dangereux :

    mcp = FastApiMCP(app, exclude_operations=["delete_item"])

    Cela expose tous les points de terminaison sauf celui avec l'operation_id "delete_item". Utile si vous voulez bloquer certaines opérations (comme la suppression ou les actions sensibles) de l'utilisation par l'IA.

  • Par tags : Supposons que vous taguiez certaines routes comme admin ou internal. Alors :

    mcp = FastApiMCP(app, exclude_tags=["admin", "internal"])

    exposerait tout sauf les points de terminaison marqués avec ces tags (assurant que les API internes ne sont pas disponibles pour l'IA).

  • Combiné : Si vous voulez inclure uniquement certains tags mais aussi exclure une opération spécifique parmi ceux-ci, vous pourriez faire :

    mcp = FastApiMCP(app, include_tags=["public"], exclude_operations=["reset_database"])

    Cela prendrait tous les points de terminaison tagués "public" et les exposerait, sauf celui dont l'operation_id est "reset_database" même s'il avait ce tag.

En utilisant le filtrage, vous pouvez affiner la surface de votre API accessible à l'IA. Une stratégie courante est d'exposer uniquement les opérations en lecture seule ou sûres et d'exclure tout ce qui modifie les données ou effectue des actions critiques (surtout si votre serveur MCP pourrait être accédé par des agents IA non fiables). Cela nous amène aux considérations de sécurité que nous aborderons ensuite.

Rafraîchissement des Outils lors des Changements

Si votre application est de longue durée et que vous ajoutez dynamiquement des routes (peut-être via le montage de nouveaux routeurs à l'exécution ou d'autres systèmes de plugins), rappelez-vous que la liste des outils de FastAPI-MCP est construite lorsque vous appelez mcp.mount() (ou setup_server()). Les nouveaux points de terminaison ajoutés plus tard n'apparaîtront pas automatiquement tant que vous ne rafraîchissez pas. Vous avez deux façons de gérer cela :

  1. Définir toutes les routes d'abord, puis créer le serveur MCP. Au démarrage normal, ordonnez simplement votre code de manière à terminer l'ajout de routes à app avant d'appeler FastApiMCP(app) et mount(). C'est l'approche la plus simple et évite tout problème.

  2. Rafraîchir manuellement si nécessaire. Si vous devez ajouter une route après avoir monté MCP, appelez mcp.setup_server() ensuite pour re-scanner et enregistrer le nouveau point de terminaison. Alternativement, vous pourriez ré-initialiser FastApiMCP (mais setup_server() est plus facile). La FAQ note cette exigence : les points de terminaison ajoutés après la création ne sont pas vus tant que les outils ne sont pas ré-enregistrés.

En développement, il est facile d'oublier – si vous ne voyez pas un outil que vous attendez, vérifiez si le MCP a été créé trop tôt. Le journal ou la sortie SSE pourrait également avertir qu'aucun outil n'a été trouvé si cela se produit.

Injection de Dépendances et Sécurité (Authentification & Autorisation)

Sécuriser votre API lorsqu'elle est accédée par l'IA est crucial. FastAPI-MCP vous permet de tirer parti du système d'injection de dépendances de FastAPI pour appliquer l'authentification ou d'autres vérifications sur les appels MCP, tout comme vous le feriez sur les appels API normaux. En d'autres termes, vous pouvez appliquer OAuth2, l'authentification par clé API, les vérifications de permissions, etc., à l'interface MCP afin que seul un accès autorisé soit permis.

Utilisation des Dépendances FastAPI pour l'Authentification

Les points de terminaison FastAPI utilisent souvent des dépendances (via Depends(), Security(), etc.) pour l'authentification. Par exemple, vous pourriez avoir :

from fastapi import Depends, HTTPException
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/users/me")
async def get_current_user(token: str = Depends(oauth2_scheme)):
    user = verify_token_and_get_user(token)
    if not user:
        raise HTTPException(status_code=401, detail="Invalid or expired token")
    return {"username": user.username}

Si vous exposez un tel point de terminaison via MCP, un client IA devrait fournir l'en-tête Authorization (avec un jeton Bearer) pour l'utiliser. FastAPI-MCP honorera toutes les dépendances sur le point de terminaison original. Cela signifie que si la dépendance lève une HTTPException (par exemple 401), l'appel MCP entraînera également une erreur (et l'IA recevra un échec).

Cependant, tous les clients IA ne peuvent pas facilement fournir des jetons d'authentification prêts à l'emploi. De nombreux clients MCP actuels sont des IDE ou des agents qui pourraient ne pas connaître votre authentification. Pour gérer cela, FastAPI-MCP fournit un argument auth_config ou plus simple dependencies qui peut appliquer l'authentification au niveau MCP et faciliter le passage de jetons.

Authentification de Base par Clé API ou Jeton

La manière la plus simple de sécuriser le serveur MCP est d'exiger une clé API pour tous les appels d'outils. Vous pouvez le faire en ajoutant une dépendance à FastApiMCP qui vérifie un en-tête. Par exemple, en utilisant un en-tête de clé API :

from fastapi import Security, HTTPException
from fastapi.security import APIKeyHeader
from fastapi_mcp import AuthConfig # Import AuthConfig

api_key_header = APIKeyHeader(name="X-API-Key")

async def verify_api_key(key: str = Security(api_key_header)):
    if key != "mysecret123":
        raise HTTPException(status_code=403, detail="Invalid API Key")
    return True

mcp = FastApiMCP(app,
    # s'assurer que chaque requête MCP dépend de verify_api_key
    auth_config=AuthConfig(dependencies=[Depends(verify_api_key)])
)
mcp.mount()

Maintenant, tout appel à un outil via l'interface MCP nécessitera l'en-tête X-API-Key: mysecret123. Si l'en-tête est manquant ou incorrect, la requête MCP sera rejetée avec 403 Forbidden. Essentiellement, cela ajoute une dépendance globale sur le serveur MCP lui-même.

Note : Dans des exemples plus anciens ou une utilisation plus simple, vous pourriez voir FastApiMCP(app, mcp_dependencies=[Depends(verify_api_key)]) qui obtient le même effet. L'approche la plus récente l'enveloppe dans AuthConfig pour des options plus avancées. Quoi qu'il en soit, le concept est le même : FastAPI-MCP peut utiliser une dépendance pour protéger les outils.

Pour un schéma de clé API, le client IA doit envoyer cet en-tête. Si vous utilisez un outil comme mcp-remote ou un client personnalisé, vous pouvez le configurer pour inclure des en-têtes à chaque requête. Par exemple, en utilisant mcp-remote (un client proxy basé sur Node), on peut passer un en-tête comme :

"mcpServers": {
  "myapi": {
    "command": "npx",
    "args": ["mcp-remote", "http://localhost:8000/mcp", "--header", "X-API-Key:mysecret123"]
  }
}

Cela garantit que l'en-tête est attaché à chaque appel, satisfaisant la dépendance.

Authentification OAuth2

FastAPI-MCP prend également en charge le flux complet d'autorisation OAuth2 tel que spécifié dans la spécification MCP (2025-03-26). C'est plus complexe mais permet une connexion OAuth pilotée par l'utilisateur si le client le prend en charge. En pratique, à ce jour, de nombreux clients MCP ne prennent pas entièrement en charge les flux OAuth interactifs, donc l'utilisation d'un jeton API ou d'une clé API (comme ci-dessus) pourrait être plus simple. Si vous avez besoin d'OAuth2, vous pouvez configurer AuthConfig avec des paramètres OAuth comme l'émetteur, l'URL d'autorisation, l'URL du jeton, etc. Par exemple :

from fastapi_mcp import AuthConfig # Assurez-vous d'importer AuthConfig

mcp = FastApiMCP(app, auth_config=AuthConfig(
    issuer="https://auth.example.com/",
    authorize_url="https://auth.example.com/authorize",
    oauth_metadata_url="https://auth.example.com/.well-known/oauth-authorization-server"
))

Cela annoncerait au client MCP les détails OAuth. L'idée est que l'agent IA (ou l'utilisateur le contrôlant) pourrait obtenir un jeton via OAuth pour utiliser les outils. En pratique, jusqu'à ce que l'outillage client IA rattrape son retard, vous pourriez compter sur le passage de jetons ou les clés API.

Conseil : Vous pouvez combiner les approches : par exemple, autoriser le passage de jetons de base et avoir également une dépendance d'authentification qui vérifie un jeton valide. La documentation officielle suggère que si vous passez simplement un en-tête Authorization: Bearer <token> depuis le client, FastAPI-MCP le transmettra aux points de terminaison FastAPI. Donc si vos points de terminaison attendent déjà un jeton bearer via Depends(oauth2_scheme), cela fonctionnera tant que le client le fournit. Utiliser mcp-remote --header Authorization:Bearer <token> est une façon de s'en assurer.

Autres Utilisations de l'Injection de Dépendances

Outre l'authentification, vos points de terminaison pourraient utiliser des dépendances pour d'autres choses (session de base de données, etc.). La bonne nouvelle est que toutes celles-ci fonctionnent toujours normalement. FastAPI-MCP appelle votre point de terminaison via l'application FastAPI, donc les dépendances comme db: Session = Depends(get_db) s'exécuteront comme d'habitude. Il n'y a pas de différence entre un appel déclenché par l'IA et un appel HTTP normal en termes d'exécution de votre code de point de terminaison – la même injection de dépendances et le même contexte s'appliquent.

Une chose à noter : Si une dépendance attend un certain contexte (comme un objet de requête ou des en-têtes spéciaux), assurez-vous que le client MCP les fournit ou que votre dépendance peut gérer leur absence. Par exemple, les dépendances qui reposent sur Request pourraient se comporter différemment sous MCP puisque la "requête" est l'appel MCP. Mais dans la plupart des cas, ce n'est pas un problème.

Meilleures Pratiques de Sécurité : Lorsque vous exposez votre API à l'IA via MCP, considérez ces directives (similaires à la sécurité API normale, mais avec l'imprévisibilité des agents IA à l'esprit) :

  • Exposez uniquement les points de terminaison sûrs : Préférez les opérations en lecture seule ou idempotentes. Soyez très prudent en exposant tout ce qui modifie les données ou effectue des actions irréversibles. Si vous le faites, assurez-vous que l'authentification est requise et peut-être même une étape d'approbation en dehors de MCP.
  • Exigez l'authentification pour les opérations sensibles : Ne comptez pas sur l'obscurité. Si un point de terminaison retourne des données sensibles, protégez-le avec une authentification appropriée même si vous pensez que "seule l'IA" le connaît. Les listes MCP pourraient être accessibles à tout client ayant accès. Utilisez des clés API ou OAuth selon le cas.
  • Validez strictement les entrées : Vos points de terminaison devraient déjà le faire (en utilisant des modèles Pydantic, des indications de type). C'est d'autant plus important lorsque l'appelant est une IA qui pourrait faire des erreurs. Une validation robuste empêche l'IA de passer accidentellement des données invalides ou d'effectuer quelque chose d'inattendu.
  • Assainissez les sorties si nécessaire : Si certaines données doivent être partiellement masquées ou traitées avant d'être retournées (pour la confidentialité ou la sécurité), assurez-vous que votre point de terminaison le fait. Ne supposez pas que l'IA gérera la confidentialité – il vaut mieux que les données quittant votre serveur soient sûres.
  • Surveillez l'utilisation : Conservez des journaux des appels aux outils et de leurs paramètres. Surveiller comment l'IA utilise votre API peut aider à identifier une mauvaise utilisation ou des améliorations nécessaires. Vous pourriez détecter des schémas comme une IA appelant un point de terminaison trop fréquemment ou avec des paramètres étranges, ce qui pourrait indiquer une incompréhension que vous pouvez corriger en ajustant les descriptions ou en ajoutant des contraintes.

En utilisant l'injection de dépendances robuste et le modèle de sécurité de FastAPI, FastAPI-MCP vous permet d'appliquer toutes ces mesures pour l'accès IA comme vous le feriez pour l'accès humain.

Intégration avec les Clients et Outils IA

Une fois votre serveur FastAPI-MCP opérationnel et sécurisé de manière appropriée, l'étape suivante consiste à l'utiliser réellement avec un client IA. Il existe plusieurs façons pour les systèmes IA de se connecter à votre service MCP :

  • Connexion SSE Directe : De nombreux IDE IA ou frameworks d'agents prennent en charge MCP nativement via SSE.
  • Proxy ou Pont (mcp-remote) : Un petit proxy qui gère SSE et les fonctionnalités avancées, utile si le client ne prend pas en charge SSE ou si vous devez injecter l'authentification.
  • Inspecteur ou outils de Test : Utile pour les tests manuels et le débogage de votre interface MCP.
  • Intégration Personnalisée (LangChain ou code personnalisé) : Vous pouvez également écrire du code pour vous connecter à un serveur MCP, bien que les bibliothèques pour cela soient naissantes.

Explorons les méthodes courantes.

Connexion via Server-Sent Events (Directe)

Les serveurs MCP (comme FastAPI-MCP) utilisent fondamentalement les Server-Sent Events pour la communication. Des outils comme Cursor IDE, Claude Desktop, Windsurf, les extensions VSCode et d'autres ont commencé à prendre en charge MCP en vous permettant de configurer un point de terminaison MCP.

Par exemple, dans Cursor (IDE d'assistant de codage IA), vous pouvez ajouter votre serveur MCP dans ses paramètres. Cela pourrait impliquer l'édition d'un fichier de configuration mcp.json pour inclure votre serveur. Selon un guide, vous ajouteriez quelque chose comme :

{
  "mcpServers": {
    "fastapi-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Ici "fastapi-mcp" est juste une étiquette que vous donnez, et l'url pointe vers votre point de terminaison FastAPI-MCP en cours d'exécution. Dans Cursor, vous iriez dans Settings → MCP → Add new MCP server et saisiriez l'URL. Une fois configuré, le client se connectera (souvent immédiatement ou lorsque vous ouvrez un chat IA) à votre serveur MCP.

Que se passe-t-il ensuite ? Typiquement, l'IDE ou le client listera maintenant de nouveaux "outils" ou capacités. Dans le cas de Cursor, vous pourriez voir dans l'interface de l'agent que les outils de votre API (comme get_item) sont disponibles pour l'IA. Le modèle IA (avec une certaine ingénierie de prompt système) est informé de ces outils. Vous pouvez maintenant demander à l'IA de les utiliser. Par exemple, vous pourriez prompter : « Utilise l'outil get_item pour récupérer l'article 42. » L'IA, via l'intégration MCP, appellera l'outil et retournera le résultat dans sa réponse.

Pour illustrer, après la configuration, on pourrait simplement demander à l'IA (dans l'onglet agent de Cursor) : « Appelle le point de terminaison /items/42 pour moi. » L'IA détecterait que cela correspond à l'outil get_item et l'exécuterait, puis répondrait probablement avec les données. C'est incroyablement puissant – l'IA agit effectivement comme un intermédiaire vers votre API, permettant des interactions conversationnelles ou autonomes avec votre service.

La plupart des clients modernes conscients de MCP utilisent SSE, donc la connexion directe est souvent la plus simple. Assurez-vous que l'URL de votre serveur MCP est accessible au client (si vous exécutez les deux localement, localhost convient ; si l'IA est distante, vous devrez exposer une URL que l'IA peut atteindre).

Utilisation d'un Proxy MCP (pour l'Authentification ou les Clients Incompatibles)

Tous les clients IA ne prennent pas en charge SSE ou les en-têtes personnalisés. Par exemple, Claude Desktop d'Anthropic (dans ses versions antérieures) ne prenait pas en charge SSE nativement pour MCP, et certains outils pourraient ne pas vous permettre d'ajouter facilement des en-têtes d'authentification personnalisés. Dans ces cas, la solution recommandée est d'utiliser mcp-remote (également appelé mcp-proxy dans certaines documentations). C'est un package npm qui agit essentiellement comme un pont : il se connecte à votre serveur MCP via SSE d'un côté, et offre une interface stdio locale ou WebSocket de l'autre côté que le client IA peut utiliser.

Par exemple, vous pourriez configurer une entrée client MCP comme :

{
  "mcpServers": {
    "myapi-via-proxy": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "8080"
      ]
    }
  }
}

Cela indiquerait au système d'exécuter npx mcp-remote http://localhost:8000/mcp 8080. Cette commande se connecte à votre point de terminaison MCP et ouvre un port local 8080 que l'IA peut utiliser. L'IA se connecterait alors réellement au proxy (qui pourrait se présenter comme un serveur MCP sans contraintes SSE). Le proxy relaie les requêtes vers votre service FastAPI-MCP réel et renvoie les réponses.

Vous pouvez également passer des en-têtes via mcp-remote, comme montré précédemment, en utilisant --header "Authorization:Bearer XYZ" ou similaire, ce qui est très pratique pour l'authentification. Essentiellement, mcp-remote peut injecter ces en-têtes pour vous à chaque appel, de sorte que le client n'a pas besoin de les connaître.

Utilisez mcp-remote si :

  • Votre client ne prend pas en charge la fourniture des en-têtes d'authentification requis ou ne prend pas en charge SSE.
  • Vous voulez exécuter l'IA dans un environnement où une connexion de port local est plus facile que SSE (certains cas pour des raisons de pare-feu ou de compatibilité).
  • Vous avez besoin de déboguer ou de journaliser le trafic – exécuter un proxy peut vous permettre de voir les requêtes aller et venir.

mcp-remote est un outil Node, vous avez donc besoin de Node.js disponible dans l'environnement où le client IA s'exécute. La surcharge est généralement faible.

Inspecteur MCP (Test Manuel)

Avant d'impliquer une IA du tout, vous pourriez vouloir tester manuellement votre serveur MCP pour voir quels outils il expose et vous assurer qu'ils fonctionnent. L'Inspecteur MCP est un utilitaire en ligne de commande à cet effet, fourni par le projet Model Context Protocol. Vous pouvez également l'exécuter avec npx :

npx @modelcontextprotocol/inspector

Cela démarrera une invite interactive (probablement dans un navigateur) où vous pourrez saisir l'URL de votre serveur MCP et l'inspecter. Étapes pour l'utiliser :

  1. Assurez-vous que votre serveur FastAPI-MCP est en cours d'exécution.
  2. Exécutez l'inspecteur (npx @modelcontextprotocol/inspector).
  3. Lorsque vous y êtes invité, entrez l'URL du point de terminaison MCP (par exemple http://localhost:8000/mcp).
  4. L'inspecteur listera les Outils disponibles. Vous pouvez sélectionner un outil et remplir les paramètres pour tester son appel, puis cliquer sur "Run Tool".
  5. Vous verrez la réponse et pourrez confirmer que tout est correctement connecté.

C'est essentiellement comme une interface utilisateur Swagger mais pour MCP. C'est très utile pour confirmer que vos points de terminaison apparaissent comme prévu et que l'authentification fonctionne (si vous avez défini l'authentification, vous devrez peut-être fournir des en-têtes dans l'inspecteur – il a également des options pour ajouter des en-têtes).

Intégration via Code (LangChain ou Personnalisé)

Et si vous vouliez construire votre propre agent IA en Python qui utilise le serveur MCP ? Bien que vous puissiez utiliser directement un client HTTP pour vous connecter à /mcp et gérer SSE, c'est un peu bas niveau. Des bibliothèques émergent pour aider. Par exemple, le dépôt GitHub fastapi-mcp mentionne un client MCP et des outils pour composer des serveurs. Il existe également un projet appelé FastMCP (jlowin/fastmcp) qui peut construire des clients MCP et même composer plusieurs serveurs MCP.

À l'heure actuelle, ce sont des sujets avancés, mais une approche exemple pourrait être :

  • Utiliser httpx ou requests de Python pour initier une requête GET vers /mcp avec stream=True pour gérer les événements SSE.
  • Analyser l'événement initial "endpoint" pour obtenir la session ou le point de terminaison de contrôle (souvent le protocole implique un message initial avec une URL messages).
  • Envoyer une commande pour lister les outils (la spécification MCP définit un message pour cela) et analyser la réponse.
  • Invoquer un outil spécifique en envoyant la charge utile JSON appropriée comme un événement ou une requête.

Cela dépasse le cadre de ce tutoriel, mais sachez que, puisque MCP est une norme ouverte (il existe une spécification officielle et des SDK), vous pourriez intégrer à ce niveau si nécessaire. Par exemple, une intégration LangChain pourrait traiter le serveur MCP de manière similaire à la façon dont il traite l'appel de fonction OpenAI ou les outils – il faudrait un adaptateur pour traduire un "outil" LangChain en un appel d'outil MCP. Nous pourrions bientôt voir des bibliothèques de première classe pour l'intégration MCP en Python, à mesure que l'écosystème se développe.

Pour l'instant, utiliser les clients IA existants ou l'inspecteur est le moyen le plus simple de travailler avec votre serveur MCP.

Stratégies de Déploiement

Déployer une application FastAPI-MCP est très similaire au déploiement de n'importe quelle application FastAPI. Comme il s'agit simplement d'une application ASGI, vous pouvez utiliser Uvicorn, Hypercorn ou Gunicorn (avec des workers Uvicorn) pour l'exécuter, et la conteneuriser avec Docker si vous le souhaitez. Cependant, gardez à l'esprit les considérations SSE et réseau :

  • Déploiement mono-application : Si vous montez MCP sur la même application FastAPI, vous déploierez un seul service. Assurez-vous que l'environnement peut prendre en charge SSE (la plupart des serveurs ASGI le font – Uvicorn le fait nativement). Si derrière un proxy inverse (comme Nginx), configurez-le pour ne pas mettre en mémoire tampon les flux SSE et pour autoriser les connexions persistantes (keep-alive).
  • Déploiement séparé : Si vous divisez l'API et MCP en services séparés, vous déploierez deux applications. Assurez-vous que le service MCP sait comment atteindre le service API (via base_url ou le réseau interne). Par exemple, vous pourriez déployer votre API principale à api.example.com et le MCP à mcp.example.com, avec l'URL de base http_client du MCP définie sur https://api.example.com. Ils pourraient également communiquer via une adresse interne s'ils sont colocalisés.

Exemple (Déploiement Séparé avec Docker Compose) : Vous pourriez avoir deux conteneurs, un pour l'API et un pour MCP. Le conteneur MCP pourrait avoir une variable d'environnement pour l'URL de l'API. Utiliser FastApiMCP(app, http_client=httpx.AsyncClient(base_url=os.getenv("API_URL"))) dirigerait les appels vers le service API. De cette façon, le conteneur MCP n'a pas besoin d'importer le code de l'API – il pourrait même appeler un service complètement différent tant qu'il a une OpenAPI compatible (bien que typiquement vous importeriez simplement la même application FastAPI comme nous l'avons montré plus tôt).

Mise à l'échelle : Si votre API est lourde et que vous ne prévoyez qu'une utilisation modérée de MCP (ou vice versa), vous pouvez les mettre à l'échelle indépendamment. Par exemple, exécutez plusieurs répliques de l'API derrière un équilibreur de charge, et peut-être qu'une ou deux instances de serveur MCP suffisent pour l'utilisation par l'IA. Comme MCP utilise le streaming, vous pourriez ne pas mettre d'équilibreur de charge devant le MCP (pour éviter de casser SSE), ou utiliser une stratégie de connexion persistante (sticky connection).

HTTPS et Réseau : Si le client IA se connectera depuis un service externe (disons, un IDE en ligne ou un agent s'exécutant dans le cloud), vous devrez servir votre point de terminaison MCP via HTTPS (pour la sécurité, et parce que de nombreux clients peuvent l'exiger). Cela signifie généralement le placer derrière un proxy de terminaison SSL ou utiliser un service cloud. Il n'y a rien de spécifique à MCP à ce sujet – traitez-le comme l'exposition d'un point de terminaison API. Utilisez TLS approprié, des noms de domaine, etc. Si votre MCP est destiné à un usage interne uniquement, vous pourriez ne pas l'exposer publiquement du tout.

Rafraîchissement et Mises à Jour : Si vous mettez à jour votre API avec de nouveaux points de terminaison, n'oubliez pas de redéployer ou de rafraîchir le service MCP afin qu'il soit au courant des nouveaux points de terminaison. Si le service MCP est de longue durée, un redémarrage progressif (rolling restart) ou l'appel de setup_server() (peut-être déclenché par un script de déploiement) pourrait être utilisé pour prendre en compte les changements.

En résumé, déployez FastAPI-MCP comme vous le feriez pour un microservice FastAPI. La principale différence est de s'assurer que SSE fonctionne de bout en bout et de planifier s'il fait partie de votre application principale ou d'un service autonome. La documentation officielle a un exemple simple montrant des processus uvicorn séparés sur différents ports, mais vous pouvez l'adapter à n'importe quelle infrastructure.

Tests et Dépannage

Tester une configuration FastAPI-MCP implique à la fois de vérifier le comportement traditionnel de l'API et la nouvelle interface MCP. Voici quelques stratégies :

Tester les Points de Terminaison de l'API

Premièrement, continuez à écrire des tests pour vos points de terminaison FastAPI comme d'habitude (en utilisant TestClient de FastAPI ou des appels HTTP). FastAPI-MCP ne change pas la logique de vos points de terminaison, donc les tests unitaires et d'intégration pour eux restent valides. S'assurer que chaque point de terminaison retourne les données attendues pour des entrées données garantira indirectement que la sortie MCP est également correcte.

Tester l'Interface MCP

Pour tester spécifiquement la couche MCP, vous pouvez simuler un client MCP. Comme mentionné, l'outil Inspecteur MCP est excellent pour les tests manuels – c'est comme un client de test interactif. Utilisez-le pendant le développement pour vous assurer que tous vos outils sont listés et fonctionnent :

  • Exécutez votre application, connectez l'inspecteur, listez les outils. Si quelque chose devrait être là et ne l'est pas, vérifiez les IDs d'opération et si vous avez appelé mount() après avoir défini ces routes.
  • Utilisez l'inspecteur pour appeler chaque outil avec des entrées valides et invalides. Par exemple, testez un paramètre requis manquant et voyez qu'il retourne une erreur de validation (tout comme votre API le ferait via la validation de FastAPI). L'inspecteur affichera la réponse d'erreur.

Pour les tests automatisés, vous pourriez écrire un petit test qui utilise le client SSE de Python ou les websockets pour se connecter à /mcp. Python n'a pas de support SSE intégré, mais vous pourriez utiliser httpx avec un analyseur d'event-stream. Cependant, cela peut devenir compliqué. Une autre approche consiste à exécuter une commande comme npx @modelcontextprotocol/inspector ou mcp-remote dans un environnement de test pour garantir que la connexion fonctionne (bien que cela sorte des tests purement Python).

Si vos points de terminaison sont simples, une vérification pragmatique consiste à voir que GET http://localhost:8000/mcp retourne un 200 et produit un flux d'événements (vous pourriez analyser le premier événement). Par exemple :

from fastapi.testclient import TestClient

client = TestClient(app)
response = client.get("/mcp", stream=True)
assert response.status_code == 200
chunks = []
for chunk in response.iter_content(chunk_size=None):
    chunks.append(chunk.decode())
    if b"event: " in chunk:
        break
stream_output = "".join(chunks)
assert "event: endpoint" in stream_output or "event: tool_list" in stream_output

C'est un peu bricolé mais cela vérifie que le point de terminaison MCP produit un événement. Un test plus approfondi simulerait un client MCP et effectuerait la commande de listage des outils.

Conseils de Dépannage

  • « Aucun outil MCP disponible » : Si le client IA dit qu'il n'a trouvé aucun outil, il est probable que le serveur MCP n'ait enregistré aucun point de terminaison. Assurez-vous que FastApiMCP(app) a été appelé après la configuration des routes (ou appelez setup_server() pour rafraîchir). Assurez-vous également de ne pas avoir tout filtré par accident avec les paramètres d'inclusion/exclusion.
  • Problèmes d'authentification : Si vous protégez le MCP avec l'authentification, et que le client IA ne peut pas se connecter, vérifiez que le client envoie l'en-tête ou le jeton. Vous pourriez tester en utilisant curl avec l'en-tête pour voir si vous obtenez un 200 OK sur /mcp. Exemple : curl -N http://localhost:8000/mcp -H "X-API-Key: mysecret123" (le -N sert à ne pas mettre en mémoire tampon la sortie, afin que vous voyiez SSE). Si cela fonctionne, alors le problème est la configuration du client.
  • La connexion SSE se ferme immédiatement : Cela pourrait se produire si une erreur survient lors de la connexion. Vérifiez les journaux de votre serveur ; si votre dépendance d'authentification a levé une erreur en raison d'un jeton manquant, la connexion pourrait chuter. Ou si une exception est levée pendant le listage des outils. Les journaux indiqueront généralement la cause.
  • L'appel d'outil ne fonctionne pas : Si une IA dit qu'elle a essayé d'utiliser un outil mais a obtenu une erreur, traitez cela comme une erreur d'appel API. Par exemple, l'IA pourrait fournir une chaîne là où un entier est attendu, provoquant une erreur de validation 422. Ces erreurs sont renvoyées via MCP sous forme d'événements – vérifiez les journaux ou utilisez l'inspecteur pour répliquer l'appel. Vous devrez peut-être ajuster vos descriptions pour que l'IA connaisse les types corrects.
  • Performance : Si les appels sont lents, rappelez-vous qu'avec SSE la connexion reste ouverte. Assurez-vous de ne pas faire quelque chose comme lire le corps de la requête d'une manière qui bloque. Ce n'est généralement pas un problème, mais si vous utilisez des réponses en streaming, assurez-vous de produire les données correctement. Pour un débit élevé, envisagez la mise à l'échelle horizontale.
  • Incompatibilités de spécification MCP : Comme MCP évolue, il pourrait y avoir de légères différences de version entre les clients et le serveur. FastAPI-MCP vise à être à jour avec la spécification. Si vous rencontrez une incompatibilité avec un client particulier, consultez les notes de version de FastAPI-MCP. Une solution de contournement peut souvent être d'utiliser mcp-remote car il tend à normaliser la communication.

En testant méthodiquement à la fois l'API et l'interface MCP, vous pouvez être confiant dans votre déploiement. Il est conseillé de tester avec le client IA réel que vous prévoyez d'utiliser (par exemple, si votre cible est les utilisateurs de Cursor IDE, testez avec Cursor ; si c'est Claude Desktop, testez via Claude avec mcp-remote).

Exemples Réels et Cas d'Utilisation

FastAPI-MCP ouvre de nombreuses possibilités pour intégrer des API avec l'IA. Voici quelques scénarios pour illustrer des applications pratiques :

  • Assistant de Documentation Alimenté par l'IA : Exposez vos points de terminaison API publics via MCP afin qu'un assistant IA puisse aider les utilisateurs à explorer l'API. Par exemple, un utilisateur pourrait demander « Comment créer un nouvel utilisateur avec cette API ? » et l'IA (ayant accès aux outils MCP) pourrait trouver le point de terminaison create_user et même exécuter des appels exemples. Cela fournit une expérience de documentation interactive alimentée par l'IA.

  • Assistant Développeur Interne : Au sein d'une entreprise, les développeurs pourraient avoir un agent IA (dans VSCode ou Slack) connecté aux microservices internes via MCP. Ils pourraient interroger des données (en lecture seule) ou effectuer des opérations de routine en instruisant l'IA en langage naturel. Par exemple, « IA, donne-moi les derniers journaux d'erreurs du service de surveillance » – l'IA appelle l'API interne appropriée et retourne les résultats. Cela peut augmenter la productivité en déchargeant les requêtes simples à l'IA.

  • Automatisation Multi-systèmes : Imaginez une IA orchestrant des tâches impliquant plusieurs systèmes – par exemple, un flux de travail IA qui prend un ticket de support, recherche les informations utilisateur d'un service et les informations produit d'un autre, puis crée une entrée dans une base de données. Si chacun de ces services a une interface MCP, l'IA peut passer de manière transparente entre eux en utilisant des appels standardisés, sans code d'intégration personnalisé pour chaque système. MCP fournit le liant pour l'automatisation inter-systèmes par l'IA.

  • API en Langage Naturel pour les Utilisateurs Finaux : Vous pourriez même exposer certains outils aux utilisateurs finaux via un chatbot IA. Par exemple, un site de vente au détail pourrait avoir un chatbot où l'utilisateur demande « Où est ma commande avec l'ID 12345 ? » L'agent IA backend utilise MCP pour appeler l'API de suivi de commande (get_order_status) puis répond à l'utilisateur avec les informations. FastAPI-MCP dans ce cas permet à l'IA d'utiliser la même API que l'application mobile ou le site web pourrait utiliser, mais via une interaction en langage naturel.

  • Prototype de Plugin IA : Si vous envisagiez de construire un Plugin OpenAI pour votre API, implémenter FastAPI-MCP atteint un objectif similaire mais avec une norme ouverte qui peut fonctionner avec plusieurs fournisseurs d'IA. Par exemple, Anthropic, OpenAI et d'autres s'alignent sur MCP. Vous bénéficiez d'une implémentation unique qui fonctionne sur de nombreux clients IA.

Ce ne sont là que quelques idées. Le principal enseignement est que FastAPI-MCP permet à votre API d'être facilement intégrée dans les flux de travail IA avec un effort minimal. Vous vous concentrez sur l'écriture de la logique API ; FastAPI-MCP la rend consommable par l'IA.

Récapitulatif des Meilleures Pratiques

Pour assurer le succès lors de l'utilisation de FastAPI-MCP, gardez à l'esprit les meilleures pratiques suivantes (certaines que nous avons abordées plus tôt) :

  • Donnez des noms clairs aux outils : Définissez toujours operation_id avec un nom descriptif pour chaque point de terminaison. Cela aide l'IA (et les humains) à comprendre ce que fait l'outil (par exemple update_user_password vs un nom par défaut vague). Utilisez lower_case ou lowerCamelCase par convention, et faites correspondre les noms aux actions.

  • Documentez bien vos points de terminaison : Plus il y a de détails dans votre documentation FastAPI (descriptions, exemples, docstrings de modèle de réponse), plus l'IA a de contexte. Incluez des valeurs d'exemple pour les paramètres si possible. FastAPI-MCP reportera ces descriptions dans les informations de l'outil MCP.

  • Validez et assainissez minutieusement : Attendez-vous à ce que l'IA appelle parfois vos outils avec des paramètres incorrects ou de manière inattendue. Assurez-vous que vos validateurs FastAPI (modèles Pydantic, vérifications de type) sont en place pour les attraper et retourner des erreurs appropriées. Assurez-vous également que les réponses ne divulguent pas accidentellement des données – par exemple, si votre modèle inclut un champ qui devrait être caché, utilisez response_model_exclude ou similaire.

  • Commencez de manière restrictive, puis ouvrez prudemment : Surtout au début, il pourrait être sage d'exposer un ensemble limité de points de terminaison à l'IA jusqu'à ce que vous voyiez comment elle les utilise. Vous pouvez inclure seulement quelques opérations sûres en lecture seule et tâter le terrain. Avec le temps, si nécessaire, vous pouvez en exposer davantage. Cela limite les risques.

  • Surveillez l'utilisation par l'IA : Activez la journalisation pour les appels MCP. Vous pourriez ajouter un middleware ou simplement surveiller les journaux du serveur (qui montreront les requêtes vers /mcp et éventuellement les points de terminaison sous-jacents). En surveillant, vous pouvez identifier si l'IA a des difficultés (par exemple, appeler un point de terminaison à plusieurs reprises sans succès) et ensuite améliorer soit vos instructions, soit la conception du point de terminaison. Cela aide également à détecter les abus.

  • Restez à jour avec les changements de spécification MCP : MCP évolue (le lien de spécification fourni montre une version datée). FastAPI-MCP se mettra probablement à jour pour se conformer aux nouvelles versions. Gardez un œil sur le GitHub de FastAPI-MCP pour les versions, et mettez à jour votre package périodiquement pour obtenir des améliorations et des corrections de bugs.

En suivant ces pratiques, vous vous assurez que l'intégration de l'IA ne compromet pas l'intégrité ou la sécurité de votre API, et que l'IA peut tirer le meilleur parti des fonctionnalités de votre API.

Conclusion

FastAPI-MCP fournit un moyen puissant mais facile de transformer n'importe quelle application FastAPI en un service prêt pour l'IA. Dans ce tutoriel, nous sommes partis des concepts de base et avons progressé vers des sujets avancés. Récapitulons rapidement le parcours :

  1. Nous avons appris ce qu'est MCP – un protocole standard pour la communication IA-outil, comparé à donner à l'IA un connecteur universel pour utiliser des API externes. FastAPI-MCP implémente cela pour FastAPI, ne nécessitant que quelques lignes de code pour la configuration.
  2. Nous avons suivi un démarrage rapide – installation du package, montage sur une application FastAPI, et vérification que le point de terminaison MCP est actif. Avec un code minimal, nos points de terminaison API sont devenus des outils MCP découvrables.
  3. Nous avons discuté de la structure du projet – comment intégrer dans une seule application ou diviser en services API et MCP pour plus de flexibilité. Planifier votre déploiement tôt aide à éviter le refactoring plus tard.
  4. Nous avons exploré la personnalisation – nommer les outils via operation_id, ajouter des informations de schéma détaillées, et filtrer quels points de terminaison sont exposés pour maintenir le contrôle.
  5. Nous avons abordé la sécurité via l'injection de dépendances – utiliser Depends() pour exiger des jetons d'authentification ou des clés API pour les appels MCP, et même activer les flux OAuth pour des scénarios avancés. Nous avons souligné l'utilisation des utilitaires de sécurité existants de FastAPI pour garder l'interface MCP sûre.
  6. Nous avons intégré avec des clients IA – démontrant comment un IDE IA peut se connecter via SSE ou via un proxy mcp-remote. Nous avons vu qu'une IA peut alors appeler des fonctions API en langage naturel, faisant effectivement de votre application une partie de la boîte à outils de l'IA.
  7. Nous avons couvert le déploiement – soulignant que vous déployez les applications FastAPI-MCP un peu comme n'importe quelle application FastAPI, avec une attention particulière à SSE et éventuellement à une mise à l'échelle séparée. La conteneurisation et le déploiement cloud fonctionnent de manière transparente, permettant une utilisation réelle de votre service MCP.
  8. Nous avons passé en revue les tests et le dépannage – utiliser des outils comme l'Inspecteur MCP pour valider votre configuration, et noter les pièges courants (comme oublier de mettre à jour la liste des outils ou les incompatibilités d'authentification).
  9. Nous avons examiné des cas d'utilisation réels – des assistants de documentation à l'automatisation multi-systèmes, illustrant la polyvalence de l'exposition d'une API à l'IA.
  10. Enfin, nous avons résumé les meilleures pratiques pour assurer une opération fluide et sécurisée lorsque les humains et l'IA commencent à consommer votre API en tandem.

En suivant ce guide, vous devriez être bien équipé pour implémenter FastAPI-MCP dans vos projets. Vous pouvez créer des applications riches, intégrées à l'IA, qui tirent parti de la puissance des grands modèles de langage pour interagir avec vos services FastAPI de manière intelligente. À mesure que l'écosystème MCP se développe (avec plus de clients et de serveurs émergeant), vous êtes déjà à la pointe avec une API qui parle le langage de l'IA.

Prochaines Étapes : Expérimentez avec votre propre configuration API + MCP. Essayez de connecter différents clients IA (Cursor, VSCode, etc.) et voyez comment l'IA utilise vos outils. Rejoignez la communauté FastAPI-MCP (le Slack "MCParty") si vous avez des questions ou des idées – étant un projet open-source, les contributions et les retours sont les bienvenus. Bon codage, et bienvenue dans la prochaine génération d'applications alimentées par l'IA !

Références

Conseil : Le dépôt fastapi-mcp et la spécification MCP évoluent rapidement—vérifiez souvent ces sources pour rester à jour.

Vous avez apprécié cet article ? Vous l'avez trouvé instructif ? N'hésitez pas à laisser un commentaire ci-dessous pour partager vos réflexions ou poser des questions. Un compte GitHub est requis pour participer à la discussion.

PARTAGER