Serveur MCP

Le serveur MCP de Frihet implémente le Model Context Protocol afin que les assistants IA puissent interagir directement avec votre ERP. Créer des factures, enregistrer des dépenses, consulter des clients ou gérer des devis — tout depuis votre IDE ou terminal, en langage naturel.

Toi :      "Crée une facture pour TechStart SL, 40 heures de consultation à 75 EUR/heure, échéance 1er mars"
Claude :  Fait. Facture INV-2026-089 créée. Total : 3 000,00 EUR + 21 % TVA = 3 630,00 EUR.

Ce à quoi s'attendre (et ce à quoi ne pas s'attendre)

Le serveur MCP est un pont stateless entre votre assistant IA et l'API REST de Frihet. Chaque appel d'outil est traduit en une requête HTTP vers l'API.

Ce qu'il FAIT :

CRUD complet sur les factures, dépenses, clients, produits, devis et webhooks
Recherche de factures par nom de client
Accès aux données de référence (taux d'imposition, calendrier fiscal, catégories)
Workflows guidés (clôture mensuelle, préparation fiscale, suivi des débiteurs)

Ce qu'il NE FAIT PAS :

OCR de documents (cela est géré par l'assistant IA au sein de l'application)
Génération de PDFs (utilise directement l'API REST : GET /v1/invoices/:id/pdf)
Traitement des paiements (les encaissements sont gérés via Stripe Connect dans l'application)

Prérequis

Compte Frihet avec accès à l'API (plans payants)
Clé API générée depuis le panneau

Obtenir la clé API

Connectez-vous à app.frihet.io
Allez dans Paramètres > Développeurs > Clés API
Cliquez sur Créer une clé API
Copiez la clé (elle commence par fri_) — elle n'est affichée qu'une seule fois

Installation

Universel (plus de 30 agents)

La manière la plus rapide d'installer le serveur MCP et la compétence métier :

npx skills add Frihet-io/frihet-mcp

Fonctionne avec Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, et plus de 30 autres agents.

MCP Registry

Le serveur est enregistré sous io.frihet/erp dans le MCP Registry officiel. Les clients MCP compatibles avec le registre peuvent le découvrir et l'installer automatiquement par son nom canonique.

npx direct

npx -y @frihet/mcp-server@latest

Vous n'avez pas besoin d'installer quoi que ce soit globalement. npx télécharge et exécute automatiquement la dernière version.

Configuration manuelle

Il existe deux modes de connexion : local (le serveur s'exécute sur votre machine via npx) et distant (connexion directe à mcp.frihet.io, sans rien installer).

Local (stdio)

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server@latest"],
      "env": {
        "FRIHET_API_KEY": "fri_tu_clave_aqui"
      }
    }
  }
}

Distant (streamable-http)

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_tu_clave_aqui"
      }
    }
  }
}

Configuration par client

La structure JSON est identique pour tous les clients. Seul l'emplacement du fichier de configuration change.

Client	Fichier de configuration
Claude Code	`~/.claude/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` ou `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	Configuration de VS Code ou `.cline/mcp.json`
Codex CLI	`~/.codex/config.toml` (section MCP)

astuce

Si vous utilisez Claude Code, vous pouvez ajouter le serveur avec une seule commande :

claude mcp add frihet -- npx -y @frihet/mcp-server@latest

Ensuite, configurez la variable FRIHET_API_KEY dans le fichier ~/.claude/mcp.json résultant.

Variables d'environnement

Variable	Requise	Valeur par défaut
`FRIHET_API_KEY`	Oui	--
`FRIHET_API_URL`	Non	`https://api.frihet.io/v1`
`FRIHET_MCP_DEBUG`	Non	`0`

FRIHET_API_URL est utile si vous ciblez un environnement de staging ou une instance personnalisée. Elle doit être https:// avec un nom d'hôte sous frihet.io.
FRIHET_MCP_DEBUG=1 active les logs de niveau debug (utile pour diagnostiquer les problèmes).

Flux OAuth

Le serveur MCP prend en charge l'authentification OAuth en plus de la clé API manuelle. Lorsqu'un client MCP initialise le flux OAuth :

