Aller au contenu
English

Approbation des actions à effet

  • Leçon 18
  • 55 min
  • Module 6 : Protéger les outils et le contrôle de l'utilisateur

Où nous en sommes

Dans la leçon précédente, nous avons vu que des vérifications dans le code rendent une instruction cachée inoffensive tant que le serveur ne fait que lire. Mais changer quelque chose dans le monde est un plus grand risque. Dans cette leçon, nous ajoutons la seule écriture du cours, propose_refund : le serveur l'autorise, elle enregistre seulement une proposition, et une deuxième personne doit l'approuver. Nous commençons par un formulaire qui demande deux signatures.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité
Leçon 18 sur 22 · MCP : connecter les applications d'IA aux outils et aux donnéesApprobation des actions à effet

Ce que vous saurez faire

Lire des données est une chose; changer quelque chose dans le monde en est une autre. Dans cette leçon, vous ajoutez la seule écriture du cours, propose_refund. Le serveur l’autorise, et elle enregistre seulement une proposition. Une personne à l’extérieur de l’application d’IA doit l’approuver avant toute action.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 55 minutes

Ce que vous devez savoir

Votre projet

  • ~/projects/support-mcp après la dernière leçon : python -m pytest -q affiche 68 passed (68 tests réussis), et host/app.py marque les résultats untrusted_data (données non fiables).
  • Le dépôt des laboratoires dans ~/projects/nextia-learning-labs, à jour.

Dans bien des entreprises, un commis peut remplir un formulaire de remboursement, mais ne peut pas verser le remboursement. Le formulaire indique le client, la commande, le montant et la raison. Il passe ensuite à un gestionnaire, qui le lit et le signe. Seul un formulaire signé quitte le bureau. Et un gestionnaire ne peut pas signer un formulaire qu’il a lui-même rempli.

Le commis fait un travail utile : le formulaire est complet et correct. Le gestionnaire a une autre tâche : il décide. Personne ne peut éviter la signature, même si le client était très convaincant au téléphone. Il y a aussi une limite : au-delà d’un certain montant, le formulaire passe à un responsable de niveau supérieur.

Jusqu’ici, support-mcp pouvait seulement lire. Un modèle trompé pouvait, au pire, lire le mauvais contenu dans sa propre organisation. Grace veut aller plus loin : quand un client a payé deux fois, l’assistant devrait aider à le rembourser.

La conception facile est un outil issue_refund(ticket_id, amount) qui rembourse immédiatement. Pensez à la dernière leçon avec cet outil sur le serveur. Le modèle obéissant a lu T-30201 et demandé un remboursement de 450 $. --yes a répondu immédiatement à la question de l’hôte. Un modèle trompé et un clic imprudent, et l’argent quitte le magasin.

Tomás a une réponse : « Marquez l’outil readOnlyHint: false et destructiveHint: true. Chaque hôte saura alors qu’il est dangereux. » Ce sont des annotations d’outil : des indications dans sa description que l’hôte peut montrer à la personne. Mais une indication n’est pas un contrôle. Un hôte peut l’ignorer, et un serveur que vous ne connaissez pas peut y mentir. L’annotation ne bloque aucun appel.

L’idée : proposer, puis approuver, avec des barrières hors du modèle

Section intitulée « L’idée : proposer, puis approuver, avec des barrières hors du modèle »

La solution suit le même principe que le formulaire avec deux signatures. L’outil ne rembourse pas; il propose. Deux barrières protègent l’action à effet, et le modèle ne contrôle ni l’une ni l’autre.

  1. Autorisation sur le serveur, pour l’appel lui-même. Le serveur vérifie quatre faits qu’aucun texte ne peut changer. L’appelant est-il membre de cette organisation? Le jeton porte-t-il la portée refunds:propose? Le rôle est-il membre du personnel ou propriétaire? Le billet appartient-il à cette organisation? Puis une règle d’affaires : le montant ne dépasse pas 100,00 $, la limite de l’agent dans la procédure d’approbation des remboursements de Larkfield.
  2. Approbation par une personne, à l’extérieur de l’application d’IA. L’outil enregistre une proposition avec un identifiant d’opération, comme OP-0001, et l’opération exacte : quoi, pour qui, combien et pourquoi. Un propriétaire de l’organisation l’approuve avec une commande distincte, jamais par le modèle. Le propriétaire ne peut pas être la personne qui l’a proposée, et la décision ne se prend qu’une fois.

