Aller au contenu principal

Serveur MCP

Augias intègre un serveur Model Context Protocol (MCP). Un agent d'IA qui s'y connecte peut lire vos factures, devis, clients et paiements et, si vous lui donnez l'accès en écriture, en créer et en modifier pour vous.

Chaque connexion est liée à une seule entreprise au moment du consentement et authentifiée par OAuth 2.1. Un agent connecté à l'entreprise A ne voit jamais les données de l'entreprise B, même si vous êtes membre des deux.

Adresse du serveur​

Le serveur MCP est toujours servi sur le chemin /_mcp de votre instance :

https://<votre-instance-augias>/_mcp
info

Le transport est Streamable HTTP (le transport standard des serveurs MCP distants), et non stdio. Tout agent qui accepte les serveurs MCP distants avec OAuth peut se connecter, sans proxy ni script intermédiaire.

attention

Une instance auto-hébergée doit être joignable en HTTPS pour qu'OAuth fonctionne. Le parcours passe par des redirections du navigateur : localhost convient pour des essais en local, mais une adresse de réseau privé en général non. Utilisez un tunnel (Cloudflare Tunnel, ngrok) pour exposer une instance de développement à un agent hébergé.

L'autorisation​

Aucune clé d'API à coller. À sa première connexion, l'agent vous fait suivre un parcours de consentement OAuth classique :

  1. L'agent découvre les points d'accès OAuth d'Augias sur /.well-known/oauth-authorization-server et s'enregistre de lui-même.
  2. Votre navigateur ouvre la page de consentement d'Augias. Connectez-vous si besoin.
  3. Sur l'écran de consentement, vous choisissez :
    • l'entreprise sur laquelle l'agent agira (si vous en avez plusieurs) ;
    • les portées accordées : mcp:read est toujours accordée ; mcp:write est facultative et n'apparaît que si l'agent l'a demandée.
  4. Une fois l'accord donné, l'agent reçoit un jeton d'accès (valable 24 heures) et un jeton de renouvellement (valable 90 jours, renouvelé à chaque usage). Les jetons sont liés à l'entreprise et aux portées choisies ; ce lien ne peut plus changer sans nouveau consentement.

Vous pouvez consulter et révoquer chaque agent connecté à tout moment dans Profil → Applications connectées (/profile/connected-apps).

Connecter votre agent​

Les étapes dépendent de l'agent. L'adresse est toujours celle de votre /_mcp ; OAuth s'occupe du reste.

Dans Claude Desktop, ouvrez Settings → Connectors → Add custom connector et saisissez :

  • Name : Augias
  • URL : https://<votre-instance-augias>/_mcp

Claude ouvre une fenêtre de navigateur pour terminer l'OAuth. Acceptez l'écran de consentement : le connecteur est prêt dans toutes vos conversations.

astuce

Une fois connecté, demandez à l'agent quelque chose comme « Liste mes factures impayées » ou « Montre le chiffre d'affaires de ce mois » pour vérifier que tout fonctionne.

Choisir l'entreprise​

Si vous êtes membre de plusieurs entreprises, l'écran de consentement propose de choisir. Le choix est inscrit dans le jeton d'accès : pour faire travailler le même agent sur une autre entreprise, révoquez-le dans Profil → Applications connectées et reconnectez-le.

astuce

Vous pouvez connecter le même agent à plusieurs entreprises en l'enregistrant plusieurs fois sous des noms différents, par exemple augias-acme et augias-perso. Chaque enregistrement a son consentement et son jeton : l'agent agit sur l'une ou l'autre entreprise selon la connexion choisie.

Outils disponibles​

Le serveur expose le même jeu d'outils à tous les agents. Les outils qui demandent mcp:write ne réussissent que si vous avez accordé l'écriture au consentement.

Outils de lecture (mcp:read)​

OutilRôle
list_resourceListe les fiches de toute ressource (facture, devis, client, contact, paiement, taxe, facture récurrente), avec filtres et pagination.
get_resourceRécupère une fiche par son identifiant.
list_invoices_by_statusListe les factures d'un statut (brouillon, en attente, payée, en retard, etc.).
list_overdue_invoicesListe les factures en retard, éventuellement pour un client.
list_quotes_by_statusListe les devis d'un statut.
list_recurring_invoicesListe les factures récurrentes, éventuellement par statut et par client.
list_payment_methodsListe les moyens de paiement configurés pour l'entreprise active.
list_tax_ratesListe les taux de taxe de l'entreprise active.
list_workflow_transitionsListe les transitions de statut possibles sur une fiche.
get_company_infoRenvoie l'identifiant, le nom et la devise par défaut de l'entreprise active.
get_client_summaryTotal facturé, impayé, total payé et nombres de documents pour un client.
get_dashboard_statsTotaux impayés et en retard par devise, nombre de factures par statut, nombre de clients.
get_invoice_status_distributionNombre de factures par statut.
get_revenue_by_periodChiffre d'affaires des paiements encaissés entre deux dates, par jour, semaine ou mois.
get_total_outstandingTotal impayé par devise, éventuellement pour un client.
get_total_overdueTotal en retard par devise, éventuellement pour un client.

