Serveur MCP KRONENWERK : connecter un agent IA à votre comptabilité

KRONENWERK expose un serveur Model Context Protocol (MCP) à l'adresse https://kronenwerk.org/api/extern/mcp. Un agent IA parlant MCP sur Streamable HTTP s'authentifie par OAuth 2.1 (Claude, ChatGPT et d'autres assistants hébergés) ou avec la même clé API Bearer que l'API REST, lit les clients, factures, transactions et rapports d'une entreprise, et crée des brouillons, des transactions et des notes. Qu'il puisse aussi émettre une facture, l'envoyer ou enregistrer un paiement relève de l'entreprise : par défaut ces actes restent ceux d'une personne, et l'entreprise peut les autoriser sous Paramètres → Assistants IA jusqu'à une limite de montant qu'elle fixe, chaque acte étant consigné. Le serveur MCP fait partie de l'offre Enterprise.

Ce qu'est le MCP

Le Model Context Protocol est une spécification ouverte, publiée sur modelcontextprotocol.io, qui définit comment une application IA (le client) découvre et appelle des outils offerts par un système externe (le serveur). Les messages sont en JSON-RPC 2.0. Le serveur publie une liste d'outils avec noms, descriptions et schémas d'entrée JSON ; le modèle lit ces descriptions, décide quoi appeler, et le client envoie une requête tools/call en son nom. Le résultat revient sous forme de contenu que le modèle peut lire et, en option, sous forme de JSON structuré.

Deux transports sont standardisés : stdio pour un serveur lancé comme sous-processus local, et Streamable HTTP pour un serveur joint par le réseau. KRONENWERK est un service réseau, il n'implémente donc que Streamable HTTP. Le protocole est versionné par date. Au 3 septembre 2026, la spécification désigne 2026-07-28 comme révision courante ; les révisions antérieures (2025-11-25, 2025-06-18, 2025-03-26) ouvrent une connexion par une poignée de main initialize, tandis que la révision courante porte la version du protocole et l'identité du client dans un objet _meta sur chaque requête et ajoute une méthode server/discover. Un serveur peut servir plusieurs révisions sur le même endpoint, et KRONENWERK le fait.

Endpoint, transport et authentification

Tout se passe à une seule adresse avec une seule méthode HTTP : POST https://kronenwerk.org/api/extern/mcp, corps application/json, un message JSON-RPC par requête.

Authentification

Soit Authorization: Bearer greif_oauth_… — un jeton d'accès OAuth 2.1 obtenu par le flux code d'autorisation + PKCE sur /oauth/authorize et /oauth/token, avec enregistrement dynamique des clients sur /oauth/register et découverte sous /.well-known/oauth-authorization-server (c'est ainsi que Claude et ChatGPT se connectent : le propriétaire de l'entreprise se connecte et consent une fois) — soit Authorization: Bearer greif_live_… / greif_test_…, la même clé API que l'API REST accepte, créée dans les paramètres de KRONENWERK et liée à exactement une entreprise. Une requête sans identifiant valide reçoit 401 avec WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource", que les clients MCP suivent pour lancer la connexion. Voir authentification.

Tenant

L'entreprise qu'un agent atteint est celle de la clé. Il n'existe de paramètre d'organisation nulle part dans la surface du protocole, si bien qu'un agent ne peut ni sélectionner ni énumérer des entreprises.

Session

Aucune. Le serveur ne conserve pas de session et n'émet pas de MCP-Session-Id. Chaque requête porte son propre identifiant et sa propre version de protocole. GET (le flux optionnel serveur-vers-client) et DELETE (terminaison de session) répondent 405 Method Not Allowed, ce que la spécification prévoit pour les serveurs qui ne les offrent pas.

Versions du protocole

2026-07-28 (_meta par requête), et les versions à poignée de main 2025-11-25, 2025-06-18 et 2025-03-26. Une requête qui nomme une autre version reçoit l'erreur JSON-RPC -32022 avec la liste prise en charge dans data.supported. Une requête qui ne nomme aucune version est servie comme client hérité.

Méthodes

server/discover, initialize, tools/list, tools/call, ping. Pas de ressources, d'invites (prompts), d'échantillonnage ni de notifications ; le serveur n'ouvre jamais de flux. Les lots ne sont pas acceptés ; chaque requête est un message.

Origin

Une requête portant un en-tête Origin d'un autre site est refusée avec 403, comme l'exige la spécification contre le DNS rebinding. Les clients hors navigateur n'envoient pas d'Origin et ne sont pas concernés.

Limite de débit

L'endpoint MCP se trouve dans la même chaîne de filtres que l'API REST, si bien que le budget de la clé de 240 requêtes, se rechargeant à environ deux par seconde, s'applique aux deux ensemble. Au-delà du budget, la réponse est 429 avec Retry-After. Voir limites de débit.

Plan

Une clé valide dont l'entreprise n'est pas sur le plan Enterprise reçoit 403 avec le code d'erreur applicatif 1402 et une phrase l'indiquant. Les plans sont décrits sur la page des tarifs.

Pour les clients sur la révision courante, le serveur vérifie aussi les en-têtes miroirs introduits par la spécification — MCP-Protocol-Version, Mcp-Method et, sur tools/call, Mcp-Name — par rapport au corps, et répond à une discordance par l'erreur -32020 et HTTP 400. Les clients construits sur un SDK MCP maintenu le font automatiquement.

Les outils

Vingt-deux outils existent, en trois classes : les outils de lecture, qui ne changent rien ; les outils de brouillon, qui créent quelque chose d'inerte sur lequel une personne doit encore agir ; et les outils d'action, qui rendent un fait financier vrai et ne sont proposés qu'aux entreprises ayant choisi le niveau Agir dans une limite. tools/list ne renvoie que les outils que les portées de l'identifiant et le niveau de l'entreprise permettent ; une clé avec invoices:read seul voit les lecteurs de factures et rien d'autre, et une entreprise au niveau par défaut ne voit jamais un outil d'action. Les portées sont les mêmes que celles de l'API REST.

Les montants sont renvoyés comme un nombre d'unités mineures avec un code de devise — {"minor": 105910, "currency": "EUR"} vaut 1 059,10 EUR — jamais comme une chaîne formatée. Les dates sont des jours calendaires au format YYYY-MM-DD. Chaque objet créé par un outil de brouillon est enregistré comme créé par cette clé API, et l'entreprise peut voir cette attribution dans le produit. Un modèle ne peut pas faire passer son travail pour celui d'une personne.

Niveaux et limites de sécurité

C'est l'entreprise — ni l'agent ni KRONENWERK — qui décide jusqu'où le logiciel peut aller. Sous Paramètres → Assistants IA, le propriétaire fixe l'un de trois niveaux, qui s'applique de la même façon à chaque assistant connecté et à chaque clé :

• Lecture seule — les douze outils de lecture. Les brouillons sont désactivés ; un appel de brouillon reçoit une phrase qui le dit.
• Lire et proposer (par défaut) — les outils de lecture plus les sept outils de brouillon. Rien de ce qu'un agent fait à ce niveau n'est un fait financier ; une personne émet, envoie et enregistre.
• Agir dans une limite — ajoute issue_invoice, send_invoice et record_payment. Chaque acte est vérifié contre une limite de montant brut dans la devise de base de l'entreprise, dans sa propre transaction, de sorte qu'une facture dépassant la limite est annulée en entier : aucun numéro consommé, aucun enregistrement, aucun e-mail.

Quel que soit le niveau, aucun outil n'annule ni ne corrige un document émis, n'approuve ni ne paie une facture fournisseur, ne passe une écriture, ne clôture une période, ni ne crée, fait tourner ou révoque des identifiants et des paramètres. Cela reste entre les mains d'une personne connectée à KRONENWERK.

Lorsqu'un modèle demande un acte que l'entreprise n'a pas autorisé — record_payment au niveau par défaut, cancel_invoice à tout niveau —, le serveur ne répond pas « outil inconnu », qu'un modèle lit comme un problème de nom et contourne. Il répond par un résultat normal marqué isError: true dont le texte énonce la règle, dit qu'aucune partie de la requête n'a été exécutée et nomme le paramètre qu'une personne changerait. Le modèle relaie quelque chose de vrai et s'arrête.

Chaque acte et chaque brouillon est inscrit au registre d'auteur de l'entreprise avec l'outil, la connexion et l'heure, et les services sous-jacents écrivent leurs lignes d'audit habituelles sous la connexion plutôt que sous une personne, de sorte que la trace dit toujours quel assistant a fait quoi. D'autres propriétés découlent du transport : les lectures sont limitées par les mêmes permissions que l'écran équivalent ; les identifiants d'une autre entreprise sont signalés comme introuvables plutôt qu'interdits ; les défaillances internes sont décrites en une phrase fixe sans trace de pile, de sorte que noms de tables et chemins de fichiers n'entrent jamais dans le contexte d'un modèle ; et une connexion peut être révoquée à tout moment dans les paramètres, ce qui met fin à l'accès de cet agent dès la requête suivante. Les mêmes règles que pour l'API REST s'appliquent — voir sécurité de l'API.

Connecter un client

La plupart des clients MCP acceptent une configuration JSON nommant des serveurs distants. Une entrée générique pour KRONENWERK ressemble à ceci ; les noms de clés de l'objet externe varient selon le client, les champs internes non :

{
  "mcpServers": {
    "kronenwerk": {
      "type": "http",
      "url": "https://kronenwerk.org/api/extern/mcp",
      "headers": {
        "Authorization": "Bearer greif_live_XXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

Utilisez une clé greif_test_ pendant le développement. Elle atteint le même endpoint en mode test pour l'entreprise qui l'a créée ; il n'existe pas d'hôte sandbox distinct. Créez la clé avec uniquement les portées dont l'agent a besoin : un assistant qui répond à « qui nous doit de l'argent » a besoin de reports:read et customers:read et de rien d'autre.

Sans client, l'endpoint peut être exercé avec curl. Une poignée de main de style hérité et un appel d'outil :

curl -s https://kronenwerk.org/api/extern/mcp \
  -H "Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-11-25","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}'

curl -s https://kronenwerk.org/api/extern/mcp \
  -H "Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"list_receivables","arguments":{"as_of":"2026-09-03"}}}'

Le résultat du second appel porte le rapport à la fois comme texte lisible dans content et comme JSON dans structuredContent. Un client sur la révision courante envoie les mêmes messages avec la version dans params._meta["io.modelcontextprotocol/protocolVersion"] et les en-têtes miroirs ; le serveur répond aux deux formes.

MCP ou REST : lequel utiliser

Utilisez MCP lorsqu'un modèle de langage décide à l'exécution ce qu'il faut demander. Utilisez l'API REST lorsque votre propre code décide. Les deux surfaces lisent les mêmes données sous la même clé et les mêmes portées, si bien que rien n'impose un choix, et un système peut utiliser les deux.

La surface REST est décrite dans la vue d'ensemble de l'API comptable, la référence et le démarrage rapide. Les modèles d'intégration au niveau applicatif sont couverts dans connecter votre SaaS.

Comment KRONENWERK gère cela

SUPPORTED Le serveur MCP est en service sur https://kronenwerk.org/api/extern/mcp pour les entreprises de l'offre Enterprise, parle Streamable HTTP pour les révisions 2026-07-28, 2025-11-25, 2025-06-18 et 2025-03-26, s'authentifie par OAuth 2.1 ou clé API, et propose à chaque entreprise les douze outils de lecture et les sept outils de brouillon, et aux entreprises ayant autorisé l'action sous Paramètres → Assistants IA les trois outils d'action — chaque acte borné par la limite propre de l'entreprise et consigné. Annuler, corriger, payer les fournisseurs, passer des écritures, clôturer et configurer restent sans outil, par conception. Le même serveur fonctionne avec une clé greif_test_ en mode test. Le serveur MCP, l'API REST, les webhooks et l'annuaire d'intégrations font partie de l'offre Enterprise ; voir les tarifs et l'aperçu développeur.