L'utilisateur s'authentifie via Firebase Auth (email, Google, GitHub ou Microsoft)
Le client envoie le jeton de session à POST /api/oauth/api-key
Le serveur provisionne une nouvelle clé fri_xxx... étiquetée "MCP OAuth" avec une expiration de 365 jours
La clé est automatiquement utilisée pour les appels ultérieurs

Cela permet aux utilisateurs de connecter le serveur MCP sans copier les clés manuellement.

Outils disponibles (44)

Le serveur expose 52 outils organisés en 7 catégories. Chaque outil inclut une sortie structurée (outputSchema + structuredContent) pour que les assistants puissent analyser les réponses de manière fiable, en plus d'annotations de sécurité et de contenu. Bilingue (EN/ES).

Factures (6 outils)

Outil	Description	Paramètres clés
`list_invoices`	Liste les factures avec pagination	`limit`, `offset`
`get_invoice`	Obtient une facture par ID	`id`
`create_invoice`	Crée une facture avec des lignes de détail	`clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`
`update_invoice`	Met à jour les champs d'une facture (partiel)	`id`, et tout champ à modifier
`delete_invoice`	Supprime une facture de manière permanente	`id`
`search_invoices`	Recherche des factures par nom de client	`clientName`, `limit`, `offset`

Statuts possibles d'une facture : draft, sent, paid, overdue, cancelled

Dépenses (5 outils)

Outil	Description	Paramètres clés
`list_expenses`	Liste les dépenses avec pagination	`limit`, `offset`
`get_expense`	Obtient une dépense par ID	`id`
`create_expense`	Enregistre une nouvelle dépense	`description`, `amount`, `category`, `date`, `vendor`, `taxDeductible`
`update_expense`	Modifie une dépense existante (partiel)	`id`, et tout champ à modifier
`delete_expense`	Supprime une dépense de manière permanente	`id`

Clients (5 outils)

Outil	Description	Paramètres clés
`list_clients`	Liste tous les clients	`limit`, `offset`
`get_client`	Obtient un client par ID	`id`
`create_client`	Enregistre un nouveau client	`name`, `email`, `phone`, `taxId`, `address` (street, city, state, postalCode, country)
`update_client`	Met à jour les données d'un client (partiel)	`id`, et tout champ à modifier
`delete_client`	Supprime un client de manière permanente	`id`

Produits (5 outils)

Outil	Description	Paramètres clés
`list_products`	Liste les produits et services	`limit`, `offset`
`get_product`	Obtient un produit par ID	`id`
`create_product`	Crée un produit ou service	`name`, `unitPrice`, `description`, `taxRate`
`update_product`	Modifie un produit existant (partiel)	`id`, et tout champ à modifier
`delete_product`	Supprime un produit de manière permanente	`id`

Devis (5 outils)

Outil	Description	Paramètres clés
`list_quotes`	Liste les devis	`limit`, `offset`
`get_quote`	Obtient un devis par ID	`id`
`create_quote`	Crée un devis pour un client	`clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status`
`update_quote`	Modifie un devis (partiel)	`id`, et tout champ à modifier
`delete_quote`	Supprime un devis de manière permanente	`id`

Statuts possibles d'un devis : draft, sent, accepted, rejected, expired

Webhooks (5 outils)

Outil	Description	Paramètres clés
`list_webhooks`	Liste les webhooks configurés	`limit`, `offset`
`get_webhook`	Obtient la configuration d'un webhook	`id`
`create_webhook`	Enregistre un endpoint de webhook	`url`, `events[]`, `active`, `secret`
`update_webhook`	Modifie un webhook existant	`id`, et tout champ à modifier
`delete_webhook`	Supprime un webhook de manière permanente	`id`

Événements webhook disponibles : invoice.created, invoice.updated, invoice.deleted, invoice.paid, expense.created, expense.updated, expense.deleted, client.created, client.updated, client.deleted, product.created, product.updated, product.deleted, quote.accepted. Consultez les Webhooks pour le format du payload et la vérification HMAC.

Ressources disponibles (8)

Les ressources MCP sont des données de référence que l'assistant peut consulter sans faire d'appels à l'API. Elles sont statiques et toujours accessibles.

