Aller au contenu
IBANforge

Intégration MCP

IBANforge fournit un serveur MCP officiel pour agents IA : ibanforge-mcp sur npm, plus un endpoint hébergé sans rien installer. Claude, Cursor ou tout client compatible MCP peut valider des IBAN, résoudre des BIC, vérifier des numéros de clearing suisses et lancer un pré-contrôle conformité sous forme d'appels d'outils.

Qu'est-ce que MCP ?

Le Model Context Protocol est un standard ouvert qui permet aux assistants IA d'utiliser des outils externes. Au lieu de demander à l'utilisateur de copier-coller des résultats d'API, l'agent appelle l'outil directement et reçoit des données structurées.

Option 1 — le paquet npm (stdio)

Claude Desktop — ajoutez IBANforge au fichier de configuration :

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

Windows : %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ibanforge": {
      "command": "npx",
      "args": ["-y", "ibanforge-mcp"],
      "env": { "IBANFORGE_API_KEY": "ifk_votre_cle" }
    }
  }
}

Claude Code — une seule commande :

claude mcp add ibanforge -e IBANFORGE_API_KEY=ifk_votre_cle -- npx -y ibanforge-mcp

La clé est optionnelle et gratuite — 25 requêtes/mois sans e-mail. Générez-la avec un POST sans corps, puis envoyez Authorization: Bearer ifk_.... Réclamer cette même clé avec un code reçu par e-mail porte le quota à 200/mois, sans carte.

Après enregistrement, redémarrez le client. Le module npm expose 13 outils, le serveur HTTP distant 11. Les deux outils d’audit de fichiers sont réservés au module npm. Le catalogue par transport détaille leur disponibilité.

Option 2 — l'endpoint hébergé (rien à installer)

https://api.ibanforge.com/mcp

Transport HTTP streamable, 25 appels d'outils gratuits par semaine et par adresse source, sans aucune clé (semaine ISO en UTC, remise à zéro le lundi à 00:00 UTC ; un lot compte un appel par IBAN ; distinct de l'essai REST sans clé) : le chemin le plus rapide pour qu'un agent évalue la donnée avant tout engagement. Pour un usage suivi, envoyez votre clé gratuite avec chaque requête (ci-dessous), ou lancez le paquet npm avec elle.

Avec votre clé

L'endpoint hébergé lit une clé IBANforge envoyée dans un en-tête de la requête, Authorization: Bearer ifk_… ou X-API-Key: ifk_…, les deux mêmes en-têtes que l'API REST. Les appels d'outils se comptent alors sur cette clé exactement comme les appels REST : son allocation à elle, une unité par appel, une par IBAN dans un lot, rien sur les outils gratuits, et les mêmes refus. L'allocation sans clé ci-dessus n'est plus utilisée. Une clé écrite dans l'adresse (?api_key=) n'est pas lue. Si la clé est inconnue, révoquée ou épuisée, l'outil répond avec le message de l'API REST pour cette clé et ne retombe jamais sur l'allocation sans clé.

Claude Code :

claude mcp add --transport http ibanforge https://api.ibanforge.com/mcp --header "Authorization: Bearer ifk_votre_cle"

Claude et Claude Desktop (connecteur personnalisé, étapes plus bas) : si la fenêtre Add custom connector montre une section Request headers, ajoutez-y l'en-tête Authorization avec la valeur Bearer ifk_votre_cle. La documentation d'Anthropic, lue le 10 novembre 2026, dit que cette section est en bêta et ouverte à un nombre limité d'organisations : si vous ne la voyez pas, votre compte ne l'a pas encore. Les réglages d'authentification d'un connecteur existant, en-têtes de requête compris, ne se modifient pas : supprimez-le, puis ajoutez-le de nouveau avec la clé. En Team et Enterprise, tous ceux qui utilisent le connecteur partagent alors cette clé. Sans cette section, utilisez le paquet npm dans Claude Desktop (Option 1) ou Claude Code (ci-dessus). Non essayé par nous.