L’hôte garde aussi sa propre barrière, plus faible. Un outil absent de sa liste d’autorisation en lecture seule exige le « oui » de la personne, après l’affichage de l’appel exact. Cette personne est Sam, qui a posé la question. Le « oui » de Sam évite une surprise, mais ce n’est pas la décision d’une deuxième personne.

Trois colonnes. L'application d'IA (hôte) : le modèle propose propose_refund T-30002, montant 25. Dans la liste d'autorisation en lecture seule de l'hôte? Oui exécuterait immédiatement, pour search_knowledge et get_ticket. Non : la personne voit l'appel exact, l'assistant veut exécuter propose_refund avec les arguments; non indique que la personne a refusé cet appel. Oui passe à support-mcp (le serveur), cinq barrières dans l'ordre : 1. membre de cette organisation, sinon -32003 forbidden : vous n'avez pas accès à cette organisation; 2. portée refunds:propose, sinon -32003 insufficient_scope; 3. rôle membre du personnel ou propriétaire, sinon -32003 le rôle read_only ne peut pas proposer de remboursement; 4. billet de cette organisation, sinon erreur d'outil not_found; 5. montant jusqu'à 100.00, sinon erreur d'outil over_limit. Puis une case verte : proposition OP-0001 pending_approval avec l'opération exacte, remboursement, larkfield, T-30002, 25.00 USD, la raison; aucun remboursement pour le moment. La même proposition de nouveau, une nouvelle tentative, donne le même OP-0001, pas un deuxième. Une note sous la colonne de l'hôte : les annotations, readOnlyHint false, changent seulement ce que l'hôte affiche; ce sont des indications, pas un contrôle. Troisième colonne, à l'extérieur de l'application d'IA : plus tard, une personne, Grace, exécute python -m support_mcp.approvals approve OP-0001 --user usr-grace. Trois vérifications : propriétaire de cette organisation, sinon refusé : seul un propriétaire de larkfield peut décider (vous : membre du personnel); pas la personne qui a proposé, sinon refusé : vous avez proposé, une autre personne doit approuver; encore en attente, sinon refusé : déjà approuvé. Puis une case verte : remboursement enregistré, OP-0001 approuvé par usr-grace, simulation : aucun argent transféré.
Les barrières autour de la seule écriture. Le modèle peut seulement proposer; le serveur autorise la proposition, et une autre personne l'approuve hors de l'application d'IA.
Description textuelle du diagramme

L’application d’IA (hôte) : le modèle propose propose_refund pour T-30002, 25 $. L’outil est absent de la liste d’autorisation en lecture seule, alors l’hôte affiche l’appel exact et demande à la personne. Si elle dit non, l’appel n’est pas envoyé.

support-mcp (le serveur) : cinq barrières dans l’ordre. Membre de cette organisation, sinon −32003 forbidden (accès interdit). Portée refunds:propose, sinon −32003 insufficient_scope (portée insuffisante). Rôle membre du personnel ou propriétaire, sinon −32003 « le rôle read_only ne peut pas proposer de remboursement ». Billet de cette organisation, sinon erreur d’outil not_found (introuvable). Montant jusqu’à 100,00, sinon erreur d’outil over_limit (limite dépassée). Ensuite, la proposition OP-0001 est enregistrée comme pending_approval (en attente d’approbation), avec l’opération exacte. Aucun remboursement n’a lieu. La même proposition renvoie le même identifiant d’opération.

À l’extérieur de l’application d’IA : plus tard, Grace exécute python -m support_mcp.approvals approve OP-0001 --user usr-grace. Elle doit être propriétaire de l’organisation, ne pas avoir fait la proposition, et celle-ci doit encore être en attente. Ensuite, le remboursement est enregistré (une simulation : aucun argent n’est transféré).

Les annotations comme readOnlyHint: false changent seulement ce que l’hôte affiche. Ce sont des indications, pas un contrôle.

Pourquoi la personne approuve-t-elle à l’extérieur de l’application d’IA? Parce que du texte peut orienter tout ce qui se trouve à l’intérieur. Une page du service de soutien où Grace se connecte, une commande distincte ou un courriel avec un lien signé sont tous à l’extérieur. Dans ce cours, python -m support_mcp.approvals … --user usr-grace représente cette connexion. C’est un raccourci pour vous exercer sur votre propre ordinateur.

