Conception des capacités

Une capacité est la plus petite compétence descriptible d’un système : typée, vérifiée par les permissions, auditable et utilisable de la même façon par les humains que par les agents. MCP-first ne commence pas par les interfaces, mais par ces capacités. Ce n’est que lorsque l’ensemble des capacités est complet que la webapp, l’application mobile, le CLI et les interfaces agents sont créés comme clients par-dessus.

Les sept blocs de construction

MCP-first modélise chaque capacité avec sept éléments structurels.

Resources

Données et contextes pouvant être lus. Les ressources fournissent à l’agent un contexte préparé, pas des tables de base de données brutes, mais des vues filtrées et finalisées de l’état du système.

Tools

Actions que le système peut exécuter. Chaque outil a un schéma d’entrée typé, un schéma de sortie, un schéma d’erreur et un schéma d’audit. Un outil est ce qu’un bouton dans la webapp ne fait que représenter.

Prompts / Workflows

Flux prédéfinis qui guident un agent à travers des processus complexes et multi-étapes. Les workflows définissent quels outils doivent être appelés dans quel ordre avec quel contexte , et où des entrées humaines sont attendues.

Policies

Règles, droits, niveaux de protection et processus d’approbation. Les politiques décident qui peut voir, appeler et exécuter de manière autonome une capacité. Elles ne sont pas une couche ajoutée après coup, elles font partie de la définition de la capacité.

Audit Events

Chaque action génère une entrée d’audit : qui, quoi, quand, avec quelle approbation, avec quel résultat. Les audit events ne sont pas une extension opérationnelle optionnelle, mais un composant obligatoire de chaque capacité.

Human Confirmation Gates

Mécanismes par lesquels l’agent doit activement demander la confirmation de l’utilisateur avant qu’une action soit exécutée. Les confirmation gates sont déclarativement intégrés dans la capacité , pas implémentés ad hoc dans l’UI.

Risk Metadata

Chaque capacité porte un niveau de risque : low, medium, high, critical ou forbidden_for_ai. Ces métadonnées pilotent le filtrage de découverte, l’obligation de confirmation et l’authentification renforcée, et sont disponibles de manière lisible par les machines dans le contrat d’outil.

Ce que chaque entité devrait offrir

Indépendamment du domaine métier, chaque entité nécessite un ensemble de capacités de base cohérent.

Capacités de base par entité

entity.list Retourner une liste filtrée
entity.search Recherche plein texte avec scoping
entity.get Entité individuelle avec contexte
entity.create Créer une nouvelle entité
entity.update Modifier des champs, idempotent
entity.archive Désactiver plutôt que supprimer
entity.audit Récupérer l'historique des modifications
entity.permissions Interroger les droits effectifs
entity.related Charger les entités liées
entity.recommended_next_actions Suggestions d'actions orientées agents

La couche d’actions en premier

Chaque fonction est d’abord implémentée comme action dans la couche d’actions centrale. Ce n’est qu’ensuite que l’adaptateur d’interface correspondant est créé.

Action: create_project

Utilisé par :
  Webapp
  Application mobile
  Outil MCP
  Worker
  CLI

Il n’y a ainsi pas de double implémentation : quand un bouton de webapp appelle create_project et qu’un agent fait de même, les deux utilisent le même code, les mêmes validations, les mêmes audit events.

Build capabilities once. Expose them everywhere.

Claim central

Le serveur MCP est un adaptateur

Le serveur MCP ne contient pas de logique métier. C’est un mince adaptateur entre le client agent et la couche d’actions.

Ses tâches :

Découverte, quels outils et ressources existent dans ce contexte ?
Exposition de schéma, description typée des entrées, sorties et erreurs
Mappage de contexte d’authentification, mapper le token du client sur le contexte utilisateur et tenant
Vérifications de politique, cet agent peut-il appeler cet outil dans ce contexte ?
Journalisation d’audit, écrire les événements d’exécution pour chaque exécution d’outil

Entrées et sorties typées

Chaque outil définit quatre schémas :

Schéma	Objectif
Schéma d’entrée	Quels paramètres l’outil attend-il, quels types, quels champs obligatoires ?
Schéma de sortie	Que retourne l’outil en cas de succès ?
Schéma d’erreur	Quels codes d’erreur sont possibles, `permission_denied`, `confirmation_required`, `policy_violation` ?
Schéma d’audit	Qu’est-ce qui est écrit dans l’audit event ?

Pas de structures JSON non typées. Les agents, tout comme les compilateurs et les tests, s’appuient sur ces schémas. Les sorties non typées imposent une logique de devinette côté client.

Idempotence

De nombreux outils devraient être idempotents : produire le même résultat pour la même requête, sans générer de doublons inutiles.

create_download_link(fileId, expiresAt)

Si pour fileId un lien valide avec le même expiresAt existe déjà, le lien existant est retourné, aucun second n’est créé. Cela réduit les erreurs d’agent lors des nouvelles tentatives et rend les workflows plus robustes face aux interruptions réseau.