Définir des prompts

Voici la troisième et dernière primitive du protocole. Les prompts dans les serveurs MCP vous permettent de définir des instructions pré-construites de haute qualité que les clients peuvent utiliser à la place de leurs propres prompts. Voyez-les comme des modèles soigneusement conçus, qui donnent de meilleurs résultats que ce que les utilisateurs formuleraient eux-mêmes. À la fin de cette leçon, vous saurez déclarer un prompt paramétré avec @mcp.prompt, y mobiliser vos outils, et vérifier dans l’inspecteur les messages exacts qui partiront vers Claude.

L’intuition à saisir

L’objection vient naturellement : les utilisateurs peuvent déjà demander à Claude de faire la plupart des tâches directement. Quelqu’un peut parfaitement taper « reformate rapport.pdf en markdown » et obtenir des résultats corrects. Alors pourquoi ajouter une primitive ?

Parce qu’il y a un écart considérable entre « correct » et « fiable ». Le même utilisateur obtiendra de bien meilleurs résultats si vous lui fournissez un prompt spécialisé, soigneusement testé, qui gère les cas limites et suit les bonnes pratiques. En tant qu’auteur du serveur MCP, vous êtes précisément la personne qui peut passer du temps à élaborer, tester et évaluer des prompts fonctionnant de façon cohérente dans différents scénarios — vous connaissez vos outils, vos données et les pièges de votre domaine. Les utilisateurs bénéficient alors de cette expertise sans avoir à devenir eux-mêmes des experts en prompt engineering.

Construire une commande de formatage

Passons à un exemple concret : une commande format qui convertit des documents en markdown. Les utilisateurs taperont /format doc_id et obtiendront une version markdown formatée professionnellement. Du point de vue de l’utilisateur, le déroulé est le suivant :

1. L'utilisateur tape / pour voir les commandes disponibles
2. Il sélectionne "format" et spécifie un identifiant de document
3. Claude utilise votre prompt pré-construit pour lire et reformater le document
4. Le résultat est du markdown propre avec headers, listes et formatage appropriés

Notez au passage l’étape 3 : le prompt ne remplace pas les outils, il les mobilise. C’est l’articulation des primitives entre elles qui donne toute sa valeur à l’ensemble.

Écrire le prompt côté serveur

Les prompts utilisent un pattern de décorateur similaire aux outils et aux ressources, ce qui vous met en terrain connu :

from mcp.server.mcpserver.prompts import base

@mcp.prompt(
    name="format",
    description="Réécrit le contenu du document en syntaxe Markdown."
)
def format_document(
    doc_id: str = Field(description="Identifiant du document à formater")
) -> list[base.Message]:
    prompt = f"""
Votre objectif est de reformater un document en syntaxe markdown.

L'identifiant du document à reformater est :
<document_id>
{doc_id}
</document_id>

Ajoutez des headers, des listes à puces, des tableaux, etc. selon les besoins.
N'hésitez pas à ajouter de la structure.
Utilisez l'outil 'edit_document' pour modifier le document. Une fois le document
reformaté, confirmez que les modifications ont été effectuées.
"""
    
    return [
        base.UserMessage(prompt)
    ]

Observez la fin du texte : le prompt désigne nommément l’outil edit_document et exige une confirmation une fois le travail terminé. Ce sont exactement les précisions qu’un utilisateur pressé n’écrirait pas, et sans lesquelles le modèle pourrait se contenter d’afficher le markdown sans jamais l’enregistrer. La fonction retourne une liste de messages qui sont envoyés directement à Claude ; rien ne vous empêche d’y inclure plusieurs messages utilisateur et assistant pour créer des flux de conversation plus complexes, par exemple pour amorcer un exemple de sortie attendue.

Avant de livrer quoi que ce soit, testez le prompt dans l’inspecteur MCP. L’onglet Prompts liste format avec sa description, affiche un formulaire pour ses arguments (doc_id, obligatoire, avec la description de Field), et le bouton Get Prompt envoie prompts/get : vous voyez exactement les messages qui seront envoyés à Claude, rôle compris, avec la variable déjà interpolée.

Ce que cette centralisation vous apporte

La dernière ligne mérite qu’on s’y arrête : lorsque vous améliorez la formulation d’un prompt sur votre serveur, toutes les applications qui s’y connectent en bénéficient sans redéploiement de leur côté.

Rester dans le domaine de votre serveur

Les prompts fonctionnent mieux quand ils sont spécialisés pour le domaine de votre serveur MCP. Un serveur de gestion de documents proposera des prompts pour formater, résumer ou analyser des documents ; un serveur d’analyse de données, des prompts pour générer des rapports ou des visualisations ; un serveur de code, des prompts pour la révision, la refactorisation et la documentation. Dans chaque cas, l’objectif est le même : fournir des prompts tellement bien conçus et testés que les utilisateurs les préfèrent à leurs propres instructions.

À vous de jouer

1. Ajoutez le prompt format au serveur, relancez l’inspecteur et exécutez prompts/get avec doc_id = plan.md : relisez le message rendu comme si vous étiez Claude. Manque-t-il une consigne ?
2. Écrivez un second prompt, summarize, qui demande un résumé en trois puces d’un document, en nommant l’outil à utiliser pour le lire. Testez-le de la même façon.
3. Ajoutez un message base.AssistantMessage(...) après le message utilisateur pour amorcer la forme de la réponse, et observez le résultat dans l’inspecteur.

Sources officielles : Defining prompts (Claude Academy) · Concepts côté serveur : prompts · Client web de l’Inspector : Prompts

Points clés à retenir

• Un prompt MCP est une instruction pré-construite, testée par l’auteur du serveur, que l’utilisateur déclenche ; il est meilleur que ce que l’utilisateur improviserait.
• @mcp.prompt(name, description) + arguments documentés par Field ; la fonction renvoie une liste de messages (base.UserMessage, base.AssistantMessage).
• Un prompt mobilise les outils : nommez-les et exigez une confirmation, précisions qu’un utilisateur pressé n’écrirait pas.
• Testez dans l’inspecteur (prompts/get) : vous voyez les messages exacts, variables interpolées, avant livraison.