ChatGPT : la page d'OpenAI sur l'authentification, lue le 7 octobre 2026, indique que ChatGPT se connecte à un serveur MCP par OAuth ou sans authentification, et ne peut pas présenter une clé d'API. Dans ChatGPT, l'endpoint hébergé reste donc sur son allocation sans clé ; votre clé sert sur l'API REST, ou avec le paquet npm dans un autre client.

Gemini : non vérifié par nous.

L'ajouter comme connecteur dans un assistant de conversation

Dans un assistant de conversation, l'adresse ci-dessus devient un connecteur personnalisé : l'assistant appelle alors lui-même les outils MCP, au lieu de deviner une réponse qu'il ne peut pas obtenir.

Un connecteur sans clé puise dans la même allocation sans clé que tout autre appelant, comptée par adresse source. Dans Claude, les appels d'un connecteur partent du cloud d'Anthropic, pas de votre appareil (page d'aide d'Anthropic sur les connecteurs personnalisés, section « Network requirements ») : cette allocation est donc partagée avec d'autres utilisateurs et peut être déjà épuisée quand vous commencez. Autres assistants : non vérifié par nous. Avec votre propre clé, le connecteur se compte sur cette clé : voir Avec votre clé ci-dessus (Claude la prend en en-tête de requête là où sa fenêtre propose cette section, ChatGPT n'en envoie aucune). Un POST sur https://api.ibanforge.com/v1/keys/generate sans corps renvoie une clé, sans e-mail.

Où cliquer, d'après les pages officielles liées. Claude : lue le 10 novembre 2026 ; ChatGPT et Gemini : lues le 24 septembre 2026 ; Mistral et Perplexity : lues le 23 octobre 2026. Les menus changent ; la page liée fait référence.

