Serveur MCP¶

Le même moteur est exposé aux agents IA via le Model Context Protocol sous forme de serveur distant (Streamable HTTP, sans état). Un agent dans Claude, Cursor, VS Code, ChatGPT ou votre propre application peut produire, contrôler et lire des factures électroniques conformes sans que vous écriviez de code d'intégration.

Endpoint : https://facturx-api.fly.dev/mcp

Outils¶

Outil	Rôle	Entrée	Sortie
`generate_invoice`	JSON de facture vers PDF/A-3 Factur-X, XML CII ou XML UBL	`invoice` (objet), `profile`, `output`, `language`, `check`, `footer_text`	Résumé texte (totaux, avertissements) + le document en ressource incorporée (PDF base64 ou texte XML)
`embed_xml`	Joindre un XML Factur-X à votre propre PDF	`pdf_base64`, `xml`, `check`, `language`	Résumé + PDF/A-3 en ressource incorporée
`validate_invoice`	XSD + schematron EN 16931 (+ `fr-ctc` français)	`document_base64` ou `xml`, `check`	Rapport structuré : `valid`, `profile`, `findings[]` avec identifiants de règles
`extract_invoice`	Lire une facture électronique	`document_base64` ou `xml`, `include_xml`	`fields` (parties, totaux, TVA, lignes) et éventuellement le XML

Ressources :

facturx://schema/invoice : JSON Schema de l'argument invoice (les agents le lisent pour remplir l'objet correctement).
facturx://guide/french-reform : aide-mémoire d'une page sur la réforme française.

Tous les outils sont annotés readOnlyHint / idempotentHint : rien n'est stocké côté serveur, appeler deux fois est sans risque.

Accès et facturation¶

Deux options en libre-service, aucun compte à demander :

	Avec votre clé de plan	Via AgenticMarket
URL	`https://facturx-api.fly.dev/mcp`	l'URL affichée par la place de marché
Authentification	en-tête `Authorization: Bearer <clé>`	aucune (la place de marché fait relais)
Prix	inclus dans tous les plans, Free compris (Tarifs)	0,05 $ par appel d'outil réussi, depuis le solde de la place de marché
Décompte	un document par `tools/call` réussi, même quota mensuel que l'API REST	à l'appel

initialize, tools/list, resources/* et les appels en échec ne sont jamais comptés. Au-delà du quota, le serveur renvoie une erreur JSON-RPC (HTTP 402) avec le lien de changement de plan ; l'agent la restitue telle quelle.

Configuration des clients¶

Les extraits utilisent la clé de plan. Si vous passez par AgenticMarket, utilisez l'URL de la place de marché et retirez l'en-tête.

Claude Desktop / Claude.aiCursorVS CodeClaude CodePython (SDK mcp)

Les connecteurs personnalisés ne peuvent pas encore envoyer d'en-tête ; utilisez mcp-remote dans claude_desktop_config.json :

{
  "mcpServers": {
    "facturx": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://facturx-api.fly.dev/mcp",
        "--header", "Authorization: Bearer ${FACTURX_KEY}"
      ],
      "env": { "FACTURX_KEY": "votre-clé-de-licence" }
    }
  }
}

Sur Claude.ai (web), sans processus local, passez par AgenticMarket.

.cursor/mcp.json (projet) ou ~/.cursor/mcp.json (global) :

{
  "mcpServers": {
    "facturx": {
      "url": "https://facturx-api.fly.dev/mcp",
      "headers": { "Authorization": "Bearer votre-clé-de-licence" }
    }
  }
}

.vscode/mcp.json :

{
  "servers": {
    "facturx": {
      "type": "http",
      "url": "https://facturx-api.fly.dev/mcp",
      "headers": { "Authorization": "Bearer votre-clé-de-licence" }
    }
  }
}

claude mcp add --transport http facturx https://facturx-api.fly.dev/mcp \
  --header "Authorization: Bearer votre-clé-de-licence"

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

url = "https://facturx-api.fly.dev/mcp"
headers = {"Authorization": "Bearer votre-clé-de-licence"}
async with streamable_http_client(url, headers=headers) as (read, write, _):
    async with Client((read, write)) as client:
        result = await client.call_tool("validate_invoice", {"xml": xml_text, "check": "fr-ctc"})
        print(result.structured_content["valid"], result.structured_content["findings"])

Exemples de demandes¶

« Génère une facture Factur-X pour ce devis : vendeur Atelier Numérique SAS (SIREN 732829320, TVA FR40732829320, Paris), acheteur Boulangerie Dupont (SIREN 552081317, Lyon), 1 x développement site web 2500 € HT à 20 %, 12 mois d'hébergement à 15 €, échéance 30 jours. »
« Valide la facture fournisseur jointe avec les règles françaises et explique chaque règle en échec en termes simples. »
« Extrais les totaux et la ventilation de TVA de ces trois PDF et donne-moi un tableau. »

Les descriptions des outils indiquent à l'agent d'utiliser des chaînes décimales pour les montants, des dates ISO, et de toujours lancer validate_invoice sur les fichiers qu'il n'a pas générés ; vous avez rarement besoin de le préciser.

Notes de conception pour les intégrateurs¶

Sans état : pas de session, pas de cookies ; chaque requête est indépendante. Compatible avec les passerelles et répartiteurs de charge.
Charges utiles : les documents circulent en base64 dans le JSON. Un PDF de 300 Ko représente environ 400 Ko de JSON ; le serveur accepte jusqu'à 20 Mo par requête.
Les erreurs sont renvoyées comme erreurs d'outil avec un message lisible incluant les identifiants des règles en échec, pour que l'agent corrige l'entrée et réessaie.
generate_invoice refuse de renvoyer un fichier qui ne passe pas le jeu de règles demandé. Vous obtenez un document conforme, ou la liste des raisons.