Aller au contenu

Cercle IA .tech · Technique

Cercle IA TechMCP

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 :

  1. Serveur approuvé et épinglé : l'annotation règle le niveau de confirmation par défaut. Un outil readOnlyHint: true s'exécute sans invite ; un outil destructeur demande une confirmation avec l'aperçu de l'action exacte.
  2. 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.
  3. 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 :

  1. https://modelcontextprotocol.io/specification/2026-07-28/schema
  2. https://modelcontextprotocol.io/specification/2026-07-28/server/tools
  3. https://modelcontextprotocol.io/specification/versioning
  4. https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/local-server-security.md

À lire aussi