Créer un serveur MCP en Python

Introduction

Un serveur mcp python devient pertinent quand vous voulez exposer le même catalogue d’outils à plusieurs clients compatibles sans recoder une intégration par application. Pour un builder, c’est utile dès qu’un script interne, une base documentaire ou une API métier doit être réutilisé proprement par un agent, un IDE ou un runtime. En revanche, si vous n’avez qu’un seul workflow local avec deux fonctions maison, ce n’est probablement pas le bon choix : restez sur une approche plus simple. Ce tutoriel montre comment monter un serveur minimal, le tester, puis cadrer sécurité, logs et maintenance.

Résumé rapide

1. Initialisez un projet Python propre puis ajoutez le SDK MCP avant d’écrire votre premier serveur.
2. Déclarez peu de tools au départ, avec des schémas d’entrée clairs et des permissions explicites.
3. Testez le serveur avec un client compatible pour vérifier la découverte des tools et les erreurs.
4. Ajoutez immédiatement logs, limites d’accès et règles d’exposition réseau si le serveur sort du poste local.

Serveur MCP, contrat et différence avec une API REST seule

Le model context protocol n’est pas une API métier de plus. C’est une façon standard de décrire des capacités pour qu’un client sache quelles ressources il peut lire, quels tools il peut appeler et avec quels paramètres. Si vous avez déjà lu Model Context Protocol : guide builders, voyez ce tutoriel comme l’étape suivante : on passe du cadre conceptuel à une implémentation exploitable.

Le bon repère simple est le suivant : une API REST expose des endpoints, alors qu’un serveur MCP expose un contrat orienté usage par agent. Le client ne consomme pas seulement une URL ; il découvre un catalogue de capacités, leur description, leurs arguments et leur forme de réponse. C’est utile quand plusieurs clients doivent partager le même outillage sans dupliquer toute la colle de découverte et d’appel.

Sujet	Serveur MCP	API REST seule
Découverte des capacités	Native côté client compatible	À documenter et mapper soi-même
Description des tools	Intégrée au protocole	Souvent externe à l’API
Réutilisation multi-clients	Forte	Variable selon l’intégration
Coût de départ	Plus élevé	Plus faible
Bon cas d’usage	Catalogue d’outils réutilisable	Service simple consommé par une seule app

Le but n’est pas de remplacer toutes vos APIs internes. Un serveur MCP sert surtout d’adaptateur propre pour rendre des capacités réutilisables. Si votre besoin ressemble davantage à un appel HTTP ponctuel depuis un agent unique, le tool calling ou une intégration directe peut suffire. MCP devient intéressant quand vous voulez stabiliser l’interface entre clients et outils, pas quand vous cherchez juste à ajouter une fonction de plus.

Créer un serveur MCP minimal en Python

Commencez par un périmètre très petit. Un premier serveur doit prouver trois choses : qu’un client peut découvrir vos tools, qu’il peut les appeler avec des paramètres simples, et que vous savez contrôler ce qui est réellement exposé. Cette logique évite de transformer un sujet de protocole en chantier d’architecture.

1. Préparer le projet

Prérequis recommandés : Python 3 récent, un environnement virtuel, et une capacité à lancer des commandes locales. Si vous gérez déjà vos projets avec uv, gardez la même chaîne pour rester cohérent avec vos autres outils Python.

uv init mcp-demo
cd mcp-demo
uv venv
source .venv/bin/activate
uv add "mcp[cli]<2"

L’idée n’est pas d’empiler des dépendances. Vous avez besoin du SDK, puis d’un serveur assez petit pour rester lisible. Si votre objectif final est de brancher une API externe, gardez aussi sous la main notre guide OpenClaw API skills : connecter une API externe, utile pour penser auth, timeouts et validation des réponses.

2. Écrire un serveur minimal

Voici un exemple simple avec un tool de recherche interne et une ressource de configuration. Il reste volontairement petit : un seul tool métier, une seule ressource, et une sortie JSON facile à tester.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("ops-catalog", json_response=True)