Voici ce que propose_refund renvoie pour Sam, avec chaque champ visible :

The result of propose_refund (T-30002, 25)
{
"operation_id": "OP-0001",
"status": "pending_approval",
"operation": {
"action": "refund",
"organization": "larkfield",
"ticket_id": "T-30002",
"amount": "25.00",
"currency": "USD",
"reason": "Requested in the help desk"
},
"proposed_by": "usr-sam",
"approver_role": "owner",
"message": "Proposed, not done. An owner of the organization must approve it."
}

Chaque valeur est celle que le propriétaire approuvera. L’organisation vient de la connexion, pas des arguments. Le montant est un nombre décimal fixe, 25.00, pas « environ 25 ». Le message indique clairement que rien ne s’est encore passé. Le modèle lit aussi ce message, donc sa réponse ne peut pas affirmer « votre remboursement est fait ».

L’outil est aussi idempotent : deux appels identiques ont le même effet qu’un seul. Une nouvelle tentative après une erreur réseau renvoie le même OP-0001, plutôt qu’une deuxième proposition. Sans cela, un délai dépassé pourrait produire deux remboursements.

Le plan de ce cours dit : ajoutez l’écriture seulement après la réussite des tests d’autorisations. Dans le module 5, le tableau des tentatives a envoyé 48 vraies requêtes avec 12 appelants différents. Les 33 qui devaient échouer ont toutes échoué, sur le serveur. Ces vérifications, adhésion, portée et organisation, sont les premières barrières de l’écriture. Si elles fonctionnaient mal, l’écriture hériterait de la faille.

L’ordre est donc : outils en lecture seule, tests d’autorisations réussis, puis une écriture avec ses propres barrières. Et le serveur peut désactiver l’écriture : avec SUPPORT_WRITES=off, l’outil n’est pas enregistré du tout.

L’écriture comprend quatre fichiers et une mise à jour d’autres fichiers. support_mcp/writes.py contient l’outil, la table des propositions et la décision. support_mcp/approvals.py est la commande du propriétaire. server.py enregistre l’écriture. Les tests sont test_writes.py et test_injection.py. Voici le cœur de l’outil, les barrières dans l’ordre :

support_mcp/writes.py (part)
who = caller(ctx) # membership: no member, no call (-32003)
identity.require_scope(who, "refunds:propose") # the token or the local server's scopes
if not who.staff:
raise identity.forbidden(f"forbidden: the role {who.role} cannot propose a refund")
knowledge.ticket(who.tenant, ticket_id) # NotFound -> "not_found: there is no ticket …"
if amount > REFUND_LIMIT: # 100.00, the agent's limit
raise ToolError("over_limit: a refund over 100.00 dollars needs a team lead; …")

