Documentation

Connecteur MCP Antò

Cette page décrit le connecteur MCP d'Antò : ce qu'il fait, comment l'ajouter à un client compatible, comment l'autorisation fonctionne, quels outils sont exposés, quelles limites s'appliquent et comment interpréter les erreurs renvoyées.

Dernière mise à jour : 31 août 2026

1. Ce que fait le connecteur

Le connecteur MCP Antò est un serveur distant qui expose les données et une partie des opérations de votre établissement Antò à un client compatible avec le Model Context Protocol (MCP). Une fois le connecteur ajouté et autorisé, l'assistant que vous utilisez peut consulter vos stocks, vos lots, vos relevés HACCP, vos clients, vos produits, vos commandes et vos factures, et effectuer certaines écritures après confirmation explicite.

Chaque appel s'exécute sous votre compte utilisateur et reste confiné aux données de votre établissement. Les outils d'écriture fonctionnent en deux temps : un premier appel produit un aperçu, un second appel exécute. Aucun outil de suppression n'est exposé.

Le connecteur ne remplace pas l'application : les opérations qui ne figurent pas dans la liste des outils continuent de se faire depuis Antò.

2. Prérequis

  • Un compte Antò actif. L'autorisation se fait avec ce compte ; le connecteur n'utilise ni clé d'API ni mot de passe partagé.
  • Un profil utilisateur. Les outils de lecture sont ouverts à tous les profils. Les outils d'écriture sont réservés à certains profils métier : la colonne « Profils autorisés » du tableau de la section 5 indique lesquels pour chaque outil.
  • Un client compatible MCP prenant en charge le transport Streamable HTTP et l'authentification OAuth 2.1 pour les serveurs distants. Claude.ai, ChatGPT, Claude Desktop, Claude Code et les autres clients MCP à serveurs distants conviennent.
Option Savé. L'outil factures_impayees nécessite que l'option Savé (comptabilité) soit activée sur l'établissement. Sans elle, l'outil renvoie une erreur explicite ; les autres outils fonctionnent normalement.

3. Connexion

L'adresse du serveur MCP est la même pour tous les clients :

https://mcp.heyanto.fr/mcp/v1

La procédure est toujours la même : ajouter un connecteur distant, coller cette adresse, puis autoriser avec votre compte Antò. Les étapes ci-dessous détaillent les clients les plus courants.

Claude.ai (plan Pro, Team ou Enterprise)

  1. Ouvrez Claude.ai, puis Réglages → Connecteurs.
  2. Cliquez sur Ajouter un connecteur personnalisé.
  3. Collez l'adresse https://mcp.heyanto.fr/mcp/v1, puis autorisez avec votre compte Antò.

ChatGPT (plan Plus, Team ou Enterprise)

  1. Ouvrez ChatGPT, puis Paramètres → Connecteurs.
  2. Ajoutez un connecteur personnalisé.
  3. Collez l'adresse https://mcp.heyanto.fr/mcp/v1, puis validez l'authentification OAuth.

Claude Desktop (Mac et Windows)

  1. Ouvrez les Réglages (⌘,) → Connecteurs.
  2. Cliquez sur Ajouter une intégration.
  3. Collez l'adresse https://mcp.heyanto.fr/mcp/v1, puis autorisez.

Claude Code (interface en ligne de commande)

  1. Dans un terminal, lancez la commande suivante :
    claude mcp add --transport http anto https://mcp.heyanto.fr/mcp/v1
  2. Suivez le flux OAuth affiché dans la console.
  3. Redémarrez votre session Claude Code.

Autres clients MCP

  1. Ouvrez les réglages MCP de votre client.
  2. Ajoutez un serveur distant HTTP.
  3. Renseignez l'adresse https://mcp.heyanto.fr/mcp/v1 et suivez le flux OAuth.
Déconnexion. Retirez le connecteur depuis les réglages de votre client. Votre compte et vos données Antò restent inchangés.

