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
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.
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 :
- L'agent découvre les points d'accès OAuth d'Augias sur
/.well-known/oauth-authorization-serveret s'enregistre de lui-même. - Votre navigateur ouvre la page de consentement d'Augias. Connectez-vous si besoin.
- 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:readest toujours accordée ;mcp:writeest facultative et n'apparaît que si l'agent l'a demandée.
- 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.
- Claude Desktop
- Claude Code
- Cursor
- Codex CLI
- Goose
- MCP Inspector
- Autres agents
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.
Dans un terminal :
claude mcp add --transport http augias https://<votre-instance-augias>/_mcp
Le premier appel d'outil d'une session déclenche le parcours OAuth dans votre navigateur.
Pour rendre la connexion disponible dans tous vos projets, ajoutez --scope user :
claude mcp add --scope user --transport http augias https://<votre-instance-augias>/_mcp
Ouvrez Settings → MCP → Add new MCP server et ajoutez :
{
"mcpServers": {
"augias": {
"url": "https://<votre-instance-augias>/_mcp"
}
}
}
Cursor vous demande l'autorisation dans le navigateur à la première utilisation.
Ajoutez le serveur à ~/.codex/config.toml :
[mcp_servers.augias]
url = "https://<votre-instance-augias>/_mcp"
Redémarrez Codex. La première requête déclenche l'OAuth dans le navigateur.
Dans Goose, ajoutez une extension de type Remote (HTTP) pointant sur votre adresse /_mcp. Goose gère seul l'enregistrement dynamique et l'OAuth.
L'inspecteur officiel est le moyen le plus rapide de tester une connexion sans configurer d'agent complet :
npx @modelcontextprotocol/inspector https://<votre-instance-augias>/_mcp
Il déroule l'enregistrement dynamique du client, ouvre la page de consentement dans votre navigateur, puis vous laisse dans une interface où lister et appeler chaque outil du serveur.
Tout client MCP qui accepte le transport Streamable HTTP avec OAuth 2.1 (code d'autorisation + PKCE) et l'enregistrement dynamique des clients (RFC 7591) peut se connecter sans rien régler de plus :
- Adresse :
https://<votre-instance-augias>/_mcp - Authentification : découverte automatiquement sur
/.well-known/oauth-authorization-server - Portées : demandez
mcp:readet, si l'agent doit modifier des données,mcp:write
Un client incapable d'enregistrement dynamique ou d'OAuth ne peut pas utiliser ce serveur : il n'y a volontairement pas de repli par clé d'API fixe.
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.
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)
| Outil | Rôle |
|---|---|
list_resource | Liste les fiches de toute ressource (facture, devis, client, contact, paiement, taxe, facture récurrente), avec filtres et pagination. |
get_resource | Récupère une fiche par son identifiant. |
list_invoices_by_status | Liste les factures d'un statut (brouillon, en attente, payée, en retard, etc.). |
list_overdue_invoices | Liste les factures en retard, éventuellement pour un client. |
list_quotes_by_status | Liste les devis d'un statut. |
list_recurring_invoices | Liste les factures récurrentes, éventuellement par statut et par client. |
list_payment_methods | Liste les moyens de paiement configurés pour l'entreprise active. |
list_tax_rates | Liste les taux de taxe de l'entreprise active. |
list_workflow_transitions | Liste les transitions de statut possibles sur une fiche. |
get_company_info | Renvoie l'identifiant, le nom et la devise par défaut de l'entreprise active. |
get_client_summary | Total facturé, impayé, total payé et nombres de documents pour un client. |
get_dashboard_stats | Totaux impayés et en retard par devise, nombre de factures par statut, nombre de clients. |
get_invoice_status_distribution | Nombre de factures par statut. |
get_revenue_by_period | Chiffre d'affaires des paiements encaissés entre deux dates, par jour, semaine ou mois. |
get_total_outstanding | Total impayé par devise, éventuellement pour un client. |
get_total_overdue | Total en retard par devise, éventuellement pour un client. |
Outils d'écriture (mcp:write)
| Outil | Rôle |
|---|---|
create_resource | Crée une ressource simple : client, contact ou tax. |
update_resource | Modifie les champs simples d'un client, d'un contact ou d'une taxe. |
delete_resource | Supprime un client, un contact ou une taxe. |
create_invoice | Crée une facture pour un client, avec ses lignes, une remise, une échéance et des contacts. |
create_quote | Crée un devis pour un client, avec ses lignes, une remise, une échéance et des contacts. |
create_recurring_invoice | Crée une facture récurrente quotidienne, hebdomadaire, mensuelle ou annuelle. |
clone_invoice | Duplique une facture en un nouveau brouillon avec les mêmes lignes. |
clone_quote | Duplique un devis en un nouveau brouillon avec les mêmes lignes. |
convert_quote_to_invoice | Transforme un devis en nouvelle facture, avec client, lignes et totaux. |
apply_invoice_transition | Applique une transition de statut (accept, cancel, overdue, pay, reopen, archive) à une facture. |
apply_quote_transition | Applique une transition de statut (send, accept, decline, cancel, reopen, archive) à un devis. |
apply_recurring_transition | Applique une transition de statut à une facture récurrente. |
record_payment | Enregistre un paiement hors ligne sur une facture et la passe payée. |
add_contact | Ajoute un contact (e-mail et nom facultatif) à un client existant. |
send_invoice_reminder | Envoie aux contacts d'une facture une relance manuelle par e-mail. |
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:migratepour 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 :
AUGIAS_MCP_SESSION_STORE=cache
AUGIAS_MCP_SESSION_CACHE_POOL=cache.app
| Stockage | Quand l'utiliser |
|---|---|
file | Par défaut. Un seul nœud. |
memory | Développement local seulement : les sessions repartent de zéro à chaque redémarrage du worker. |
cache | Plusieurs nœuds. Faites pointer AUGIAS_MCP_SESSION_CACHE_POOL vers un pool Redis. |
framework | Reprend 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.