KB = {
    "mcp": "Le protocole standardise la découverte et l'appel d'outils.",
    "logs": "Un log structuré doit inclure run_id, tool, durée et statut.",
    "retry": "Un retry sans limite masque souvent une mauvaise conception."
}

@mcp.tool()
def search_kb(query: str) -> dict:
    matches = [
        {"topic": topic, "content": content}
        for topic, content in KB.items()
        if query.lower() in topic.lower() or query.lower() in content.lower()
    ]
    return {"query": query, "matches": matches[:5]}

@mcp.resource("config://ops")
def ops_config() -> str:
    return "logs=enabled;auth=required;network=private"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Ce guide défend une idée simple : votre premier serveur ne doit pas être “puissant”, il doit être contrôlable. Un tool bien nommé, avec un schéma d’entrée évident, vaut mieux que dix actions floues. Le client doit comprendre immédiatement à quoi sert search_kb, quelles données il reçoit et dans quel cadre l’utiliser.

3. Structurer les tools comme un catalogue de capacités

Un serveur MCP utile n’expose pas votre backend entier. Il expose des capacités bien découpées. En pratique, chaque tool devrait répondre à une action métier précise : rechercher un document, lancer une synchronisation, lire une configuration, créer un ticket, interroger un stock. Si vous donnez au client un wrapper générique vers tout votre système, vous gagnez en vitesse au départ mais vous perdez en contrôle, en observabilité et en sécurité.

Pensez vos tools comme des contrats publics, même si le serveur reste interne. Cela implique :

• un nom explicite ;
• des arguments limités et typés ;
• une description utile pour le client ;
• une sortie stable ;
• des erreurs compréhensibles.

À ce stade, ne mélangez pas encore plusieurs transports, ni plusieurs permissions par profil. Le bon ordre est : rendre un tool fiable, vérifier qu’il est découvert, puis ajouter la complexité nécessaire. C’est la même discipline que pour créer un agent IA : d’abord une boucle simple qui marche, ensuite l’orchestration.

4. Tester avec un client compatible

Le test minimum n’est pas “le process démarre”. Le vrai signal, c’est qu’un client compatible découvre les capacités annoncées puis appelle un tool avec les bons arguments. Si vous utilisez un runtime agent ou un poste outillé comme Hermes Agent : guide pour builders IA, le comportement à observer est simple : le client doit voir le nom du serveur, lister les tools disponibles, puis remonter un résultat ou une erreur exploitable.

Votre checklist de validation initiale :

1. le serveur démarre sans stacktrace ;
2. le client voit le tool search_kb ;
3. un appel avec query="logs" retourne une structure stable ;
4. un appel invalide produit une erreur lisible ;
5. les logs permettent de relier la requête, le tool et le statut.

Cette partie paraît triviale, mais c’est souvent là que le design d’un serveur se joue. Si vos logs ne permettent pas de relier un appel à un run_id, si vos erreurs se réduisent à 500, ou si un tool peut tout faire selon une chaîne libre, vous aurez un serveur “compatible” mais difficile à maintenir.

5. Préparer la montée en charge raisonnable

Avant d’ajouter un deuxième client, posez déjà les limites d’exploitation. Qui a le droit d’appeler quels tools ? Le serveur reste-t-il local, passe-t-il par un tunnel privé, ou devient-il accessible sur le réseau ? Quelle volumétrie accepte-t-il ? Comment évitez-vous qu’un outil lent bloque les autres appels ?

La réalité production commence ici, pas au moment du déploiement. Si votre serveur doit sortir du laptop, documentez dès maintenant :

• le mode d’authentification ;
• les permissions par tool ;
• les timeouts ;
• les retries acceptables ;
• la journalisation minimale ;
• les secrets nécessaires ;
• les conditions de rollback.

Vous pourrez ensuite l’industrialiser plus proprement via un guide comme Déployer un agent IA en production, mais sans ce cadrage initial vous transformerez vite un adaptateur utile en surface d’attaque ou en goulot de maintenance.

Exemple concret : exposer un outil interne de veille

