Aller au contenu

Cercle IA .tech · Technique

Cercle IA TechMCP

Guide

Concevoir un outil MCP : nom, schéma, erreurs, état

Les règles de la spécification MCP pour bien définir un outil : format du nom, schéma d'entrée et de sortie, deux types d'erreurs, état par identifiant.

Mis à jour le

Dans MCP (Model Context Protocol), un outil est une fonction que le modèle peut appeler. La spécification, révision datée du 28/07/2026 (identifiant 2026-07-28) et lue le 16/11/2026, fixe peu de règles de forme mais beaucoup de conseils qui décident si le modèle s'en sert bien. Cette page les rassemble pour qui écrit un serveur. Pour la distinction entre outils, ressources et prompts, voir outils, ressources et prompts ; pour écrire le code, le serveur en Python.

Examinez les descriptions du catalogue MCP d’ALMA pour préparer vos propres questions de conception. Comparez surtout la portée d’une opération, ses paramètres et les droits nécessaires, plutôt que le seul nom de l’outil.

Ce que contient une définition

Une définition d'outil comporte : name (identifiant unique), title (nom lisible, facultatif), description (facultatif), icons (facultatif), inputSchema (schéma JSON des paramètres), outputSchema (facultatif) et annotations (facultatif, décrit le comportement). Par défaut, les schémas suivent JSON Schema 2020-12 sauf si un champ $schema dit autrement. Le schéma d'entrée doit être un objet valide, jamais null.

Un point de sécurité à ne pas oublier : les clients doivent considérer les annotations comme non fiables, sauf si le serveur est de confiance.

Le nom

Règles de la spécification (formulées en « devrait ») :

  • entre 1 et 128 caractères, sensible à la casse ;
  • uniquement lettres ASCII, chiffres, tiret bas, tiret et point ;
  • ni espace, ni virgule, ni autre caractère spécial ;
  • unique au sein du serveur.

Exemples valides donnés : getUser, DATA_EXPORT_v2, admin.tools.list. L'unicité ne vaut que dans un serveur : un client qui agrège plusieurs serveurs peut rencontrer deux outils search, et la spécification lui conseille de préfixer par un identifiant de serveur. Elle précise que le nom du serveur (serverInfo) n'est pas garanti unique.

Les schémas

Un outil sans paramètre se déclare ainsi, forme recommandée par la spécification :

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

Le outputSchema est facultatif, mais s'il est fourni, le serveur doit produire un résultat structuré conforme et le client devrait le valider. Le résultat structuré se place dans structuredContent, et pour la compatibilité, un outil qui en renvoie devrait aussi mettre le JSON sérialisé dans un bloc de texte. Un schéma de sortie aide aussi les clients à typer ce qu'ils reçoivent.

Deux sortes d'erreurs

La spécification distingue :

  1. Les erreurs de protocole (outil inconnu, requête mal formée, panne du serveur), renvoyées comme erreurs JSON-RPC. Le modèle a peu de chances d'y remédier.
  2. Les erreurs d'exécution (panne d'une interface externe, paramètre invalide, règle métier), renvoyées dans le résultat avec isError: true. Elles contiennent un retour exploitable par le modèle pour se corriger.

L'exemple de la spécification : « Invalid departure date: must be in the future. » Un message précis, qui dit quoi corriger, vaut mieux qu'un échec muet. Les clients devraient transmettre ces erreurs d'exécution au modèle.

Garder un état : l'identifiant explicite

MCP n'a pas de session au niveau du protocole : le serveur ne peut pas compter sur un état implicite attaché à la connexion. Pour un panier, un navigateur ouvert ou une transaction, la spécification conseille (section non normative) de renvoyer un identifiant à la création, que le modèle reprend dans les appels suivants. Ses recommandations sur cet identifiant :

  • Autorisation : pour un serveur authentifié, l'identifiant est un nom, pas une clé ; vérifiez les droits de l'appelant à chaque appel. Pour un serveur sans authentification, générez-le avec assez d'entropie (UUIDv4) et une durée de vie bornée.
  • Opacité : pas de structure interne à deviner.
  • Durée de vie : à dire dans la description de l'outil de création (« les paniers expirent après 24 heures d'inactivité »).
  • Expiration : un identifiant inconnu ou périmé doit donner une erreur d'exécution claire, pour que le modèle recrée un état.

