MCP Fusion/Core concepts/Exposition des tools

Exposition des tools

Demandez à l’IA à propos de Vinkius

Écrivez les actions une fois et choisissez leur forme sur le réseau : un tool groupé avec discriminateur ou un tool atomique par action, avec visibilité par tags et schémas propres à chaque action.

La manière dont vous écrivez un connecteur et celle dont l’agent le voit sont deux décisions différentes dans MCP Fusion. La couche d’exposition se trouve entre les deux : elle prend vos builders et compile la surface tools/list reçue par le client. Changez de stratégie sans toucher à un seul handler.

Namespaces : un tool, plusieurs actions

La création utilise des noms avec des points, et le premier point sépare le namespace de l’action :

Vous écrivez	Tool MCP	Action
`f.query('billing.get_invoice')`	`billing`	`get_invoice`
`f.mutation('billing.refund')`	`billing`	`refund`
`f.action('support.tickets.search')`	`support.tickets`	`search`

Les noms de tools ont au plus un point ; les préfixes imbriqués utilisent f.router('support.tickets'). Les builders qui partagent un namespace sont fusionnés par le registry : trois fichiers exportant compliance.scan, compliance.report et compliance.status produisent donc un tool compliance avec trois actions. L’agent voit une surface cohérente ; vous gardez une organisation par fichier et par action.

Deux stratégies

attachToServer(server, { toolExposition }) choisit la forme sur le réseau :

Groupée est la forme par défaut pour les namespaces à plusieurs actions : un tool MCP par namespace avec un champ discriminateur, action par défaut et renommable avec .discriminator('operation'). L’agent choisit l’action comme argument, exactement comme dans une API orientée ressources.

Plate : un tool MCP atomique par action, nommé billing_get_invoice, avec un séparateur configurable. Chaque tool reçoit son propre schéma épuré, avec les champs communs fusionnés avec ceux de cette action uniquement, le discriminateur retiré et ses propres annotations. Utilisez la forme plate lorsque la sélection des tools du client est faible ou lorsque les actions ont très peu en commun.

Les tools plats rendent aussi les affordances HATEOAS directes : un .suggest('billing.remind') depuis une surface plate est un tool que le client liste déjà.

La vérité des annotations

Les verbes sémantiques définissent les annotations MCP, et l’exposition les préserve pour chaque action :

Builder	Annotation
`f.query()`	`readOnlyHint: true`
`f.mutation()`	`destructiveHint: true`
`f.action()`	neutre
`.idempotent()`	`idempotentHint: true`

En mode plat, chaque tool atomique porte ses propres indications. En mode groupé, le tool porte l’agrégat le plus sûr, et les indications propres à chaque action figurent dans les descriptions de leurs schémas. Une mutation destructive qui se déclare en lecture seule est un mensonge sur lequel les clients agissent, le framework n’infère donc jamais une sécurité que vous n’avez pas déclarée.

Les annotations de paramètres enseignent

Les schémas groupés fusionnent les paramètres communs et ceux de chaque action, et la description de chaque champ reçoit une annotation d’obligation générée à partir des actions elles-mêmes :

Annotation	Signification
`(always required)`	requis par toutes les actions du tool
`Required for: refund, void`	requis par toutes les actions listées
`Required for: refund. For: get`	requis par certaines actions, facultatif dans les autres
`For: get, list`	jamais requis, mais utilisé par ces actions

L’agent n’a pas à apprendre la matrice par les erreurs ; le schéma l’énonce. Avec l’énumération du discriminateur, un tool groupé est une API auto-descriptive.

Visibilité par tag

.tags('billing', 'finance') marque un tool, et attachToServer(server, { filter }) décide ce qu’il expose :

typescript

attachToServer(server, {
  filter: {
    tags: ['finance'],          // AND: must carry every tag
    anyTag: ['public'],         // OR: at least one
    exclude: ['internal'],      // NOT
  },
});

Les tags permettent à une base de code de servir plusieurs produits : le niveau gratuit expose les tools publics, le déploiement entreprise expose les tools internes et le code des handlers reste identique. Consultez les Connecteurs multi-tenant pour la version par requête de la même idée.

Le groupement comme stratégie de tokens

Chaque nom de tool, description et schéma coûte du contexte à chaque tour. Cent tools plats représentent cent descriptions que le modèle lit avant de planifier. Regrouper dix actions dans un tool avec une énumération discriminatrice échange la taille du schéma contre celle du prompt, généralement avec un gain important au-delà d’une dizaine d’actions. .toonDescription() compresse encore la description et compactDescription() fournit la forme courte pour la divulgation progressive FSM. L’économie est traitée dans Économie de tokens.

Étapes suivantes

Économie de tokens : payer moins de contexte pour la même surface
Gating d’état FSM : retirer les tools interdits par l’état
Routage : où les builders vivent sur le disque