Outils d'écriture (mcp:write)​

OutilRôle
create_resourceCrée une ressource simple : client, contact ou tax.
update_resourceModifie les champs simples d'un client, d'un contact ou d'une taxe.
delete_resourceSupprime un client, un contact ou une taxe.
create_invoiceCrée une facture pour un client, avec ses lignes, une remise, une échéance et des contacts.
create_quoteCrée un devis pour un client, avec ses lignes, une remise, une échéance et des contacts.
create_recurring_invoiceCrée une facture récurrente quotidienne, hebdomadaire, mensuelle ou annuelle.
clone_invoiceDuplique une facture en un nouveau brouillon avec les mêmes lignes.
clone_quoteDuplique un devis en un nouveau brouillon avec les mêmes lignes.
convert_quote_to_invoiceTransforme un devis en nouvelle facture, avec client, lignes et totaux.
apply_invoice_transitionApplique une transition de statut (accept, cancel, overdue, pay, reopen, archive) à une facture.
apply_quote_transitionApplique une transition de statut (send, accept, decline, cancel, reopen, archive) à un devis.
apply_recurring_transitionApplique une transition de statut à une facture récurrente.
record_paymentEnregistre un paiement hors ligne sur une facture et la passe payée.
add_contactAjoute un contact (e-mail et nom facultatif) à un client existant.
send_invoice_reminderEnvoie aux contacts d'une facture une relance manuelle par e-mail.
remarque

L'agent agit toujours au nom de l'utilisateur qui a donné son accord, sur l'entreprise choisie au consentement. Un company ou company_id passé par l'agent dans un appel d'écriture est ignoré : l'entreprise active est imposée côté serveur.

Gérer les applications connectées​

Connecté, ouvrez /profile/connected-apps pour :

  • voir chaque agent autorisé, l'entreprise à laquelle il est lié et ses portées ;
  • révoquer un agent. La révocation invalide aussitôt ses jetons d'accès et de renouvellement ; sa requête suivante échoue en 401 invalid_token, et un nouveau consentement est nécessaire.

Révoquer un agent ne supprime pas son enregistrement : il peut se reconnecter plus tard sans refaire l'enregistrement dynamique.

Auto-hébergement : activer le serveur​

Le serveur MCP est fourni avec Augias et activé par défaut. Les seuls prérequis, une fois pour toutes :

  • Les clés de signature OAuth. Lancez une fois bin/console mcp:keys:generate ; les clés sont écrites dans $AUGIAS_CONFIG_DIR/oauth/ et survivent aux redéploiements. Le lanceur du binaire (augias run) le fait seul au premier démarrage.
  • Les migrations de base de données. Lancez bin/console doctrine:migrations:migrate pour créer les tables OAuth et des jetons.

Avec plusieurs nœuds, sortez le stockage des sessions MCP du disque local pour que les sessions passent d'un nœud à l'autre :

.env.local
AUGIAS_MCP_SESSION_STORE=cache
AUGIAS_MCP_SESSION_CACHE_POOL=cache.app
StockageQuand l'utiliser
filePar défaut. Un seul nœud.
memoryDéveloppement local seulement : les sessions repartent de zéro à chaque redémarrage du worker.
cachePlusieurs nœuds. Faites pointer AUGIAS_MCP_SESSION_CACHE_POOL vers un pool Redis.
frameworkReprend le gestionnaire de sessions Symfony de votre application.

Dépannage​

Le navigateur s'ouvre mais le consentement échoue avec « company required »

Vous êtes membre de plusieurs entreprises et n'en avez choisi aucune. Relancez la connexion depuis l'agent et choisissez une entreprise sur l'écran de consentement.

Les outils qui modifient des données renvoient « insufficient scope »

L'agent n'a demandé, ou vous n'avez accordé, que mcp:read. Révoquez la connexion dans Profil → Applications connectées et reconnectez-vous, en vérifiant que l'agent demande mcp:write et que vous cochez l'écriture sur l'écran de consentement.

Les requêtes renvoient désormais 401 invalid_token

Le jeton a expiré ou a été révoqué. La plupart des agents le renouvellent seuls ; sinon, reconnectez-vous depuis les réglages MCP de l'agent. Vérifiez dans Profil → Applications connectées que l'agent n'a pas été révoqué.

Auto-hébergement : la redirection OAuth échoue

Augias doit être joignable en HTTPS depuis le navigateur de l'agent, sous le nom d'hôte configuré dans l'agent. Un mélange http/https, ou un nom d'hôte différent entre l'adresse configurée et la cible de redirection, casse le parcours.