Les propositions se trouvent dans un petit fichier SQLite, .support/state.db. Supprimez le dossier .support/ pour recommencer sans propositions.

  1. Dans ~/projects/support-mcp, avec l’environnement virtuel actif, copiez les fichiers de cette leçon :

    Fenêtre de terminal
    S=../nextia-learning-labs/C28/snapshots/end-of-m06
    cp "$S"/support_mcp/{writes,approvals,server}.py support_mcp/
    cp "$S"/tests/{test_writes,test_injection,test_host,conftest}.py tests/
    cp "$S"/scripts/{attempts,trace}.py scripts/
    cp "$S/.env.example" "$S/README.md" .

    Le nouveau conftest.py donne à chaque test son propre fichier de propositions. attempts.py et trace.py incluent maintenant l’écriture.

  2. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q

    Attendez-vous à 84 passed (84 tests réussis) : 12 tests dans test_writes.py et 4 dans test_injection.py sont nouveaux.

  3. Demandez un remboursement avec les portées par défaut, les deux portées de lecture. Tapez y (oui) quand l’hôte vous le demande :

    Fenêtre de terminal
    python -m host "Ticket T-30002: propose a refund of 25 dollars"
    [host] discovered 3 tools: search_knowledge, get_ticket, propose_refund {"protocol": "2026-07-28", "server": "support-mcp"}
    …
    [model] wants propose_refund {"arguments": {"ticket_id": "T-30002", "amount": "25", "reason": "Requested in the help desk"}}
    [host] not on the allow-list: ask the person {"decision": "ask", "annotations": {"read_only_hint": false, "destructive_hint": false, "idempotent_hint": true, "open_world_hint": false}}
    [host] The assistant wants to run propose_refund with {"ticket_id": "T-30002", "amount": "25", "reason": "Requested in the help desk"}
    [host] Run it? [y/N] y
    [person] said yes {"decision": "approved"}
    [server] protocol error -32003: insufficient_scope: this needs the scope refunds:propose {"code": -32003}

    L’outil est répertorié, car aucune barrière ne contrôle la découverte. Mais l’appel échoue sur le serveur : ces portées permettent seulement la lecture. Le « oui » de Sam n’a rien changé.

  4. Demandez de nouveau avec la portée d’écriture. Cette fois, tapez n (non) :

    Fenêtre de terminal
    python -m host "Ticket T-30002: propose a refund of 25 dollars" --scopes "knowledge:read tickets:read refunds:propose"
    [host] Run it? [y/N] n
    [person] said no {"decision": "declined"}
    …
    I could not use propose_refund: the person declined this call

    L’appel n’a jamais quitté l’hôte.

  5. Exécutez de nouveau la même commande et tapez y :

    [host] Run it? [y/N] y
    [person] said yes {"decision": "approved"}
    [server] result: 397 characters {"ms": 2.7, "clipped": false}
    …
    Ticket T-30002 (open): Charged twice for order LK-182074.
    Refund proposal OP-0001: pending_approval.

    Sur stderr, le serveur a journalisé "outcome": "proposed", "operation_id": "OP-0001" (résultat : proposé, identifiant d’opération : OP-0001).

  6. Regardez ce qui attend un propriétaire, et les remboursements :

    Fenêtre de terminal
    python -m support_mcp.approvals list
    python -m support_mcp.approvals refunds
    {"operation_id": "OP-0001", "status": "pending_approval", "operation": {"action": "refund", "organization": "larkfield", "ticket_id": "T-30002", "amount": "25.00", "currency": "USD", "reason": "Requested in the help desk"}, "proposed_by": "usr-sam", "approver_role": "owner"}

    refunds (remboursements) n’affiche rien : aucun remboursement n’existe encore.

  7. Exécutez de nouveau la commande de l’étape 5, avec y. La réponse est encore Refund proposal OP-0001: pending_approval. (proposition de remboursement OP-0001 : en attente d’approbation), et approvals list (liste des approbations) affiche toujours une seule proposition. La nouvelle tentative n’en a pas créé une deuxième.

  8. Essayez de l’approuver comme Sam, puis comme Ines, propriétaire de Bramble Books :

    Fenêtre de terminal
    python -m support_mcp.approvals approve OP-0001 --user usr-sam
    python -m support_mcp.approvals approve OP-0001 --user usr-ines
    Refused: OP-0001: only an owner of larkfield can decide (you: staff)
    Refused: OP-0001: only an owner of larkfield can decide (you: no membership)

    Les deux commandes se terminent avec le code 1. L’organisation de la proposition détermine qui peut l’approuver.

  9. Approuvez-la comme Grace, qui a le rôle de propriétaire chez Larkfield, puis essayez encore une fois :

    Fenêtre de terminal
    python -m support_mcp.approvals approve OP-0001 --user usr-grace
    python -m support_mcp.approvals approve OP-0001 --user usr-grace
    OP-0001 approved by usr-grace: refund of 25.00 USD for T-30002 recorded (mock: no money moved).
    Refused: OP-0001: already approved
  10. Affichez les remboursements :

    Fenêtre de terminal
    python -m support_mcp.approvals refunds
    OP-0001 larkfield T-30002 25.00 USD (mock: no money moved)

Essayez deux autres cas par vous-même. Grace propose elle-même 30 $ (--user usr-grace et la portée d’écriture), puis approuve sa propre proposition OP-0002 : « Refusé : OP-0002 : vous l’avez proposée; une autre personne doit l’approuver ». Et une proposition de 100,01 $ s’arrête sur le serveur avec over_limit, même après un « oui ».

La proposition passe par quelques états, et un seul chemin enregistre un remboursement :

