Skip to main content
L’API Solya POS est conçue pour être pilotée par un agent autonome aussi bien que par une intégration classique. Chaque opération documentée porte les métadonnées dont un agent a besoin pour la choisir et l’appeler en sécurité, et la passerelle MCP les exploite pour la découverte.

​
La surface servie

Le document OpenAPI masque toute route qui n’a pas explicitement opté pour la documentation : GET /openapi.json est donc la surface intentionnelle, prête pour les agents. Ajouter une route non documentée ailleurs ne pollue pas cette surface.

​
x-required-permissions

Chaque opération documentée porte l’extension x-required-permissions : la liste des scopes pos.* exigés pour l’appeler. Elle est dérivée du scope de la route et de la méthode (scope de lecture pour un GET/HEAD, scope d’écriture pour une mutation) — jamais écrite à la main, donc jamais divergente de ce que les gardes de route appliquent réellement. Un agent croise ces permissions avec ses propres droits (via whoami) pour ne tenter que les opérations qu’il est autorisé à appeler.

​
x-agent-tier

Chaque opération porte aussi un niveau agent (x-agent-tier) qui indique à quel point l’opération doit être mise en avant. Le vocabulaire d’écriture interne est mappé sur celui de la passerelle au dernier moment : Le mapping vers advanced (et non deprecated) préserve l’intention « appelable, mais non suggérée par défaut » sans mentir sur le cycle de vie : ces opérations sont actuelles et supportées. Un garde de lexique interdit d’écrire une opération à verbe dangereux en preferred.

​
Le flux de découverte MCP

Un agent qui découvre l’API via MCP suit le flux search → describe → invoke :
  1. search — trouver les opérations pertinentes pour la tâche (les preferred/supported en tête ; les advanced sur opt-in seulement).
  2. describe — lire la description, les paramètres, les exemples et les x-required-permissions de l’opération choisie. Les descriptions sont écrites pour un agent : ce que fait l’opération, quand la préférer, ses préconditions et ses conditions d’échec en clair.
  3. invoke — appeler l’opération avec un corps valide (les exemples fournis sont garantis valides vis-à-vis du schéma).

​
Découverte sensible aux droits : whoami

Avant d’appeler, l’agent introspecte ses droits :
C’est ce qui permet à l’agent de savoir, avant d’appeler, quelles opérations documentées il est autorisé à invoquer. La passerelle solya-api-mcp utilise ce point d’accès (sous l’alias ${baseUrl}/api/auth/whoami) pour sa découverte sensible aux droits.

​
Voir aussi