Claude (documentation d'Anthropic, lue le 10 novembre 2026). Les connecteurs personnalisés sont ouverts aux plans Free, Pro, Max, Ultra, Team et Enterprise ; en Free, un seul connecteur personnalisé. Non essayé par nous.

  • Raccourci (plan individuel) : ouvrir la fenêtre Add custom connector de Claude avec cette adresse déjà saisie. Claude affiche les valeurs et vous demande de confirmer avant d'ajouter quoi que ce soit.
  • Plan individuel : ouvrez Customize > Connectors, cliquez sur Add custom connector, saisissez https://api.ibanforge.com/mcp, puis Add. La fenêtre diffère d'un compte à l'autre : si elle demande comment les personnes se connectent, choisissez No sign-in, ce serveur ne demandant aucun compte. Pour utiliser votre clé, voir Avec votre clé ci-dessus.
  • Team ou Enterprise : un Owner ouvre Organization settings > Connectors, choisit Add, puis Custom (et Web si Claude demande le type de connecteur), saisit l'adresse et clique sur Add ; les membres le trouvent ensuite dans Customize > Connectors et cliquent sur Connect.
  • Dans une conversation : le bouton + de la conversation, puis Connectors, pour l'activer.

ChatGPT (page officielle). Le mode développeur, sur le web, pour les comptes Pro, Plus, Business, Enterprise et Education : pas sur l'offre gratuite. Non essayé par nous.

  • L'activer : Settings → Security and login, puis Developer mode.
  • Ajouter le serveur : ouvrez ChatGPT Plugins, choisissez le bouton plus et créez une application en mode développeur pour le serveur MCP distant https://api.ibanforge.com/mcp. La page cite le HTTP en flux parmi les protocoles et No Authentication parmi les options.
  • Dans une conversation : choisissez Developer mode dans le menu plus, puis l'application.

Gemini (page officielle). Les applications personnalisées demandent d'avoir 18 ans ou plus et d'être aux États-Unis, un compte Google personnel (pas un compte professionnel ou scolaire), l'activité conservée (Keep Activity) et l'anglais ; elles s'ajoutent dans l'application web de Gemini seulement, puis fonctionnent sur le web et dans l'application mobile. Non essayé par nous.

  • Sur gemini.google.com, cliquez sur Settings en bas, puis Connected Apps ; sous « Custom apps », ajoutez une application personnalisée, saisissez https://api.ibanforge.com/mcp, cliquez sur Next et suivez les instructions à l'écran.
  • La page demande des identifiants sous « Advanced features » quand un serveur ne prend pas en charge le Dynamic Client Registration. Ce serveur ne demande aucune authentification ; que Gemini l'accepte n'est pas vérifié par nous.
  • Dans une requête : tapez @ et choisissez l'application.

Mistral (Le Chat) (guide officiel des connecteurs, désormais sous Vibe Work, lu le 23 octobre 2026). Un accès administrateur est requis ; les titulaires Free, Pro et Student le sont par défaut. Non essayé par nous.

  • Ouvrez Connectors → + Add Connector → Custom MCP Connector. Nommez-le IBANforge, saisissez https://api.ibanforge.com/mcp comme adresse du serveur, puis Connect.
  • Le guide décrit une détection automatique de l'authentification, y compris son absence. IBANforge s'essaie sans clé ; l'ajout d'une clé dans cet assistant n'a pas été vérifié par nous.

Perplexity (page officielle, lue le 23 octobre 2026). Disponible sur Pro, Max et Enterprise selon l'annonce de lancement. En organisation, l'administrateur doit autoriser les connecteurs personnalisés. Non essayé par nous.

  • Ouvrez Plugins → Add custom → Connector → Add MCP connector → Remote. Sans Plugins, partez de Customize → Connectors.
  • Nommez-le IBANforge, saisissez https://api.ibanforge.com/mcp, choisissez Streamable HTTP et None pour essayer sans clé. Lisez l'avertissement, puis Add et ouvrez la carte du connecteur pour l'activer. Le guide cite aussi l'authentification par clé API ; son en-tête avec IBANforge n'a pas été vérifié par nous.

Pour les répertoires de connecteurs, https://api.ibanforge.com/mcp/directory expose les mêmes outils sans prix ni offres. Cette adresse partage les plafonds et les compteurs de /mcp : changer d'adresse ne donne pas une allocation supplémentaire. Elle ne signifie pas qu'IBANforge a été accepté dans le répertoire d'un assistant.

Sur le registre MCP officiel, le serveur est listé sous io.github.cammac-creator/ibanforge.

Les outils disponibles

Les objets JSON ci-dessous sont les arguments des outils, à transmettre par votre client MCP. Ce sont des exemples documentaires, sans garantie qu’un compte existe. Pour un premier essai gratuit sur les deux transports, utilisez validate_payment_reference sans IBAN. Relisez tools/list dans votre session : le paquet installé et le serveur hébergé peuvent évoluer séparément.

validate_iban

Contrôle la structure et la clé de l’IBAN, puis fournit les informations bancaires disponibles. Lisez séparément valid, bank_code_check et bic. Un BIC absent, une source indisponible ou une classification par défaut demandent une interprétation ; ils ne prouvent ni compte fermé ni fraude. Conservez source, as_of, basis et authoritative quand ils sont présents. Lire le résultat.

{ "iban": "CH1000230000000012345" }

batch_validate_iban

Reçoit de 1 à 100 IBAN et renvoie un objet avec results, count et valid_count. Les résultats suivent l’ordre d’entrée. Conservez cet ordre et les identifiants de vos lignes ; l’outil ne réécrit aucun fichier fournisseur. Les règles de clé et de décompte restent celles du transport choisi. Guide des lots.

{ "ibans": ["CH1000230000000012345", "DE89370400440532013000"] }

lookup_bic

Recherche une institution à partir d’un BIC déjà connu. Le champ d’entrée s’appelle bic, pas code, sur le paquet npm comme sur le serveur hébergé. valid_format décrit la forme du BIC ; found indique si une fiche a été trouvée. Nom, LEI et adresse peuvent manquer ou porter des dates distinctes. Guide BIC.

{ "bic": "UBSWCHZH80A" }

lookup_ch_clearing

Recherche un IID / BC-Nummer suisse ou liechtensteinois. Lisez found, les informations d’institution et de participation disponibles, puis leur provenance. Une attribution qr_iid peut venir du registre ou être héritée du siège : conservez qr_iid_source. Un IID de la plage QR ne prouve pas l’existence du compte. Guide du clearing.

{ "iid": "230" }

check_compliance

Ajoute les indicateurs de banque et de pays au résultat de validation. Lisez les états de consultation (screened, bank_screened), les valeurs null, les flags et les dates de source avant le score. Ce score ne remplace pas la revue du dossier. La présence d’une banque au registre VoP n’est pas une vérification du nom du titulaire ; le filtrage bancaire ne porte pas sur le bénéficiaire. Comprendre les contrôles.

{ "iban": "CH1000230000000012345" }

validate_payment_reference

Sur /mcp hébergé sans clé, cet outil consomme néanmoins l’allocation gratuite.

Contrôle une référence RF/SCOR, QRR, OGM/VCS ou viitenumero. Sans IBAN, cet appel est gratuit sur les deux transports. Exemple de premier essai :

{ "reference": "RF18539007547034" }

Un IBAN facultatif ajoute le contrôle d’appariement. Différence de transport : le serveur HTTP hébergé effectue ce contrôle gratuitement ; le paquet npm 1.10.0 passe alors par POST /v1/iban/validate, avec les conditions d’accès de cette route. Ne présentez donc pas l’exemple suivant comme gratuit dans tous les clients. valid et pairing sont indépendants. Pour KID et OCR, valid: null signifie que la configuration du compte créancier est nécessaire, pas que la référence est invalide.

{ "reference": "210000000003139471430009017", "iban": "CH4431999123000889012" }

check_postal_address

Contrôle des règles de format pour sps, hvps_plus ou fedwire, gratuitement. Conservez la source de chaque constat et le champ note ; not_applicable n’est pas un contrôle réussi. L’outil ne vérifie pas l’existence de la rue. Pour CH/LI, le bloc distinct postcode_locality décrit le rapprochement code postal/localité lorsqu’il est possible. Règles et calendriers.

{ "scheme": "sps", "address": { "strt_nm": "Bahnhofstrasse", "bldg_nb": "45", "pst_cd": "8001", "twn_nm": "Zurich", "ctry": "CH" } }

check_swiss_qr_bill

Contrôle le texte d’une QR-facture suisse commençant par SPC, gratuitement : structure, IBAN, référence et appariement, montant, monnaie et adresses. Ce n’est pas un décodeur d’image. valid porte sur le contenu contrôlé, pas sur le compte ni l’acceptation par une banque. Une proposed_structured reste une proposition à relire. Conservez les sources des findings ; les calendriers de la QR-facture et de l’ordre de paiement sont distincts. Guide QR-facture. Les noms du payload ci-dessous sont fictifs.

Le type K n'est plus permis dans une QR-facture depuis le 21.11.2025 (SIX, IG QR-facture 2.3). Les banques n'en garantissent le paiement que jusqu'à fin septembre 2026 (UBS : 30.09.2026 ; ZKB : au plus tard fin septembre 2026). Une QR-facture K risque donc d'être refusée au paiement : réémettez-la en type S. Dès le 14.11.2026, les Swiss Payment Standards exigent dans un ordre de paiement une adresse structurée ou hybride, avec la localité et le pays dans leurs propres champs. Le système SIC ne valide pas les adresses : chaque banque décide. Certaines acceptent encore, pour un temps, les paiements suisses ; un paiement SEPA ou international sans localité peut être rejeté. Refaites aussi les ordres permanents et les modèles saisis depuis une QR-facture K.

{ "payload": "SPC\n0200\n1\nCH4431999123000889012\nS\nSociete Alpha\nRue du Lac\n1268\n2501\nBiel\nCH\n\n\n\n\n\n\n\n1949.75\nCHF\nS\nSociete Beta\nMarktgasse\n28\n9400\nRorschach\nCH\nQRR\n210000000003139471430009017\nOrder 15.06.2026\nEPD" }

audit_creditor_file

Contrôle un fichier de créanciers/fournisseurs entier (CSV ou XLSX) ligne par ligne : structure et clé de l'IBAN, code banque au registre national, nom de banque et BIC, joignabilité SEPA et type d'émetteur, plus les contrôles qu'un seul appel IBAN ne peut pas faire car ils ont besoin du fichier entier — IBAN dupliqués, BIC porté par le fichier contre le BIC dérivé du registre, pays de l'adresse contre pays de l'IBAN, et contrôles d’adresse décrits dans le rapport. Renvoie un aperçu gratuit uniquement (IBAN masqués, compteurs de synthèse, jusqu'à 20 lignes) — le rapport annoté .xlsx complet est une prestation payante (149 $ jusqu'à 5 000 lignes, 349 $ jusqu'à 20 000) réglée via une session Stripe Checkout ponctuelle, jamais payée automatiquement. Passez checkout: true pour recevoir aussi l'URL Checkout, à ouvrir par un humain. Encodez le fichier en base64 et envoyez-le comme file_base64 ; un fichier de plus de 5 Mo est refusé localement, avant tout appel réseau : au-delà, la charge base64 casse le canal stdio et l'agent perd sa connexion au lieu de recevoir une erreur. La route HTTP, elle, accepte jusqu'à 10 Mo — passez par elle pour un gros fichier.