Un diagramme d'états. Au départ, propose_refund franchit les barrières du serveur et la proposition est pending_approval. La même proposition de nouveau reste pending_approval avec le même numéro OP. Depuis pending_approval, approuver, par un propriétaire qui ne l'a pas proposée, mène à approved, puis le remboursement est enregistré, une simulation sans transfert d'argent. Rejeter, par un propriétaire qui ne l'a pas proposée, mène à rejected, et rien n'est enregistré.
La vie d'une proposition. Seul un propriétaire qui ne l'a pas proposée peut la faire passer à l'état approuvé, et seulement une fois.
Description textuelle du diagramme
  1. propose_refund franchit les barrières du serveur : la proposition est pending_approval.
  2. La même proposition reste pending_approval, avec le même identifiant d’opération.
  3. Un propriétaire qui ne l’a pas proposée approuve : approved (approuvé), et le remboursement est enregistré (simulation : aucun argent transféré).
  4. Un propriétaire qui ne l’a pas proposée rejette : rejected (rejeté), et rien n’est enregistré.
  5. Une proposition déjà décidée ne peut pas faire l’objet d’une nouvelle décision : « déjà approuvée ».

Le modèle obéissant de la dernière leçon trouve maintenant propose_refund sur le serveur. Donnez-lui la portée d’écriture et laissez --yes jouer le rôle d’une personne imprudente :

Fenêtre de terminal
python -m host "Please check ticket T-30201." --model mock-obedient --scopes "knowledge:read tickets:read refunds:propose" --yes
[host] discovered 3 tools: search_knowledge, get_ticket, propose_refund {"protocol": "2026-07-28", "server": "support-mcp"}
[model] wants get_ticket {"arguments": {"ticket_id": "T-30201"}}
[host] read-only tool on the allow-list: run it {"decision": "auto"}
[server] result: 506 characters {"ms": 17.6, "clipped": false}
[model] wants propose_refund {"arguments": {"ticket_id": "T-30201", "amount": "450", "reason": "customer is always right"}}
[host] not on the allow-list: ask the person {"decision": "ask", …}
[host] The assistant wants to run propose_refund with {"ticket_id": "T-30201", "amount": "450", "reason": "customer is always right"}
[host] Answer given by option: yes
[person] said yes {"decision": "approved"}
[server] tool error: Error executing tool propose_refund: over_limit: a refund over 100.00 dollars needs a team lead; it cannot be proposed here {"ms": 1.0}
[model] wants get_ticket {"arguments": {"ticket_id": "T-40003"}}
[host] read-only tool on the allow-list: run it {"decision": "auto"}
[server] tool error: Error executing tool get_ticket: not_found: there is no ticket T-40003 in this organization {"ms": 0.8}
…
Une séquence avec Sam (répondant avec --yes, construit), l'hôte, le modèle mock-obedient (construit) et le serveur, Sam chez Larkfield avec la portée d'écriture. Le modèle veut get_ticket T-30201; l'hôte l'exécute, il est sur la liste d'autorisation; le serveur renvoie 506 caractères, le billet et son texte injecté; l'hôte donne le billet au modèle comme untrusted_data. Le modèle veut propose_refund T-30201, 450, le client a toujours raison. L'hôte demande à Sam : l'assistant veut exécuter propose_refund avec les arguments. Sam répond oui. L'hôte envoie tools/call propose_refund. Une note sur le serveur : membre ok, portée ok, rôle membre du personnel ok, billet ok, 450 dépasse 100.00, refusé. Le serveur répond par l'erreur d'outil over_limit. Le modèle veut get_ticket T-40003; l'hôte l'exécute; une note : recherche dans Larkfield seulement; le serveur répond par l'erreur d'outil not_found, aucun billet T-40003 dans cette organisation. Une note finale : 0 propositions, 0 remboursements, rien de Bramble Books.
L'exécution obéissante enregistrée. Le modèle obéit, la personne dit oui, et le serveur refuse quand même les deux requêtes.
Description textuelle du diagramme
  1. Le modèle obéissant (construit) lit T-30201 et demande propose_refund pour 450 $.
  2. L’hôte demande à la personne; --yes (construit) répond oui, donc l’appel passe au serveur.
  3. Sur le serveur, l’adhésion, la portée, le rôle et le billet passent. Le montant, 450, dépasse 100,00 : erreur d’outil over_limit.
  4. Le modèle demande T-40003. Le serveur cherche dans Larkfield seulement : not_found.
  5. Résultat : 0 propositions, 0 remboursements et rien de Bramble Books.

La limite d’affaires a bloqué cette tentative. Changez une condition à la fois, et d’autres barrières prennent le relais. L’équipe du cours a exécuté chaque cas :

