Crear un servidor MCP en Python es hoy una de las formas más rápidas de hacer accesible un conocimiento interno a un asistente de IA. Los runbooks de operación se prestan especialmente bien: están escritos, estructurados, a menudo dispersos en un wiki o en un repositorio Git, y son valiosos justo en el momento en que nadie tiene tiempo de buscarlos.
El objetivo de este tutorial es modesto y deliberadamente prudente: exponer runbooks en solo lectura, permitir que el asistente los busque y los lea, y ofrecer un prompt de investigación reutilizable. No se ejecuta ninguna acción en producción. Es el buen punto de partida antes de plantearse herramientas que actúan.
Usamos el SDK oficial de Python del Model Context Protocol. Su API cambió con la versión 2 (la clase FastMCP de la v1 se llama ahora MCPServer): si sigues un tutorial más antiguo, adapta los imports.
¿Por qué crear un servidor MCP en Python para tus runbooks?
Un servidor MCP expone tres tipos de capacidades: herramientas, recursos y prompts (nuestra guía del Model Context Protocol las detalla). Los runbooks se reparten de forma natural entre los tres:
- cada runbook se convierte en un recurso, direccionado por una URI como
runbook://redemarrage-api; - la búsqueda por palabra clave se convierte en una herramienta, que el modelo invoca cuando busca un procedimiento;
- el método de investigación se convierte en un prompt, que el usuario lanza de forma explícita.
La ventaja frente a un simple copiar y pegar en la conversación: la fuente sigue siendo única, actualizada y versionada, y el asistente solo lee lo que necesita.
Preparar el entorno
El SDK requiere Python 3.10 o superior. Se instala desde PyPI con el nombre mcp; el extra cli añade el comando mcp, útil para probar:
python3 -m venv .venv
. .venv/bin/activate
pip install "mcp[cli]"
El proyecto recomienda además uv para gestionar el entorno. Consulta la documentación del SDK de Python para el método actualizado.
En cuanto al contenido, supongamos un directorio de archivos Markdown, uno por runbook:
/opt/runbooks/
redemarrage-api.md
saturation-disque.md
certificat-expire.md
En la práctica
Paso 1: declarar el servidor y los recursos
El servidor cabe en un solo archivo. Se empieza por el objeto servidor y un recurso parametrizado que lee un runbook por su nombre. La función solo se invoca cuando un cliente lee realmente el recurso.
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")
Cuentan dos detalles. La validación del nombre con una expresión regular y luego la comprobación de la ruta resuelta bloquean los intentos del tipo ../../etc/passwd. Y los mensajes de error se mantienen sobrios: no revelan el árbol de directorios del servidor.
Paso 2: añadir una herramienta de búsqueda
El modelo no conoce los nombres de tus archivos. Una herramienta de búsqueda le permite encontrar el runbook adecuado a partir de un síntoma:
@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 no es decorativa: es la descripción que lee el modelo para decidir cuándo invocar la herramienta. Las anotaciones indican al cliente que la herramienta no modifica nada, pero son solo indicaciones; la seguridad descansa en el propio código.
Paso 3: ofrecer un prompt de investigación
Un prompt orienta al usuario hacia un método coherente:
@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()
Sin argumentos, mcp.run() usa el transporte stdio. La salida estándar se reserva entonces al protocolo: usa el módulo logging, que escribe en la salida de error, en lugar de print().
Paso 4: probar con el Inspector
El comando que ofrece el extra cli lanza el servidor bajo MCP Inspector, una interfaz web de pruebas (requiere Node.js):
mcp dev serveur_runbooks.py
Prueba la búsqueda con palabras clave reales, lee un recurso y después prueba a propósito nombres inválidos para comprobar los rechazos.
Paso 5: declarar el servidor en tu asistente
La mayoría de los hosts aceptan un comando de arranque en su configuración. Usa el Python del entorno virtual para asegurarte de tener las dependencias correctas:
{
"mcpServers": {
"runbooks": {
"command": "/opt/runbooks-mcp/.venv/bin/python",
"args": ["/opt/runbooks-mcp/serveur_runbooks.py"],
"env": { "RUNBOOKS_DIR": "/opt/runbooks" }
}
}
}
Para un servidor compartido por el equipo, el SDK también sabe servir por HTTP con mcp.run(transport="streamable-http"), que escucha por defecto en la interfaz local. Antes de abrirlo a la red, añade autenticación y relee nuestra guía para proteger un servidor MCP.
Buenas prácticas
- Empezar en solo lectura; añadir herramientas de acción solo con validación humana.
- Validar cada argumento en el servidor: listas permitidas, longitudes, formatos.
- Redactar docstrings precisas: guían la elección del modelo.
- Lanzar un error de herramienta explícito en lugar de devolver un texto de error como si fuera un resultado.
- Registrar en la salida de error, nunca en la salida estándar con stdio.
- Versionar los runbooks en Git y revisarlos como código: se convierten en instrucciones leídas por un agente.
Preguntas frecuentes
¿Hay que usar FastMCP o MCPServer?
En el SDK oficial en versión 2, FastMCP se ha renombrado a MCPServer. La guía de migración del SDK detalla la correspondencia de los imports.
¿Es observable mi servidor?
El SDK v2 emite spans de OpenTelemetry por cada mensaje procesado; basta con instalar un SDK y un exportador. Consulta observar los agentes MCP con OpenTelemetry.
¿Puedo vincular este servidor a mis incidentes?
Sí, combinando sus runbooks con un servidor de observabilidad en el mismo asistente. Nuestras fichas como los incidentes habituales de un clúster Managed son, además, buenas candidatas para convertirse en runbooks.
Conclusión
Crear un servidor MCP en Python requiere poco código; el cuidado se pone en otra parte: validación de las entradas, descripciones claras, errores explícitos y perímetro de solo lectura. Este pequeño servidor de runbooks ya aporta un valor real durante las guardias y es una base sana para ir más lejos.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y las opciones en su documentación oficial.