L’exemple contient une seule ligne fictive. L’encodage base64 ne chiffre pas le fichier : son contenu est transmis au service. Utilisez uniquement des données que vous êtes autorisé à transmettre ; l’aperçu masqué ne signifie pas que le fichier est resté local. Parcours d’audit.

{ "file_base64": "Tm9tO0lCQU4KU29jaWV0ZSBBbHBoYTtDSDEwMDAyMzAwMDAwMDAwMTIzNDUK", "filename": "creanciers.csv", "lang": "fr" }

audit_status

Lit le statut du job renvoyé par audit_creditor_file. L’identifiant ci-dessous est un exemple fictif : remplacez-le par celui de votre réponse. Un éventuel session_id vient du retour de votre propre Checkout ; ne le fabriquez pas. L’outil ne réalise pas de paiement. Le lien de téléchargement dépend de l’état du job.

{ "job": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }

audit_creditor_file et audit_status ne sont, pour l'instant, que sur le paquet npm (Option 1) — pas encore sur l'endpoint HTTP hébergé (Option 2).

send_feedback

Transmet un retour aux opérateurs : cette action écrit un message, elle ne sert pas à tester la connexion. error_type et notes sont requis ; n’y incluez ni clé, ni fichier client, ni coordonnées bancaires sensibles. L’outil est gratuit et possède ses propres protections contre les abus. Un humain lit chaque rapport. L’exemple ci-dessous est un modèle à adapter, pas une anomalie constatée.

