Définir des outils avec MCP

La construction d’un serveur MCP devient beaucoup plus simple avec le SDK Python officiel. Au lieu d’écrire des schémas JSON complexes à la main, vous définissez vos outils avec des décorateurs et vous laissez le SDK produire le schéma. Cette leçon écrit les deux premiers outils de notre serveur de documents : un pour lire, un pour modifier. À la fin, vous saurez déclarer un outil avec @mcp.tool, documenter ses arguments pour Claude, et signaler une erreur que le client pourra lire.

Initialiser le serveur MCP

Le SDK MCP Python rend la création de serveur très simple — une seule ligne suffit :

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("DocumentMCP", log_level="ERROR")

L’objet mcp ainsi créé est le registre central du serveur : c’est lui qui portera les décorateurs de tous les outils, ressources et prompts que nous ajouterons. Le premier argument est le nom sous lequel le serveur se présente aux clients, et log_level="ERROR" limite la sortie aux vraies erreurs, ce qui évite de polluer le canal stdio utilisé pour la communication.

Vos documents peuvent être stockés dans un dictionnaire simple :

docs = {
    "deposition.md": "Ce document couvre le témoignage d'Angela Smith, P.E.",
    "rapport.pdf": "Ce rapport détaille l'état d'une tour de condensation de 20m.",
    "finances.docx": "Ces finances décrivent le budget et les dépenses du projet.",
    "perspectives.pdf": "Ce document présente les performances futures projetées.",
    "plan.md": "Ce plan décrit les étapes de mise en œuvre du projet.",
    "spec.txt": "Ces spécifications définissent les exigences techniques."
}

Définir des outils avec des décorateurs

Le SDK utilise des décorateurs pour définir les outils. Vous n’écrivez pas de schéma JSON : vous annotez les types des paramètres Python et documentez chaque champ, puis le SDK génère le schéma que Claude comprend. La signature de votre fonction devient donc le contrat exposé au modèle, avec une conséquence pratique importante : la qualité de vos descriptions détermine la qualité des appels que fera Claude.

Outil de lecture de documents

Le premier outil lit le contenu d’un document par son identifiant :

from mcp.server.mcpserver.exceptions import ToolError
from pydantic import Field

@mcp.tool(
    name="read_doc_contents",
    description="Lit le contenu d'un document et le retourne sous forme de chaîne."
)
def read_document(
    doc_id: str = Field(description="Identifiant du document à lire")
):
    if doc_id not in docs:
        raise ToolError(f"Document avec l'id {doc_id} introuvable")
    
    return docs[doc_id]

Le décorateur spécifie le nom et la description de l’outil, tandis que les paramètres de la fonction définissent les arguments requis. La classe Field de Pydantic fournit les descriptions d’arguments qui aident Claude à comprendre ce que chaque paramètre attend. Notez aussi le traitement de l’erreur : si l’identifiant n’existe pas, la fonction lève une exception plutôt que de retourner silencieusement None, et l’exception choisie compte. Nous l’avons vérifié sur le SDK 2.3.0 : une ValueError quelconque remonte au client sous la forme opaque « Error executing tool read_doc_contents », le SDK masquant le détail par prudence ; une ToolError du SDK, elle, transmet votre message tel quel (« Error executing tool read_doc_contents: Document avec l’id … introuvable »), avec is_error à vrai. Quand un utilisateur demandera le contenu d’un document mal orthographié, Claude recevra donc un message explicite et pourra réagir : redemander, corriger, ou signaler le problème.

Outil d’édition de documents

Le deuxième outil effectue des opérations de recherche-remplacement sur les documents :

@mcp.tool(
    name="edit_document",
    description="Modifie un document en remplaçant une chaîne par une nouvelle."
)
def edit_document(
    doc_id: str = Field(description="Identifiant du document à modifier"),
    old_str: str = Field(description="Le texte à remplacer. Doit correspondre exactement, espaces compris."),
    new_str: str = Field(description="Le nouveau texte à insérer à la place de l'ancien.")
):
    if doc_id not in docs:
        raise ToolError(f"Document avec l'id {doc_id} introuvable")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Cet outil prend trois paramètres : l’identifiant du document, le texte à trouver, et le texte de remplacement. Observez la description de old_str, qui précise « doit correspondre exactement, espaces compris ». Cette phrase n’est pas là pour le lecteur humain : elle indique au modèle qu’il ne peut pas approximer la chaîne recherchée. C’est un bon exemple de ce qu’apporte une description soignée par rapport à un simple nom de paramètre.

Avantages de l’approche SDK

Le tableau résume ce que le SDK vous épargne par rapport à une définition écrite entièrement à la main.

Voici, mot pour mot, le schéma que le SDK 2.3.0 a généré pour edit_document lors de nos tests, tel que Claude le recevra :

{"type": "object", "title": "edit_documentArguments",
 "properties": {
   "doc_id":  {"type": "string", "title": "Doc Id",  "description": "Identifiant du document à modifier"},
   "old_str": {"type": "string", "title": "Old Str", "description": "Le texte à remplacer. Doit correspondre exactement, espaces compris."},
   "new_str": {"type": "string", "title": "New Str", "description": "Le nouveau texte à insérer à la place de l'ancien."}},
 "required": ["doc_id", "old_str", "new_str"]}

Pourquoi cette approche fonctionne

Le SDK transforme la création d’outils : d’un exercice de rédaction de schémas, on passe à de simples définitions de fonctions Python. Le gain est surtout de maintenance — ajouter un paramètre revient à ajouter un argument, et le schéma exposé à Claude suit automatiquement, sans divergence possible entre la documentation et le code exécuté.

À vous de jouer

1. Écrivez les deux outils dans mcp_server.py, avec ToolError pour les identifiants inconnus, et terminez le fichier par if __name__ == "__main__": mcp.run(transport="stdio").
2. Ajoutez un troisième outil, list_doc_ids, sans argument, qui renvoie la liste des identifiants. Rédigez sa description comme si vous l’expliquiez à un collègue pressé : c’est ce que Claude lira.
3. Modifiez la description de old_str pour retirer « espaces compris », et demandez-vous ce que Claude ferait d’une chaîne approximative : c’est la raison d’être d’une description soignée.

Sources officielles : Defining tools with MCP (Claude Academy) · Serveurs : outils (SDK Python v2) · What’s new in v2

Points clés à retenir

• MCPServer("DocumentMCP") crée le registre ; @mcp.tool(name=…, description=…) déclare un outil ; les annotations de type et Field(description=…) génèrent le schéma JSON.
• La qualité des descriptions détermine la qualité des appels de Claude : écrivez-les pour le modèle, pas pour vous.
• Levez ToolError pour une erreur attendue : le message atteint le client ; une exception quelconque est masquée en « Error executing tool … ».
• Un argument ajouté à la fonction, c’est un champ ajouté au schéma : documentation et code ne divergent jamais.

Il reste à vérifier que tout cela fonctionne. Dans la prochaine leçon, nous testerons ces deux outils avec l’inspecteur MCP, sans écrire une ligne de code de test.