Les obligations de sécurité

Côté serveur : valider toutes les entrées, contrôler les accès, limiter la fréquence des appels, nettoyer les sorties. Côté client, la spécification recommande (SHOULD) la confirmation pour les opérations sensibles, l'affichage des entrées avant l'appel, la validation des résultats, les délais maximaux et le journal d'usage.

Exemple de contrat pour un outil de consultation

Pour lire_stock_piece, décrivez la référence attendue, le dépôt concerné et l'unité de quantité. Si une pièce est connue mais épuisée, une quantité nulle constitue un résultat valide. Si la référence est inconnue, renvoyez un échec métier explicite ; si l'utilisateur n'a pas accès au dépôt, refusez l'accès sans dévoiler ses quantités. Ces choix de conception sont à fixer dans votre contrat.

Testez séparément un champ obligatoire absent, une référence inexistante et un compte sans permission. Une validation de schéma ne vérifie ni l'existence de la pièce ni les droits sur le dépôt. Si vous ajoutez ensuite un outil de réservation, documentez son effet et la manière de reconnaître une relance après coupure pour éviter une double réservation.

Décrire un outil de calcul sans ambiguïté

Pour un outil fictif de calcul de surface, déclarer deux nombres ne suffit pas. Le contrat doit préciser les grandeurs, les unités admises, le domaine de valeurs et la règle d’arrondi. Une longueur absente doit provoquer une demande complémentaire ou une erreur définie ; elle ne vaut pas automatiquement zéro.

Nous proposons de retourner le résultat avec l’unité, les entrées effectivement utilisées et la version de la méthode. L’assistant peut alors expliquer ce qui a été calculé sans inventer le périmètre. Cette structure est un choix de conception, pas un format imposé par MCP.

Essai de recette Décision attendue du service
Une unité manque Refuser le calcul ou obtenir cette information
Deux unités diffèrent Convertir selon une règle explicite ou refuser
Une entrée sort du domaine Signaler l’entrée concernée, sans produire un résultat plausible
Le temps maximal est dépassé Retourner un état d’échec, sans reprendre un ancien chiffre
Un résultat nul est valide Le distinguer d’une opération non exécutée

Dans la spécification relue le 16/11/2026, les erreurs métier peuvent être transmises avec isError: true. Ne les enveloppez pas dans une réponse présentée comme un calcul réussi. Côté application, vérifiez que le texte final conserve cette distinction, y compris après une nouvelle tentative.

Si le calcul prépare ensuite une écriture, séparez les deux outils. Obtenir une estimation ne doit pas modifier un dossier par effet implicite. La décision d’enregistrer doit porter sur les mêmes entrées et sur le résultat effectivement relu.

Liste de contrôle (synthèse des points ci-dessus)

  • Le nom respecte le format et reste unique.
  • Chaque paramètre a un type, et les schémas sont valides.
  • Les erreurs d'exécution disent quoi corriger.
  • L'état passe par un identifiant, jamais par la connexion.
  • Les entrées sont validées et les sorties nettoyées.

Questions fréquentes

Quels caractères peut contenir un nom d'outil MCP ?

La spécification recommande des lettres ASCII, des chiffres, le tiret bas, le tiret et le point, avec 1 à 128 caractères, sans espace ni virgule. Exemples donnés : getUser, DATA_EXPORT_v2, admin.tools.list.

Comment déclarer un outil sans paramètre ?

La forme recommandée est { "type": "object", "additionalProperties": false }, qui n'accepte que l'objet vide.

Un serveur MCP peut-il garder un état entre deux appels ?

Il n'y a pas de session au niveau du protocole. La spécification conseille de renvoyer un identifiant explicite à la création (un panier par exemple) et de l'exiger dans les appels suivants.

Références du carnet

Pages consultées pour écrire cet article :

  1. Site d’ALMA : référence MCP
  2. https://modelcontextprotocol.io/specification/2026-07-28/server/tools.md

À lire aussi