Ressource	URI	Description
Schéma API	`frihet://api/schema`	Résumé des endpoints, authentification, limites de débit et codes d'erreur
Taux d'imposition	`frihet://tax/rates`	TVA (21/10/4%), IGIC (7/3/0%), IPSI, intracommunautaire, IRPF (15%/7%)
Calendrier fiscal	`frihet://tax/calendar`	Dates de dépôt trimestriel (Modèle 303, 130, 420, 390)
Catégories de dépense	`frihet://config/expense-categories`	8 catégories avec règles de déductibilité et traitement fiscal
Statuts de facture	`frihet://config/invoice-statuses`	Flux d'états (brouillon, envoyée, payée, en retard, annulée) avec déclencheurs
Fournisseurs	`frihet://config/vendors`	Liste des fournisseurs enregistrés avec données fiscales et de contact
Intégrations actives	`frihet://config/integrations`	État des intégrations connectées (Stripe, Shopify, etc.)
Configuration de l'entreprise	`frihet://config/business`	Données fiscales de l'entreprise, zone fiscale, devise et préférences

Prompts disponibles (7)

Les prompts sont des workflows guidés que l'assistant exécute étape par étape. Ils sont invoqués par leur nom.

Prompt	Description	Paramètres
`monthly-close`	Clôture mensuelle : vérifie les factures impayées, catégorise les dépenses, vérifie les obligations fiscales, génère un résumé	`month` (optionnel)
`onboard-client`	Intégration client : détermine le type d'imposition selon l'emplacement, crée l'enregistrement, génère un devis de bienvenue	`clientName`, `country`, `region`
`quarterly-tax-prep`	Préparation fiscale trimestrielle : recueille les factures, calcule la TVA/IGIC, génère un aperçu du Modèle 303/130	`quarter`, `fiscalZone`
`overdue-followup`	Suivi des débiteurs : identifie les factures échues, les regroupe par client, rédige des messages de recouvrement	—
`expense-batch`	Traitement des dépenses en lot : catégorise, applique les impôts, vérifie la déductibilité, crée avec confirmation	`fiscalZone`
`vendor-analysis`	Analyse des fournisseurs : regroupe les dépenses par fournisseur, calcule les totaux, identifie les tendances et opportunités d'économie	`period` (optionnel)
`business-health`	Diagnostic de la santé de l'entreprise : KPIs clés, comparaison avec le mois précédent, alertes et recommandations actionnables	`month` (optionnel)

astuce

Vous pouvez invoquer un prompt directement : "Exécute la clôture mensuelle de février" ou "Prépare les impôts du T1".

Exemples d'utilisation

Ce sont des requêtes réelles en langage naturel que l'assistant traduit en appels d'outils MCP.

Créer une facture

"Crée une facture pour Acme SL avec 10 heures de consultation à 95 EUR/heure, échéance 15 mars"

L'assistant appelle create_invoice avec clientName: "Acme SL", une ligne de détail (10 x 95) et dueDate: "2026-03-15". Il calcule automatiquement le total.

Enregistrer une dépense

"Enregistre une dépense de 59.99 EUR pour Adobe Creative Cloud, catégorie logiciel, déductible"

Appelle create_expense avec description, amount: 59.99, category: "software" et taxDeductible: true.

Rechercher les factures d'un client

"Recherche toutes les factures de TechStart SL"

Appelle search_invoices avec clientName: "TechStart SL" et renvoie les correspondances avec leurs totaux et statuts.

Consulter les débiteurs

"Montre-moi toutes les factures impayées"

Appelle list_invoices et filtre par status: "sent" ou "overdue", affichant les factures échues triées par montant.

Enregistrer un client

"Nouveau client : Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"

Appelle create_client avec nom, NIF, email et adresse.

Configurer l'automatisation

"Crée un webhook pour notifier https://mi-app.com/hook lorsqu'une facture est payée"

Appelle create_webhook avec url et events: ["invoice.paid"].

Mettre à jour un produit

"Augmente le prix de l'heure de consultation à 85 EUR"

Appelle update_product avec l'id du produit et unitPrice: 85. Seul le champ indiqué est modifié.

Observabilité

Le serveur MCP v1.5.1 inclut la journalisation structurée et les métriques d'outils.

Journalisation structurée