Prenons un cas réaliste : une équipe contenu ou produit possède déjà un script Python qui interroge une base documentaire interne pour récupérer des notes sur un framework, un incident ou une release. Tant que ce script reste local, il n’est réutilisable que par la personne qui le lance. En l’exposant via un serveur MCP, vous transformez ce script en capacité partagée pour plusieurs clients compatibles.

Le flux reste simple. Le client demande une recherche sur langgraph observabilité. Le serveur appelle search_kb, renvoie une liste bornée de résultats, puis le client décide quoi en faire : afficher la synthèse, enrichir un article, comparer une stack ou déclencher un autre tool. Vous ne rendez pas votre système “plus intelligent” par magie ; vous rendez surtout l’outillage plus composable.

Le bon pattern business est là : un outil interne isolé devient un actif réutilisable. C’est particulièrement utile pour la veille, les catalogues de procédures, les checklists de support, ou des recherches documentaires répétitives. En revanche, si votre besoin se limite à une seule intégration ponctuelle, garder une API interne ou même une fonction Python directe restera souvent plus rapide et moins coûteux à maintenir.

Bonnes pratiques

Commencez par peu de tools, puis élargissez. Un serveur MCP trop large devient vite opaque pour les clients et dangereux pour l’équipe. La meilleure première version est souvent un mini-catalogue de 1 à 3 capacités très propres.

Mini-checklist de départ :

• exigez une auth claire avant toute exposition réseau ;
• définissez des permissions par tool au lieu d’un accès global ;
• logguez le run_id, le nom du tool, la durée et le statut ;
• fixez des timeouts et des retries courts ;
• masquez les secrets dans les logs et dans les erreurs ;
• gardez un plan de rollback vers une intégration plus simple.

Restez sobre sur l’architecture. Si vous commencez à empiler discovery, auth, proxy, cache, retries et orchestration multi-clients avant d’avoir un cas d’usage validé, MCP devient vite overkill. Le bon choix est celui qui réduit la colle et la maintenance, pas celui qui ajoute un protocole par principe.

Questions fréquentes

Comment créer un serveur MCP en Python rapidement ?

Le plus simple est de partir d’un projet Python isolé, d’ajouter le SDK MCP, puis d’exposer un ou deux tools métier très précis. Évitez de brancher toute votre API interne d’un coup. Le bon objectif initial est de vérifier la découverte des tools, la qualité des erreurs et la lisibilité des logs.

MCP remplace-t-il une API REST ?

Non. MCP ne remplace pas forcément votre API métier. Il ajoute surtout une couche de contrat standard pour des clients compatibles qui doivent découvrir et appeler des capacités réutilisables. Si une seule application consomme déjà votre service sans friction, une API REST seule peut rester suffisante.

Quel premier cas d’usage choisir pour un serveur MCP ?

Choisissez un outil interne déjà utile et peu risqué : recherche documentaire, lecture de configuration, catalogue de procédures, ou consultation bornée d’une base métier. Ce type de capacité permet de valider permissions, logs et maintenance sans exposer immédiatement des actions sensibles comme l’écriture ou la suppression.

Comment sécuriser un serveur MCP en production ?

Commencez par l’authentification, les permissions par tool, les timeouts et la journalisation structurée. Ajoutez ensuite l’exposition réseau minimale, la rotation des secrets et des règles de rollback. Le piège classique consiste à rendre le protocole propre mais le serveur lui-même trop permissif ou trop bavard dans ses logs.

Articles liés

Si votre besoin est de standardiser un petit catalogue d’outils réutilisables, MCP est un bon choix. Si vous cherchez seulement un appel de fonction ponctuel, restez sur une approche plus simple. Et si vous voulez le cadre global avant d’industrialiser, commencez par notre guide MCP avant ce tuto : Model Context Protocol : guide builders.

• Model Context Protocol : guide builders
• Tool calling agent IA : guide pratique
• OpenClaw API skills : connecter une API externe
• Déployer un agent IA en production
• Hermes Agent : guide pour builders IA