4. Autorisation et sécurité

  • OAuth 2.1 avec PKCE et enregistrement dynamique de client (DCR). L'autorisation passe par votre compte Antò. Aucun mot de passe ni aucune clé d'API n'est transmis au client, et l'accès est révocable à tout moment.
  • Portée limitée à votre établissement. Chaque appel s'exécute dans le contexte de l'établissement auquel votre compte est rattaché. L'isolation est appliquée au niveau de la base de données : un outil ne peut pas atteindre les données d'un autre établissement.
  • Droits par profil. Les outils de lecture sont ouverts à tous les profils. Les outils d'écriture sont restreints aux profils métier concernés, en plus des profils d'administration. Un appel émis par un profil non autorisé est refusé avec le code forbidden.
  • Limite de débit et détection de boucle. Le serveur accepte 30 requêtes par minute et par établissement. Il coupe également les boucles : le même outil rappelé avec les mêmes paramètres trois fois de suite en moins d'une minute est refusé.
  • Journal d'audit. Chaque appel d'outil est journalisé : outil appelé, utilisateur, paramètres, horodatage.
  • Confirmation des écritures. Un outil d'écriture appelé avec confirm:false ne modifie rien : il renvoie un aperçu accompagné d'un jeton de confirmation. Seul un second appel portant ce jeton, avec des paramètres strictement identiques, exécute réellement l'opération. Un jeton n'est valable que pour un utilisateur, un établissement, un outil et un jeu de paramètres donnés, et il expire.
  • Absence de doublon. Les outils d'écriture qui acceptent un identifiant de requête (client_request_id) rejouent le résultat déjà produit au lieu d'écrire une seconde fois. Réutiliser le même identifiant avec des paramètres différents est refusé plutôt qu'exécuté silencieusement.
  • Aucune suppression. Aucun outil de suppression n'est exposé. Les opérations destructives se font depuis l'application.

5. Les 24 outils

Le serveur expose 24 outils : 14 en lecture, 8 en écriture avec confirmation et 2 composites. Le tableau ci-dessous est généré à partir du code du serveur ; il reflète les noms, titres, annotations et droits réellement déclarés au client MCP.

La colonne Confirmation indique si l'outil applique le schéma en deux temps décrit à la section 4. La colonne Profils autorisés indique les profils qui peuvent l'appeler ; « Tous les profils » signifie qu'aucune restriction de rôle ne s'applique.