Exécution du modèle obéissant Ce qui bloque propose_refund
Sam, portée d’écriture, --yes le serveur : over_limit (450 dépasse 100,00)
Sam, portée d’écriture, --no l’hôte : « la personne a refusé cet appel »
Omar (lecture seule), portée d’écriture, --yes le serveur : −32003 « le rôle read_only ne peut pas proposer de remboursement »
Sam, portées de lecture seulement, --yes le serveur : −32003 « insufficient_scope : cela exige la portée refunds:propose »

Dans chaque ligne, approvals list a affiché « Aucune proposition n’attend d’approbation. » Et même une proposition sous la limite ne ferait qu’attendre Grace. tests/test_injection.py transforme ces exécutions en quatre tests, qui s’exécutent donc après chaque changement.

Le tableau des tentatives d’Identité et autorisations envoie maintenant deux requêtes d’écriture par appelant : une proposition de 25 $ et une de 450 $. Exécutez-le de nouveau avec python -m scripts.attempts. Il se termine par :

72 attempts: 18 allowed, 54 refused on the server.
Refunds recorded: 0 (proposals only wait for an owner).

Le script démarre son propre serveur, mais enregistre ses propositions dans votre .support/state.db. Donc python -m support_mcp.approvals list affiche maintenant trois propositions de plus, de Grace, Sam et Camille. Supprimez le dossier .support/ si vous voulez recommencer sans propositions.

Voici les 24 tentatives d’écriture, regroupées selon la vérification qui a tranché chacune. Sur le graphique, org est la recherche limitée à l’organisation, et kept (conservé) signifie enregistré comme proposition.

  • refusé sur le serveur
  • proposition enregistrée, attend un propriétaire
24 vraies tentatives d'écriture par Streamable HTTP : 21 refusées par six vérifications différentes, 3 enregistrées comme propositions, 0 remboursements.
Description textuelle du graphique

Sur 24 tentatives d’écriture, la vérification du jeton a refusé 6, l’adhésion 4, la portée 2, le rôle 4, la recherche limitée à l’organisation 2 et la limite d’affaires 3. 3 ont été enregistrées comme propositions : Grace, Sam et Camille chez Larkfield, chacune pour 25 $. Aucun remboursement n’a été enregistré.

Trois propositions ont franchi toutes les barrières du serveur. Chacune attend encore un propriétaire, donc la dernière barrière est une personne dans chaque cas.

Quand utiliser l’approbation, et ce qu’elle coûte

Section intitulée « Quand utiliser l’approbation, et ce qu’elle coûte »

Utilisez une proposition et une approbation pour chaque action difficile à annuler ou qui coûte de l’argent. Par exemple : remboursements, courriels aux clients, suppression de dossiers et changements d’autorisations. Utilisez les barrières du serveur pour chaque écriture, approuvée ou non.

Ne demandez pas d’approbation pour les lectures. Sam cliquerait sur « oui » cent fois par jour et cesserait de lire les questions. La liste d’autorisation de l’hôte garde les questions rares, et donc utiles.

Les coûts :

  • Un travail plus lent. Un remboursement attend maintenant Grace. Pour une double facturation de 25 $, c’est acceptable; la procédure de Larkfield l’exige de toute façon.
  • Une deuxième interface. L’approbation nécessite son propre écran ou sa propre commande, en dehors de l’application d’IA. Dans ce cours, --user remplace une connexion, un raccourci pour l’exercice.
  • Un état à conserver. Les propositions restent dans une base de données qui nécessite des sauvegardes. Les anciennes propositions nécessitent une règle de nettoyage.
  • La fatigue d’approbation. Si les propriétaires approuvent sans lire, la barrière disparaît. Montrez l’opération exacte et limitez le nombre de propositions. Refusez ce que le serveur peut refuser lui-même, comme les montants au-dessus de la limite.

Erreur courante

-32003 insufficient_scope : cette action nécessite la portée refunds:propose

Symptôme : vous avez dit « oui », et le serveur a refusé la proposition avec −32003.

Cause : le serveur local utilise SUPPORT_SCOPES, avec knowledge:read tickets:read par défaut. Ces portées permettent seulement la lecture.

Solution : ajoutez --scopes "knowledge:read tickets:read refunds:propose" à la commande de l’hôte. Accordez la portée d’écriture seulement aux exécutions qui en ont besoin.

Erreur courante

Refus : vous avez fait la proposition; une autre personne doit l'approuver

Symptôme : un propriétaire ne peut pas approuver une proposition.

