Outils MCP
Les outils exposés par le serveur MCP de Grace et leur endpoint backend.
Le serveur MCP (platform/mcp/) est un adaptateur de protocole : il expose des outils
MCP en Streamable HTTP, valide le bearer, et traduit chaque appel en requête HTTP vers
le backend NestJS. Toute la logique vit dans le backend.
Les outils
| Outil | Rôle | Endpoint backend |
|---|---|---|
grace_prepare_task(talentIds, language?) | Compile les expertises que l'agent désigne — talents du catalogue et consignes privées mêlés — et renvoie un resolutionId qui fige ce qui a été servi. talentIds est obligatoire : une désignation vide est refusée (400 designation_required), il n'y a pas de repli qui devine à la place de l'agent. | POST /prepare-task |
grace_deepen(uri?, section?, query?, k?, scope?) | Approfondit une règle. Avec uri : lit un talent activé ou une version privée autorisée par la résolution du projet. Avec query : recherche littérale et renvoie des pointeurs (id, uri, résumé), jamais de contenu. | POST /talents/get · GET /search |
grace_validate(resolutionId, talent?) | Renvoie l'index d'audit de la résolution — donc des expertises réellement servies — puis le détail ciblé d'un talent. resolutionId est obligatoire : sans lui, aucun périmètre à rejouer. Aucun diff n'est envoyé au serveur. | GET /validation/playbook |
grace_record_validation(submissionId, resolutionId, expertiseResults) | Enregistre un verdict final et ses preuves pour chaque expertise privée de la résolution. Rejouable avec le même payload. | POST /validation/reports |
grace_install_talents(talent | talents) | Installe un talent ({ talent }) ou une liste d'ids nus ({ talents: [...] }, groupé atomique, écrit en DB). Un id absent du catalogue est refusé. N'installe que : la désactivation reste au dashboard. | PATCH /projects/current/talents |
grace_doctor() | Prérequis manquants / conflits sur la sélection courante. | GET /doctor |
grace_discover_codebase() | Procédure de découverte de projet + index du catalogue, à suivre quand la sélection est vide. N'active rien. | GET /discovery/playbook |
Le projet est déduit du bearer — les outils ne prennent jamais d'id de projet.
Altitude
grace_prepare_task sert toujours le compact.md d'une expertise. L'altitude ne se règle
plus par appel : un paramètre facultatif permettait de réduire ce qui était reçu — donc ce sur
quoi l'agent serait relu — sans que rien ne le signale. Pour aller plus loin sur une expertise
précise, l'agent tire le fichier voulu avec grace_deepen({ uri }), à partir des pointeurs
« Quand approfondir » du bloc servi.
Voir Concepts → Altitude pour le principe.
Coût contexte
Les schémas des outils sont déférés par Claude Code (≈ 0 token au repos, ~900 chargés à la demande) — d'où la discipline « surface d'outils minimale ».
Boucle de bout en bout
grace_prepare_taskcompile le contexte et renvoie sonresolutionId.- Après le travail,
grace_validate({ resolutionId })restitue l'index exact des obligations publiques et privées de cette résolution. - L'agent tire uniquement les détails publics utiles avec
grace_validate({ resolutionId, talent }), confronte chaque règle au diff et corrige les violations bloquantes. - S'il existe des expertises privées,
grace_record_validationenregistre exactement un verdict final par expertise, avec des preuvesfichier:ligneou les éléments manquants.
Installer un talent avec grace_install_talents l'ajoute à la sélection pour les résolutions
futures, mais ne change jamais le périmètre d'une résolution déjà enregistrée.
→ Voir Moteur de résolution pour le détail de la composition, et Validation pour le contrat d'audit et d'enregistrement.