Les 24 outils exposés par le serveur MCP Antò, dans l'ordre d'enregistrement : lecture, puis écriture, puis composites.
Outil Titre Type Confirmation Profils autorisés Ce qu'il fait
recap_journee Récap de la journée Lecture Non Tous les profils Résumé de l'établissement pour la période demandée : nombre de commandes, BL en attente de signature, lots ouverts, alertes actives (HACCP non signé, stock sous seuil, DLC imminente). À APPELER EN DÉBUT DE SESSION pour avoir une vue d'ensemble. Ne PAS utiliser pour un détail chiffré précis (→ ca_periode) ni pour la liste des alertes (→ alertes). Paramètre : periode (jour ou semaine). Retourne des compteurs agrégés + hints contextuels.
alertes Alertes actives Lecture Non Tous les profils Toutes les alertes actives de l'établissement, filtrable par type. Types : haccp (tâches non signées aujourd'hui), stock (ingrédient sous seuil critique), dlc (lot arrivant à DLC dans 48 h), temp (relevé température hors seuil). Sans filtre : retourne toutes les alertes. Utiliser recap_journee pour une vue d'ensemble chiffrée.
ca_periode Chiffre d'affaires par période Lecture Non admin, SUPER_ADMIN, compta Chiffre d'affaires HT sur une période (total + optionnel ventilation par client ou par produit). Source : factures aux statuts validee/envoyee/payee/payee_partiellement. Préférer recap_journee pour un simple chiffre du jour, ou factures_impayees pour l'encours. Paramètres : debut (YYYY-MM-DD), fin (YYYY-MM-DD, inclusive), grouper_par (optionnel : client ou produit).
stocks_critiques Stocks sous seuil critique Lecture Non Tous les profils Liste les ingrédients dont le stock actuel (currentStock) est inférieur au seuil d'alerte configuré (seuilCritique). Retourne nom, quantité restante, seuil, unité, catégorie, type de stock, ratio. Quand utiliser : dashboard proactif, audit stock, préparation commande fournisseur. Ne pas utiliser pour chercher un ingrédient spécifique (préférer stock_ingredient). Sans paramètre. Retour : liste triée (pire en premier) + count + hints.
stock_ingredient Stock d'un ingrédient Lecture Non Tous les profils État du stock d'un ingrédient spécifique : quantité totale, lots ouverts (numéro, qty restante, DLC, date réception), catégorie, fournisseurs habituels. Recherche fuzzy case-insensitive sur le nom (min 2 caractères). Retourne jusqu'à 5 meilleures correspondances. Quand utiliser : vérifier stock avant production, répondre à une question ciblée. Pour la liste globale des sous-seuil, préférer stocks_critiques. Params : nom (string requis).
lots_dlc Lots proches de la DLC Lecture Non Tous les profils Lots ingrédients arrivant à DLC dans X jours (defaut : 7). Retourne lot (id, numéro), nom ingrédient, DLC, stock restant, daysLeft (jours avant expiration). Trié par DLC ascendante (le plus urgent en premier). Quand utiliser : gestion DLC, anticipation pertes, alerte cuisine. Params : jours (int 0-90, défaut 7). Note : les produits finis (ProductionBatch) n'ont pas de DLC dans le schema — tracés via TraceabilityEvent.
tracer_lot Traçabilité d'un lot Lecture Non Tous les profils Traçabilité complète d'un lot : origine (fournisseur+facture OU recette), productions liées (via ProductionUsage), livraisons clients (via TraceabilityEvent step=delivery). Format lot attendu : cuid OU numéro (internalLotCode pour ingredientLot, lotNumber AAJJMMLL pour batch). Quand utiliser : audits HACCP/DDPP, enquête non-conformité, rappel produit. Params : lot (string min 3). Retour 404 si non trouvé. Graph complet dispo dans l'écran Traçabilité de l'app.
temperatures_jour Relevés de température du jour Lecture Non Tous les profils Relevés de température HACCP du jour (ou d'une date donnée), par zone de stockage (chambre froide, congélateur, etc.). Signale les dépassements de seuil via nonConformity. NE PAS utiliser pour saisir un relevé (→ enregistrer_temperature en Phase 4). Retourne : date, totalReleve, liste des relevés (zone, taskLabel, temperature, heure, horsSeuil, note, operatorId), et horsSeuil agrégé. Params : date (YYYY-MM-DD, défaut aujourd'hui). Note : pas de liste de zones attendues dans le schema actuel.
score_haccp Score de conformité HACCP Lecture Non Tous les profils Score de conformité HACCP pour l'établissement : pourcentage de tâches complétées sur la période, liste des tâches en retard (nettoyage, relevés, contrôles). Permet de savoir si on est à jour pour un contrôle DDPP. Retourne : periode, dateDebut/dateFin, score_percent (0-100), total_taches, completed, non_completed, en_retard (5 premières). Params : periode (jour | semaine | mois, défaut semaine).
chercher_client Rechercher un client Lecture Non Tous les profils Recherche un client par nom, SIREN ou ville. Retourne jusqu'à 5 correspondances avec fiche essentielle : raison sociale, SIREN, adresse, email, téléphone, groupe tarifaire. Pour obtenir les prix de ce client → prix_client. Pour ses commandes → lister_commandes (filtre client_id). Paramètre : recherche (string, min 2 caractères).
prix_client Grille tarifaire d'un client Lecture Non Tous les profils Grille tarifaire d'un client : pour chaque produit, prix HT appliqué récemment (source : 200 dernières lignes de commandes, 1 ligne par produit, la plus récente). Utiliser client_id si connu, sinon nom_client (fuzzy). Au moins l'un des deux est requis. Retourne jusqu'à 50 prix avec remise% de ligne et contrainte réelle (surcharge fixe : conv=1.50€, bio=1.00€, cuit=0€) issue du catalogue produits.
chercher_produit Rechercher un produit Lecture Non Tous les profils Recherche un produit / fiche technique (Recipe) par nom. Retourne jusqu'à 5 matches avec : type de boyau, DLC par défaut (jours), type d'emballage, poids moyen (kg), top 5 ingrédients principaux (nom, quantité par kg, unité). Recherche fuzzy case-insensitive (min 2 caractères). Pour le prix chez un client spécifique → prix_client. Paramètre : recherche (string).
lister_commandes Lister les commandes Lecture Non Tous les profils Commandes (Order) du jour ou de la semaine avec statut et détail. Filtrable par statut (draft, validated, sent, delivered, cancelled) et/ou client_id. Retourne count total + 20 plus récentes avec numéro, client, statut, date, total HT calculé, nb de lignes, nb de BL associés. Ne PAS utiliser pour créer une commande (→ creer_commande en Phase 4).
factures_impayees Factures impayées Lecture Non Tous les profils Factures non réglées de l'établissement avec montant HT/TTC, client, date d'émission, date d'échéance, jours de retard, nombre de relances envoyées. Filtrable par jours_retard_min. Nécessite l'addon Savé (comptabilité) actif sur l'établissement — sinon retourne une erreur explicite.
creer_commande Créer une commande Écriture Oui admin, SUPER_ADMIN, commercial Crée une commande client. Appeler d'ABORD avec `confirm:false` pour prévisualiser (client trouvé, lignes résolues, total HT calculé). Puis rappeler avec `confirm:true` et les MÊMES paramètres + `client_request_id` UUID pour créer. Si le client est inconnu, utiliser chercher_client d'abord pour obtenir son client_id. Prix non fourni → le dernier prix observé pour ce (client × produit) est utilisé (OrderLine). Utiliser creer_commande_complete (Phase 5) pour une création en une seule passe quand toutes les infos sont connues.
creer_bl Créer un bon de livraison Écriture Oui admin, SUPER_ADMIN, commercial Crée un bon de livraison. Deux modes : (a) depuis une commande existante via `commande_id` — les lignes sont reprises automatiquement ; (b) manuellement via `client_id` + `lignes` — un Order support est créé puis rattaché au BL. Pattern 2-step : `confirm:false` pour prévisualiser puis `confirm:true` + `client_request_id` pour créer. Utiliser creer_bl_complet (Phase 5) pour créer + décrémenter le stock + tracer en une passe.
lancer_production Lancer une production Écriture Oui admin, SUPER_ADMIN, production, OPERATEUR Lance une fabrication depuis une recette. Vérifie la disponibilité des ingrédients en stock (FIFO par DLC asc) — on peut forcer un lot par ingrédient via `lots_ingredients`. Pattern 2-step : `confirm:false` → preview (recette, quantité, lots sélectionnés, stock suffisant oui/non, coût matière estimé) ; `confirm:true` → crée le ProductionBatch (status=in_progress) et les ProductionUsage. Le stock sera décrémenté à la clôture du lot (pas ici). Format lotNumber : AAJJMMLL (ex : 26042001).
enregistrer_temperature Enregistrer une température HACCP Écriture Oui admin, SUPER_ADMIN, commercial Enregistre un relevé de température HACCP (chambre froide, congélateur, etc.) sur la checklist du jour. Deux modes de résolution : `zone_id` (exact, HaccpTaskEntry.id) ou `zone_nom` (fuzzy contains sur taskLabel). Pattern 2-step : `confirm:false` → preview ; `confirm:true` → enregistre et marque la tâche faite. Idéal pour la saisie vocale ('enregistre 4.2 degrés chambre froide').
modifier_prix Modifier un prix client Écriture Oui admin, SUPER_ADMIN, commercial Modifie le tarif d'un client pour un produit dans la grille de prix par client (clients_tarifs). Appeler d'ABORD avec `confirm:false` pour prévisualiser (prix actuel → nouveau, delta). Puis rappeler avec `confirm:true`, les MÊMES paramètres + un `client_request_id` UUID pour appliquer. Identifier client et produit par leur UUID si connu, sinon par nom (fuzzy). La remise est recalculée automatiquement vs le prix catalogue. Pour lire la grille existante, utiliser prix_client.
creer_facture Créer une facture depuis des BL Écriture Oui admin, SUPER_ADMIN, compta Génère une facture à partir d'un ou plusieurs bons de livraison (DeliveryNote) du MÊME client. Appeler d'ABORD avec `confirm:false` pour prévisualiser (client, nb BL, total HT estimé). Puis rappeler avec `confirm:true`, les MÊMES paramètres + un `client_request_id` UUID pour générer. `valider:false` (défaut) crée un brouillon ; `valider:true` numérote et verrouille la facture (nécessite l'onboarding module SAVE). Réservé aux profils admin / compta.
creer_devis Créer un devis Écriture Oui admin, SUPER_ADMIN, commercial Crée un devis (Quote) pour un client. Appeler d'ABORD avec `confirm:false` pour prévisualiser (totaux HT/TVA/TTC recalculés serveur-side). Puis rappeler avec `confirm:true`, les MÊMES paramètres + un `client_request_id` UUID pour créer. Identifier le client par `client_id` (UUID legacy, le nom est dérivé) ou par `client_nom` libre. Chaque ligne : `produit_id` (optionnel, valide l'appartenance), `designation`, `quantite`, `prix_unitaire_ht`, `remise_pct`. La TVA est relue depuis la fiche produit. Réservé aux profils admin / commercial.
creer_avoir Créer un avoir d'annulation Écriture Oui admin, SUPER_ADMIN, compta Crée un avoir d'ANNULATION TOTALE sur une facture (génère une facture type avoir à montants négatifs liée à l'origine). Appeler d'ABORD avec `confirm:false` pour prévisualiser (facture, client, montant à créditer). Puis rappeler avec `confirm:true`, les MÊMES paramètres + un `client_request_id` UUID. La facture doit être validée/envoyée et NON payée ; `motif` obligatoire (min. 3 caractères). Réservé aux profils admin / compta.
creer_commande_complete Créer une commande complète Composite Oui admin, SUPER_ADMIN, commercial Crée une commande client COMPLÈTE en une transaction atomique : entête + lignes + numérotation. Si une ligne échoue (prix introuvable, produit invalide), tout est rollback. PRÉFÉRER ce tool quand le client et toutes les lignes sont connues d'un coup (pas d'itération avec l'utilisateur). Pour une création interactive ou incrémentale, utiliser creer_commande (Phase 4).
creer_bl_complet Créer un BL complet (stock décrémenté) Composite Oui admin, SUPER_ADMIN, commercial Crée un bon de livraison COMPLET en une transaction atomique : (1) entête BL, (2) reprise ou saisie des lignes, (3) décrément du stock MATIÈRE par IngredientLot FIFO (ou lot_id fourni), (4) événement de traçabilité par ligne livrée, (5) si `commande_id` fourni : marque l'Order `delivered`. `lot_id` désigne uniquement le lot matière consommé ; `production_batch_id` désigne le lot PRODUIT livré et alimente DeliveryNoteLine.lotId. Sans lot produit explicite, lotId reste null. Si le stock est insuffisant, TOUT est rollback. PRÉFÉRER ce tool pour un BL complet sans itération. Pour un flow interactif ou avec validation intermédiaire, utiliser creer_bl (Phase 4).

6. Limites

  • 30 requêtes par minute et par établissement. Au-delà, le serveur répond une erreur de limite de débit et invite à réessayer après une minute.
  • Détection de boucle. Le même outil appelé avec les mêmes paramètres trois fois de suite en moins d'une minute est refusé.
  • Listes bornées. Les recherches de clients, de produits et d'ingrédients renvoient au plus 5 correspondances ; lister_commandes renvoie le total et les 20 commandes les plus récentes ; prix_client renvoie au plus 50 prix.
  • Période bornée. ca_periode refuse les fenêtres de plus de 24 mois.
  • Option Savé. factures_impayees nécessite l'option Savé activée sur l'établissement.
  • Écritures en deux appels. Aucune écriture ne s'exécute en un seul appel : il faut d'abord obtenir un aperçu, puis confirmer avec le jeton renvoyé.
  • Recettes composées. lancer_production ne prend pas en charge les recettes contenant des sous-recettes composées ; ces productions se lancent depuis l'application.

7. Dépannage

Les erreurs de transport (authentification, limite de débit) sont renvoyées en HTTP. Les erreurs d'outil sont renvoyées dans la réponse de l'outil, sous la forme d'un code et d'un message. Voici les codes que vous pouvez rencontrer.

Codes d'erreur renvoyés par le serveur MCP Antò, cause probable et action à mener.
Code Cause Action
invalid_token (HTTP 401) Jeton OAuth absent, expiré ou invalide. Relancez l'autorisation depuis les réglages du connecteur dans votre client.
rate_limited (HTTP 429) Plus de 30 requêtes en une minute pour l'établissement. Attendez une minute avant de relancer la demande.
loop_detected (HTTP 429) Le même outil a été appelé avec les mêmes paramètres trois fois de suite. Vérifiez les paramètres de la demande, puis reformulez-la.
forbidden Votre profil n'est pas autorisé à utiliser cet outil. Le message indique les profils requis. Faites réaliser l'opération par un profil autorisé, ou depuis l'application.
validation_failed Un paramètre est manquant, mal formé ou hors des valeurs acceptées. Le message précise le champ en cause. Corrigez le paramètre et relancez.
not_found La ressource demandée (client, produit, lot, facture, commande) n'existe pas dans votre établissement. Vérifiez l'identifiant ou le libellé, au besoin avec un outil de recherche.
ambiguous_match Plusieurs clients, produits ou zones correspondent au libellé fourni. Précisez l'identifiant exact plutôt que le nom.
confirmation_required Une écriture a été demandée sans jeton de confirmation valide. Rappelez d'abord l'outil avec confirm:false pour obtenir un jeton, puis renvoyez ce jeton avec des paramètres identiques.
confirmation_expired La fenêtre de confirmation a expiré entre l'aperçu et l'exécution. Redemandez un aperçu, puis confirmez à nouveau.
idempotency_conflict L'identifiant de requête a déjà servi pour des paramètres différents, ou appartient à un autre utilisateur. Relancez l'opération avec un nouvel identifiant de requête.
operation_in_progress Une exécution identique est déjà en cours. Patientez quelques secondes, puis retentez avec le même identifiant de requête.
manual_reconciliation_required Une tentative précédente a été interrompue après avoir potentiellement écrit. Vérifiez l'état dans l'application avant de retenter : rejouer risquerait de créer un doublon.
addon_not_active L'option Savé (comptabilité) n'est pas activée sur l'établissement. Activez l'option Savé, ou consultez les factures depuis l'application.
range_too_large La période demandée dépasse 24 mois. Restreignez la période.
stock_insufficient Le stock disponible ne couvre pas la production ou la livraison demandée. Le message liste les ingrédients manquants. Réapprovisionnez ou réduisez les quantités.
price_missing Aucun prix connu pour ce couple client et produit. Fournissez explicitement le prix unitaire HT dans la demande.
recipe_empty La recette visée ne contient aucun ingrédient. Complétez la fiche technique dans l'application avant de lancer la production.
composite_recipe_unsupported La recette contient des sous-recettes composées. Lancez cette production depuis l'application.
bl_deja_genere Un bon de livraison actif existe déjà pour cette commande. Utilisez le bon de livraison existant, ou reprenez l'opération depuis l'application.
multiple_clients Les bons de livraison sélectionnés n'appartiennent pas tous au même client. Facturez un client à la fois.
not_creditable Le statut de la facture n'autorise pas la création d'un avoir. Un avoir d'annulation ne s'applique qu'à une facture validée ou envoyée.
facture_payee La facture est déjà réglée, totalement ou partiellement. Traitez la régularisation depuis l'application.
invoice_failed La génération de la facture a échoué. Vérifiez les bons de livraison sélectionnés, puis retentez. Si l'erreur persiste, contactez le support.
internal_error Erreur interne du serveur ; le détail technique n'est pas exposé au client. Retentez plus tard. Si l'erreur persiste, contactez le support en indiquant l'outil et l'heure de l'appel.

8. Support

Pour toute question sur le connecteur, écrivez à contact@heyanto.fr ou utilisez le formulaire de contact. Indiquez l'outil concerné, le message d'erreur reçu et l'heure approximative de l'appel : cela permet de retrouver l'entrée correspondante dans le journal d'audit.

Documents de référence

Pages liées