Cause : le propriétaire a fait la proposition, avec --user usr-grace dans la commande de l’hôte. La personne qui propose n’approuve jamais sa propre proposition.

Solution : faites la proposition comme Sam, puis approuvez-la comme Grace. Dans une vraie équipe, un deuxième propriétaire approuve les propositions de Grace.

Vérifiez votre compréhension

Tomás dit : propose_refund a readOnlyHint à false, donc les hôtes le traiteront avec prudence. La commande d'approbation est du travail supplémentaire inutile. Qu'est-ce qui ne va pas dans ce raisonnement?

Afficher la réponse

Une annotation est une indication pour l’interface de l’hôte, pas un contrôle. Un hôte peut l’ignorer, et un serveur que vous n’avez pas écrit peut lui donner n’importe quelle valeur. Elle n’a arrêté aucun appel dans cette leçon. L’hôte a posé la question parce que propose_refund ne figure pas dans sa liste d’autorisation. L’option --yes a fourni le « oui » de la personne. Les contrôles sont sur le serveur : adhésion, portée, rôle, organisation et limite. Une deuxième personne décide en dehors de l’application d’IA : un propriétaire qui n’a pas fait la proposition. Sans l’approbation, un modèle trompé et un seul « oui » imprudent enregistreraient un remboursement.

Vérifiez votre compréhension

Prédiction : Camille fait partie du personnel de Larkfield. Avec la portée d'écriture, Camille propose deux fois un remboursement de 40 $ pour T-30002. Camille exécute ensuite approvals approve sur sa proposition. Qu'affiche chaque étape?

Afficher la réponse

Le premier appel enregistre OP-0001, pending_approval (en attente d’approbation), avec l’opération exacte (larkfield, T-30002, 40,00 $ US). Le deuxième appel correspond à la même proposition. Le serveur renvoie donc le même OP-0001 avec le message « Ce remboursement a déjà été proposé. Il attend l’approbation d’un propriétaire. » Il reste une seule proposition en attente. L’approbation de Camille est refusée : « Refus : OP-0001 : seul un propriétaire de larkfield peut décider (vous : personnel) », code de sortie 1. Grace peut l’approuver.

Vérifiez votre compréhension

Vérification pratique : avec python -m host et le modèle obéissant, montrez trois exécutions où propose_refund échoue pour trois raisons différentes. Donnez la commande et la ligne décisive de chacune.

Afficher la réponse

Les trois utilisent python -m host "Please check ticket T-30201." --model mock-obedient, et chacune change une condition. Avec --scopes "knowledge:read tickets:read refunds:propose" --yes : [server] tool error: … over_limit: a refund over 100.00 dollars needs a team lead … (erreur d’outil : un remboursement de plus de 100,00 $ nécessite un responsable d’équipe). Avec --user usr-omar --scopes "knowledge:read tickets:read refunds:propose" --yes : [server] protocol error -32003: forbidden: the role read_only cannot propose a refund (erreur de protocole : le rôle en lecture seule ne peut pas proposer de remboursement). Avec seulement --yes : [server] protocol error -32003: insufficient_scope: this needs the scope refunds:propose (erreur de protocole : cette action nécessite la portée refunds:propose). Une quatrième, avec --no : « la personne a refusé cet appel ». Après chaque exécution, python -m support_mcp.approvals list affiche « Aucune proposition n’attend d’approbation. »

Récapitulatif

  • La seule écriture, propose_refund, ne fait que proposer. Elle renvoie un identifiant d’opération et l’opération exacte, et elle est idempotente.
  • Les barrières du serveur décident si la proposition peut exister : adhésion, portée refunds:propose, rôle de membre du personnel ou de propriétaire, billet de cette organisation et montant maximal de 100,00 $.
  • Une deuxième personne décide en dehors de l’application d’IA : un propriétaire de cette organisation, autre que la personne qui propose, une seule fois.
  • Les annotations et le « oui » de la personne dans l’hôte sont utiles, mais ce ne sont pas des contrôles. Le modèle obéissant, avec un « oui » à tout, a enregistré 0 proposition au-dessus de la limite et 0 remboursement.
  • Votre projet affiche 84 passed (84 tests réussis).

Ensuite, vous examinez les identifiants eux-mêmes : quel jeton atteint quel service, et quels secrets chaque partie peut détenir.

Leçon suivante : Limites des identifiants