Tous les logs sont émis en JSON vers stderr (le MCP utilise stdout pour les messages du protocole). Chaque entrée inclut :

level : debug, info, warn, error
service : toujours frihet-mcp
timestamp : ISO 8601
tool : nom de l'outil (le cas échéant)
operation : type d'opération (tool_call, api_call, api_retry, startup, shutdown_metrics)
durationMs : temps d'exécution en millisecondes
error : détails de l'erreur (message, code, statusCode)

Activez les logs de débogage avec FRIHET_MCP_DEBUG=1.

Métriques d'outils

Le serveur enregistre en mémoire les appels à chaque outil : nombre d'invocations, erreurs et durée moyenne. Lors de la fermeture du serveur (SIGINT/SIGTERM), un résumé est émis :

{
  "level": "info",
  "message": "Shutdown after 3600s — 42 calls, 1 errors",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}

Réessai automatique en cas de limite de débit

Lorsque l'API répond avec 429, le serveur réessaie automatiquement avec un backoff exponentiel (jusqu'à 3 tentatives). Les tentatives sont enregistrées dans le log :

{
  "level": "warn",
  "message": "Rate limited, retrying GET /invoices (attempt 2, delay 2000ms)",
  "operation": "api_retry"
}

Vous n'avez pas besoin de gérer manuellement la limite de débit — le serveur le fait pour vous.

Transport

Le serveur MCP de Frihet prend en charge deux modes de transport. Les deux exposent les mêmes 52 outils, 11 ressources et 10 prompts.

Local (stdio)

Le serveur s'exécute en tant que processus local sur votre machine. La communication entre le client MCP et le serveur utilise l'entrée/sortie standard (stdin/stdout).

Requiert : Node.js installé (est téléchargé automatiquement via npx)
Avantage : Latence plus faible, fonctionne sans connexion internet (sauf pour les appels à l'API)
Cas d'utilisation : Développement quotidien, usage intensif, environnements d'entreprise avec restrictions réseau

Distant (streamable-http)

Le serveur s'exécute sur Cloudflare Workers. Votre client MCP se connecte directement à https://mcp.frihet.io/mcp via HTTP.

Requiert : Uniquement une connexion internet
Avantage : Pas d'installation locale, pas de dépendances, fonctionne sur n'importe quel appareil
Cas d'utilisation : Configuration rapide, équipes qui préfèrent ne pas installer de packages, clients ne supportant que le transport HTTP

info

Si votre client MCP ne prend pas en charge streamable-http (certains anciens clients ne supportent que stdio), utilisez le mode local.

Gestion des erreurs

Limite de débit

L'API autorise 100 requêtes par minute par clé. Si la limite est dépassée, le serveur renvoie une erreur 429 avec le temps d'attente dans retryAfter.

Le serveur MCP gère automatiquement la limite de débit avec un backoff exponentiel : il réessaie la requête après avoir attendu le temps indiqué, sans intervention de l'utilisateur. Maximum 3 tentatives.

Erreurs d'authentification

Code	Cause	Solution
`401`	Clé API invalide, expirée ou non fournie	Vérifiez que la clé dans votre configuration commence par `fri_` et n'a pas expiré
`403`	La clé n'a pas les permissions pour cette ressource	Générez une nouvelle clé avec les permissions nécessaires

Autres erreurs

Code	Description
`400`	Paramètres incorrects ou champs requis manquants
`404`	La ressource demandée n'existe pas
`408`	Délai d'attente de la requête (30 secondes)
`413`	Le corps de la requête dépasse 1 Mo
`422`	Données valides mais non traitables (ex : profil fiscal non configuré)
`429`	Limite de requêtes dépassée (réessai automatique)
`500`	Erreur interne du serveur

Toutes les erreurs renvoient un message descriptif bilingue (EN/ES) afin que l'assistant puisse communiquer clairement le problème à l'utilisateur.

Limites

Concept	Valeur
Requêtes par minute	100 par clé API
Résultats par page	100 maximum (50 par défaut)
Corps de la requête	1 Mo maximum
Payload de webhook	100 Ko maximum
Webhooks par compte	20 maximum
Délai d'attente de la requête	30 secondes
Tentatives de réessai pour la limite de débit	3 maximum

Différence avec l'API REST

	Serveur MCP	API REST
Destiné à	Assistants IA (Claude, Cursor, Windsurf)	Applications, scripts, intégrations
Communication	Langage naturel via le client MCP	HTTP/JSON direct
Authentification	Variable d'environnement dans la configuration du client (ou OAuth)	En-tête `X-API-Key` ou `Authorization: Bearer`
Format	Texte formaté + sortie structurée pour l'assistant	JSON brut
Limite de débit	Géré automatiquement (backoff exponentiel, 3 tentatives)	Manuel (le consommateur doit implémenter les tentatives de réessai)
Observabilité	Journalisation structurée + métriques par outil	Logs de requête via `X-Request-Id`
Cas d'utilisation	Interagir avec votre ERP depuis l'IDE	Construire des intégrations programmatiques

En interne, le serveur MCP traduit chaque appel d'outil en une requête vers l'API REST. Il ne duplique pas la logique — c'est un pont stateless.

Développement

Pour contribuer ou exécuter le serveur en mode développement :

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Exécuter localement :

FRIHET_API_KEY=fri_tu_clave node dist/index.js

Exécuter avec les logs de débogage :

FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_tu_clave node dist/index.js

Tester avec l'MCP Inspector :

npx @modelcontextprotocol/inspector node dist/index.js

Ressources associées

API REST — Référence complète des endpoints, authentification et codes d'erreur
Webhooks — Événements disponibles, vérification HMAC-SHA256 et politique de tentatives de réessai
Compétence pour Claude Code — Couche d'intelligence métier au-dessus du serveur MCP
Code source (GitHub) — Dépôt du serveur MCP
Package npm — @frihet/mcp-server@1.5.1
MCP Registry — io.frihet/erp
Endpoint distant — Serveur MCP hébergé sur Cloudflare Workers
Spécification MCP — Documentation du protocole

Précédent : Webhooks | Suivant : Compétence pour Claude Code

Ce à quoi s'attendre (et ce à quoi ne pas s'attendre)​

