Logs et notifications de progression

Les logs et les notifications de progression sont simples à implémenter mais font une énorme différence dans l’expérience utilisateur lors du travail avec des serveurs MCP. Ils aident les utilisateurs à comprendre ce qui se passe pendant les opérations longues au lieu de se demander si quelque chose a planté.

Le problème

Quand Claude appelle un outil qui prend du temps — comme faire des recherches sur un sujet ou traiter des données — les utilisateurs ne voient généralement rien jusqu’à la fin de l’opération. C’est frustrant car ils ne savent pas si l’outil fonctionne ou s’est bloqué.

Avec les logs et les notifications de progression activés, les utilisateurs obtiennent un retour en temps réel montrant exactement ce qui se passe en coulisses. Ils peuvent voir des barres de progression, des messages de statut, et des logs détaillés pendant l’exécution de l’opération.

Comment ça fonctionne

Dans le SDK MCP Python, les logs et notifications de progression fonctionnent via l’argument Context automatiquement fourni à vos fonctions d’outils. Cet objet contexte vous donne des méthodes pour communiquer avec le client pendant l’exécution.

@mcp.tool(
    name="research",
    description="Fait des recherches sur un sujet donné"
)
async def research(
    topic: str = Field(description="Sujet à rechercher"),
    *,
    context: Context
):
    await context.info("Démarrage des recherches...")
    await context.report_progress(20, 100)
    sources = await do_research(topic)
    
    await context.info("Rédaction du rapport...")
    await context.report_progress(70, 100)
    results = await generate_report(sources)
    
    await context.report_progress(100, 100)
    return results

Les méthodes clés :

Implémentation côté client

Côté client, vous devez configurer des callbacks pour gérer ces notifications. Le serveur émet ces messages, mais c’est à votre application cliente de décider comment les présenter aux utilisateurs.

Callback de logging

async def logging_callback(params: LoggingMessageNotificationParams):
    print(f"[LOG] {params.data}")

Callback de progression

async def progress_callback(
    progress: float, total: float | None, message: str | None
):
    if total is not None:
        percentage = (progress / total) * 100
        print(f"Progression: {progress}/{total} ({percentage:.1f}%)")
    else:
        print(f"Progression: {progress}")

Connecter les callbacks

async with stdio_client(server_params) as (read, write):
    async with ClientSession(
        read,
        write,
        logging_callback=logging_callback  # ← callback de logging
    ) as session:
        await session.initialize()
        
        await session.call_tool(
            name="research",
            arguments={"topic": "intelligence artificielle"},
            progress_callback=progress_callback,  # ← callback de progression
        )

Le callback de logging est fourni lors de la création de la session ; le callback de progression lors de l’appel d’outil individuel.

Options de présentation

Comment vous présentez ces notifications dépend de votre type d’application :

Important : les notifications sont optionnelles

Ces notifications sont entièrement optionnelles. Vous pouvez choisir de les ignorer complètement, d’en afficher seulement certaines, ou de les présenter de la façon qui correspond à votre application. Ce sont purement des améliorations d’expérience utilisateur pour aider à comprendre ce qui se passe pendant les opérations longues.