{"error_type": "stale_bic", "notes": "À compléter : BIC concerné, source publique et résultat attendu.", "endpoint": "/v1/iban/validate"}

request_api_key

Demander une clé sans e-mail : l’outil rend un lien qu’une personne ouvre et approuve dans son navigateur. Disponible sur les deux transports.

La clé ne débloque pas la session qui l’a demandée : elle sert une fois placée dans la configuration du client, après une reconnexion. Où la mettre :

  • Claude Code avec le paquet npm : la config_line que rend poll_api_key, une commande claude mcp add … -e IBANFORGE_API_KEY=….
  • Claude Code sur l’endpoint hébergé : --header "Authorization: Bearer ifk_…" (voir Avec votre clé).
  • Claude et Claude Desktop : les Request headers du connecteur personnalisé si la fenêtre montre cette section (le connecteur doit être supprimé puis ajouté de nouveau), ou IBANFORGE_API_KEY dans claude_desktop_config.json avec le paquet npm (Option 1).
  • ChatGPT : nulle part sur un connecteur, qui n’envoie aucune clé ; la clé sert sur l’API REST.
  • Tout client HTTP : l’API REST, avec Authorization: Bearer ifk_….

poll_api_key

Récupérer la clé après son approbation, avec le device_code reçu de request_api_key. La clé n’est rendue qu’une fois : conservez-la, et placez-la comme le dit la liste ci-dessus. Disponible sur les deux transports.

