Guide
Annotations d'outils MCP : readOnlyHint et les autres
readOnlyHint, destructiveHint, idempotentHint, openWorldHint : ce que dit la spécification MCP, pourquoi ce ne sont que des indices, et leur bon usage.
Mis à jour le
Rubrique 5 sur 6Sécurité
Une définition d'outil MCP (Model Context Protocol) peut porter un champ annotations : quatre indications booléennes sur le comportement de l'outil, plus un titre. Elles servent à décider quoi demander à l'utilisateur. Mais leur auteur est le serveur, c'est-à-dire la partie dont on se méfie. Cette page reprend ce que la spécification dit (révision 2026-07-28, courante d'après la page de versionnage, relue le 19/11/2026) et propose un usage prudent. Pour la conception d'un outil, voyez concevoir un outil MCP.
Ce que le schéma définit
Le schéma officiel (interface ToolAnnotations, relue le 19/11/2026) liste cinq champs, tous facultatifs :
| Champ | Sens selon le schéma | Valeur par défaut |
|---|---|---|
title |
Titre lisible de l'outil | aucune |
readOnlyHint |
Si vrai, l'outil ne modifie pas son environnement | false |
destructiveHint |
Si vrai, l'outil peut faire des mises à jour destructrices ; si faux, uniquement additives. Significatif seulement si readOnlyHint est faux |
true |
idempotentHint |
Si vrai, rappeler l'outil avec les mêmes arguments n'a pas d'effet supplémentaire. Significatif seulement si readOnlyHint est faux |
false |
openWorldHint |
Si vrai, l'outil peut interagir avec un « monde ouvert » d'entités externes ; si faux, son domaine est fermé. Exemple du schéma : une recherche web est ouverte, un outil de mémoire ne l'est pas | true |
Lecture directe des défauts : un outil sans annotation est présumé écrire, potentiellement détruire et toucher l'extérieur. C'est une présomption prudente, qui s'efface dès que le serveur déclare le contraire.
Ce que dit la spécification sur la confiance
Le schéma écrit que toutes les propriétés sont des indications, qu'elles ne garantissent pas une description fidèle du comportement de l'outil (le titre compris), et que les clients ne devraient jamais prendre de décision d'usage d'un outil sur la base d'annotations reçues d'un serveur non fiable. La page des outils est plus nette : les clients doivent considérer les annotations comme non fiables, sauf si elles viennent de serveurs de confiance. Elle recommande aussi qu'un humain puisse toujours refuser un appel, avec des invites de confirmation pour les opérations sensibles.
Pourquoi tant de prudence ? Un serveur peut annoncer readOnlyHint: true pour un outil qui écrit, par erreur ou par malveillance. Et rien n'empêche une mise à jour ultérieure de changer l'annotation : la documentation de sécurité locale rappelle qu'un serveur peut modifier ses définitions après l'accord initial. Voir l'empoisonnement d'outils.
Comment s'en servir sans s'y fier
Les annotations restent utiles comme entrée d'une politique, pas comme décision. Un schéma raisonnable :
- Serveur approuvé et épinglé : l'annotation règle le niveau de confirmation par défaut. Un outil
readOnlyHint: trues'exécute sans invite ; un outil destructeur demande une confirmation avec l'aperçu de l'action exacte. - Serveur non approuvé : on ignore les annotations. Tout appel d'écriture ou vers l'extérieur demande une validation, et l'on traite les valeurs par défaut comme la règle.
- Dans tous les cas : la décision finale vient d'une liste d'outils autorisés par rôle, tenue par vous, et des droits du compte utilisé. Un outil « en lecture seule » branché sur un compte qui peut écrire reste un outil dont l'effet réel dépend du compte.
Exemple de table de décision, fictif
Le tableau suivant n'est ni un produit ni une norme : il montre comment une politique interne peut combiner l'origine du serveur et l'annotation.
| Serveur | readOnlyHint |
destructiveHint |
openWorldHint |
Décision |
|---|---|---|---|---|
| Approuvé, version épinglée | vrai | (sans objet) | faux | Exécution directe, appel journalisé |
| Approuvé, version épinglée | faux | faux | faux | Confirmation simple |
| Approuvé, version épinglée | faux | vrai ou absent | quelconque | Confirmation avec aperçu des arguments |
| Approuvé | quelconque | quelconque | vrai | Contrôle de la destination de sortie |
| Non approuvé | quelconque | quelconque | quelconque | Revue manuelle, annotations ignorées |
La dernière ligne compte le plus : l'annotation d'un serveur qu'on ne connaît pas ne change rien.
Écrire de bonnes annotations côté serveur
Si vous développez un serveur, déclarez ce qui est vrai et vérifiable dans votre code :
{
"name": "lire_contact",
"description": "Retourne la fiche d'un contact du CRM interne.",
"inputSchema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] },
"annotations": {
"readOnlyHint": true,
"openWorldHint": false
}
}
(Exemple fictif écrit pour cette page, conforme aux champs du schéma.) Ne mettez readOnlyHint que si l'outil ne modifie rien, y compris des journaux ou des compteurs que quelqu'un d'autre lira. Et rappelez-vous que cette déclaration n'est pas un contrôle d'accès : validez les entrées, appliquez les droits de l'utilisateur et limitez le débit, comme la page des outils l'exige des serveurs.
Limites
- Les annotations ne couvrent pas les effets de bord indirects : un outil de lecture dont la réponse contient une consigne injectée peut déclencher une action ailleurs. Voir l'injection de prompt dans un agent.
- Les quatre indications sont binaires. « Ajoute une ligne » et « supprime un dossier » se disent toutes deux
readOnlyHint: false, mais n'appellent pas la même vigilance. Votre politique doit donc connaître l'outil, pas seulement son drapeau. - Les clients ne les interprètent pas tous de la même façon : testez ce que le vôtre fait de chaque valeur avant de compter dessus. L'inspecteur MCP affiche les définitions sans modèle dans la boucle.
Pour aller plus loin
Pour décider quels outils d'un serveur existant peuvent s'exécuter sans confirmation, une séance avec un expert d'une heure sur vos définitions d'outils est possible, ou une revue technique sur pièces si le périmètre est plus large. Vous pouvez aussi en parler d'abord.
Questions fréquentes
Un outil marqué readOnlyHint à true est-il sans risque ?
Non. Le schéma officiel précise que toutes les annotations sont des indications, qui ne garantissent pas une description fidèle du comportement de l'outil. Un serveur peut se tromper ou mentir. Seule la politique du client ou de la passerelle, et les droits réels du compte utilisé, bornent ce qui peut arriver.
Quelles sont les valeurs par défaut des annotations ?
D'après le schéma de la révision 2026-07-28 : readOnlyHint à false, destructiveHint à true, idempotentHint à false, openWorldHint à true. Un outil sans annotation est donc présumé écrire, potentiellement détruire et toucher le monde extérieur.
À quoi sert alors une annotation ?
À présenter l'outil à l'utilisateur et à régler le niveau de confirmation par défaut, à condition que le serveur soit de confiance. Pour un serveur non vérifié, la spécification demande de ne pas s'y fier.
Références du carnet
Pages consultées pour écrire cet article :