Créer un serveur MCP Python est aujourd’hui l’un des moyens les plus rapides de rendre une connaissance interne accessible à un assistant IA. Les runbooks d’exploitation s’y prêtent particulièrement bien : ils sont écrits, structurés, souvent dispersés dans un wiki ou un dépôt Git, et précieux au moment précis où personne n’a le temps de les chercher.
L’objectif de ce tutoriel est modeste et volontairement prudent : exposer des runbooks en lecture seule, permettre à l’assistant de les rechercher et de les lire, et proposer un prompt d’investigation réutilisable. Aucune action n’est exécutée sur la production. C’est le bon point de départ avant d’envisager des outils qui agissent.
Nous utilisons le SDK Python officiel du Model Context Protocol. Son API a changé avec la version 2 (la classe FastMCP de la v1 s’appelle désormais MCPServer) : si vous suivez un tutoriel plus ancien, adaptez les imports.
Pourquoi créer un serveur MCP Python pour vos runbooks ?
Un serveur MCP expose trois types de capacités : des outils, des ressources et des prompts (notre guide du Model Context Protocol les détaille). Les runbooks se répartissent naturellement entre les trois :
- chaque runbook devient une ressource, adressée par une URI comme
runbook://redemarrage-api; - la recherche par mot-clé devient un outil, que le modèle appelle quand il cherche une procédure ;
- la démarche d’investigation devient un prompt, que l’utilisateur déclenche explicitement.
L’intérêt par rapport à un simple copier-coller dans la conversation : la source reste unique, à jour, versionnée, et l’assistant ne lit que ce dont il a besoin.
Préparer l’environnement
Le SDK requiert Python 3.10 ou plus récent. Il s’installe depuis PyPI sous le nom mcp ; l’extra cli ajoute la commande mcp, utile pour tester :
python3 -m venv .venv
. .venv/bin/activate
pip install "mcp[cli]"
Le projet recommande aussi uv pour gérer l’environnement. Reportez-vous à la documentation du SDK Python pour la méthode à jour.
Côté contenu, supposons un répertoire de fichiers Markdown, un par runbook :
/opt/runbooks/
redemarrage-api.md
saturation-disque.md
certificat-expire.md
En pratique
Étape 1 — Déclarer le serveur et les ressources
Le serveur tient dans un seul fichier. On commence par l’objet serveur et une ressource paramétrée qui lit un runbook par son nom. La fonction n’est appelée que lorsqu’un client lit effectivement la ressource.
import logging
import os
import re
from pathlib import Path
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ResourceNotFoundError, ToolError
from mcp.types import ToolAnnotations
RUNBOOKS_DIR = Path(os.environ.get("RUNBOOKS_DIR", "/opt/runbooks")).resolve()
NOM_VALIDE = re.compile(r"^[a-z0-9-]{1,64}$")
log = logging.getLogger("runbooks")
mcp = MCPServer("runbooks-ops")
def chemin_runbook(nom: str) -> Path:
"""Valide le nom et empêche toute sortie du répertoire."""
if not NOM_VALIDE.match(nom):
raise ResourceNotFoundError("Nom de runbook invalide.")
chemin = (RUNBOOKS_DIR / f"{nom}.md").resolve()
if chemin.parent != RUNBOOKS_DIR or not chemin.is_file():
raise ResourceNotFoundError(f"Runbook introuvable : {nom}")
return chemin
@mcp.resource("runbook://{nom}")
def lire_runbook(nom: str) -> str:
"""Contenu complet d'un runbook d'exploitation."""
return chemin_runbook(nom).read_text(encoding="utf-8")
Deux détails comptent. La validation du nom par expression régulière, puis la vérification du chemin résolu, bloquent les tentatives du type ../../etc/passwd. Et les messages d’erreur restent sobres : ils ne révèlent pas l’arborescence du serveur.
Étape 2 — Ajouter un outil de recherche
Le modèle ne connaît pas vos noms de fichiers. Un outil de recherche lui permet de trouver le bon runbook à partir d’un symptôme :
@mcp.tool(annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False))
def chercher_runbooks(mots_cles: str) -> list[str]:
"""Cherche les runbooks dont le contenu contient tous les mots-clés.
Renvoie au plus 10 noms, à lire ensuite via runbook://{nom}."""
termes = [t.lower() for t in mots_cles.split()][:5]
if not termes:
raise ToolError("Indiquez au moins un mot-clé.")
resultats = []
for fichier in sorted(RUNBOOKS_DIR.glob("*.md")):
texte = fichier.read_text(encoding="utf-8").lower()
if all(t in texte for t in termes):
resultats.append(fichier.stem)
log.info("recherche %s : %d résultat(s)", termes, len(resultats))
return resultats[:10]
La docstring n’est pas décorative : c’est la description que lit le modèle pour décider quand appeler l’outil. Les annotations signalent au client que l’outil ne modifie rien, mais ce ne sont que des indications ; la sécurité repose sur le code lui-même.
Étape 3 — Proposer un prompt d’investigation
Un prompt guide l’utilisateur vers une démarche cohérente :
@mcp.prompt()
def investiguer(symptome: str) -> str:
"""Démarrer une investigation à partir d'un symptôme."""
return (
f"Symptôme observé : {symptome}\n"
"1. Cherche les runbooks pertinents avec chercher_runbooks.\n"
"2. Lis le plus adapté et résume les vérifications à faire.\n"
"3. Ne propose aucune action destructive sans validation explicite."
)
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO)
mcp.run()
Sans argument, mcp.run() utilise le transport stdio. La sortie standard sert alors au protocole : passez par le module logging, qui écrit sur la sortie d’erreur, plutôt que par des print().
Étape 4 — Tester avec l’Inspector
La commande fournie par l’extra cli lance le serveur sous MCP Inspector, une interface web de test (elle nécessite Node.js) :
mcp dev serveur_runbooks.py
Testez la recherche avec des mots-clés réels, lisez une ressource, puis essayez volontairement des noms invalides pour vérifier les refus.
Étape 5 — Déclarer le serveur dans votre assistant
La plupart des hôtes acceptent une commande de lancement dans leur configuration. Utilisez le Python de l’environnement virtuel pour être sûr d’avoir les bonnes dépendances :
{
"mcpServers": {
"runbooks": {
"command": "/opt/runbooks-mcp/.venv/bin/python",
"args": ["/opt/runbooks-mcp/serveur_runbooks.py"],
"env": { "RUNBOOKS_DIR": "/opt/runbooks" }
}
}
}
Pour un serveur partagé par l’équipe, le SDK sait aussi servir en HTTP avec mcp.run(transport="streamable-http"), qui écoute par défaut sur l’interface locale. Avant de l’ouvrir au réseau, ajoutez une authentification et relisez notre guide pour sécuriser un serveur MCP.
Bonnes pratiques
- Commencer en lecture seule ; ajouter des outils d’action seulement avec validation humaine.
- Valider chaque argument côté serveur : listes autorisées, longueurs, formats.
- Rédiger des docstrings précises : elles guident le choix du modèle.
- Lever une erreur d’outil explicite plutôt que renvoyer un texte d’erreur comme s’il s’agissait d’un résultat.
- Journaliser sur la sortie d’erreur, jamais sur la sortie standard en stdio.
- Versionner les runbooks dans Git et les relire comme du code : ils deviennent des instructions lues par un agent.
Questions fréquentes
Faut-il utiliser FastMCP ou MCPServer ?
Dans le SDK officiel en version 2, FastMCP a été renommé MCPServer. Le guide de migration du SDK détaille la correspondance des imports.
Mon serveur est-il observable ?
Le SDK v2 émet des spans OpenTelemetry pour chaque message traité ; il suffit d’installer un SDK et un exportateur. Voir observer les agents MCP avec OpenTelemetry.
Puis-je relier ce serveur à mes incidents ?
Oui, en combinant ses runbooks avec un serveur d’observabilité dans le même assistant. Nos fiches comme les incidents courants d’un cluster Managed sont d’ailleurs de bons candidats à transformer en runbooks.
Conclusion
Créer un serveur MCP en Python demande peu de code ; le soin se porte ailleurs : validation des entrées, descriptions claires, erreurs explicites et périmètre en lecture seule. Ce petit serveur de runbooks offre déjà une vraie valeur pendant les astreintes, et constitue une base saine pour aller plus loin.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.
2 comments