Lire une réponse sans inventer de verdict

Le client MCP reçoit une enveloppe avec content et, pour les réponses structurées, structuredContent. Vérifiez d’abord si l’appel a échoué. Un isError: true ou une erreur de protocole n’est pas un valid: false : aucun résultat métier exploitable n’est alors garanti.

SituationLecture à conserver
valid: false dans une réponse réussieLe contrôle de l’IBAN a échoué ; lire les détails.
bic: null, unknown ou source indisponibleRésultat incomplet ou inconnu ; garder cet état.
Refus 401, 402 ou 429Problème d’accès, de quota ou de fréquence ; lire le message et retry_after s’il existe.
Délai dépassé, réseau ou réponse illisibleL’appel n’a pas fourni de résultat complet ; il a pu atteindre le serveur.

L’outil validate_iban du paquet npm 1.10.0 peut renvoyer un contrôle de format dégradé lors d’un essai sans clé refusé en 402 : _degraded: true et _scope: "format_only". Il ne contient alors pas de résolution bancaire complète. Une clé configurée mais refusée ne déclenche pas ce repli. Le paquet ne signe pas de paiement x402 et ne recrée pas de clé pour continuer.

next_steps contient des recommandations calculées à partir du résultat. Conservez leur code, do et because lorsqu’ils sont présents, puis relisez les champs cités. Ces recommandations n’autorisent ni paiement, ni modification de coordonnées, ni validation du titulaire. Les absences de source restent des absences de source. Erreurs et accès.

Les codes bank_code_not_allocated, modulus_check_failed et national_check_digits_failed signalent un contrôle bloquant à résoudre avant de poursuivre le traitement. Ils décrivent respectivement l’attribution du code banque, l’appariement britannique sort code/numéro de compte et la clé nationale. national_check_digits_suspect demande une confirmation du numéro, sans le déclarer invalide ; verify_payee_name appelle un contrôle distinct du nom du bénéficiaire. Un code absent ne constitue pas une autorisation de payer.

Un premier essai reproductible

Contrôle uniquement la référence documentaire RF18539007547034 avec validate_payment_reference, sans IBAN. Donne le schéma reconnu, valid et la source renvoyée. Si l’appel échoue, explique l’erreur sans inventer un résultat.

Pour un essai de résolution bancaire, appelez ensuite validate_iban avec l’exemple de sa section. Demandez à l’assistant de restituer les valeurs reçues et leur provenance, y compris les champs inconnus. Aucun nom de banque ou résultat de registre n’est garanti par cette page.

Fonctionne bien avec

PayQR — npx -y @czagents/payqr, MCP hébergé https://payqr.cz-agents.dev/mcp, registre dev.cz-agents/payqr. Génère et auto-vérifie un QR de paiement européen à partir d'un IBAN et des détails du paiement : SPAYD pour les comptes CZ/SK, EPC/GiroCode (EUR uniquement) pour les autres comptes SEPA ; EPC exige recipient_name. PayQR valide la clé de l'IBAN mais ne vérifie ni la titularité du compte ni le nom du bénéficiaire, et ne génère pas de QR-factures suisses natives — le contrôle au registre, la préparation VoP et les indicateurs de risque sont exactement ce qu'IBANforge ajoute par-dessus.

Clients compatibles

  • Claude Desktop et Claude Code — support MCP natif
  • Cursor et Continue.dev — via leur configuration MCP
  • n8n — préférez le node communautaire dédié
  • Agents sur mesure — toute application utilisant le SDK MCP

Notes

  • Le paquet npm envoie les arguments à l’API IBANforge. Il ne constitue pas un fonctionnement bancaire hors ligne.
  • Les sources ont des dates et une couverture différentes. Lisez les dates effectivement renvoyées ; un appel récent peut consulter une source plus ancienne.
  • Les schémas de tools/list décrivent la version connectée. Les deux outils d’audit sont propres au paquet npm.
  • Les tarifs, les accès et les erreurs sont détaillés dans les clés API, les tarifs et le guide des erreurs.