Prérequis​

Obtenir la clé API​

Installation​

Universel (plus de 30 agents)​

MCP Registry​

npx direct​

Configuration manuelle​

Local (stdio)​

Distant (streamable-http)​

Configuration par client​

Variables d'environnement​

Flux OAuth​

Outils disponibles (44)​

Factures (6 outils)​

Dépenses (5 outils)​

Clients (5 outils)​

Produits (5 outils)​

Devis (5 outils)​

Webhooks (5 outils)​

Ressources disponibles (8)​

Prompts disponibles (7)​

Exemples d'utilisation​

Créer une facture​

Enregistrer une dépense​

Rechercher les factures d'un client​

Consulter les débiteurs​

Enregistrer un client​

Configurer l'automatisation​

Mettre à jour un produit​

Observabilité​

Journalisation structurée​

Métriques d'outils​

Réessai automatique en cas de limite de débit​

Transport​

Local (stdio)​

Distant (streamable-http)​

Gestion des erreurs​

Limite de débit​

Erreurs d'authentification​

Autres erreurs​

Limites​

Différence avec l'API REST​

Développement​

Ressources associées​

Ce à quoi s'attendre (et ce à quoi ne pas s'attendre)

Prérequis

Obtenir la clé API

Installation

Universel (plus de 30 agents)

MCP Registry

npx direct

Configuration manuelle

Local (stdio)

Distant (streamable-http)

Configuration par client

Variables d'environnement

Flux OAuth

Outils disponibles (44)

Factures (6 outils)

Dépenses (5 outils)

Clients (5 outils)

Produits (5 outils)

Devis (5 outils)

Webhooks (5 outils)

Ressources disponibles (8)

Prompts disponibles (7)

Exemples d'utilisation

Créer une facture

Enregistrer une dépense

Rechercher les factures d'un client

Consulter les débiteurs

Enregistrer un client

Configurer l'automatisation

Mettre à jour un produit

Observabilité

Journalisation structurée

Métriques d'outils

Réessai automatique en cas de limite de débit

Transport

Local (stdio)

Distant (streamable-http)

Gestion des erreurs

Limite de débit

Erreurs d'authentification

Autres erreurs

Limites

Différence avec l'API REST

Développement

Ressources associées