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, 10 appels d'outils gratuits par IP et par jour, sans aucune clé : le chemin le plus rapide pour qu'un agent évalue la donnée avant tout engagement. Pour un usage suivi, lancez le paquet npm avec votre clé gratuite.

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

Les outils disponibles

validate_iban

Valide un IBAN : structure et clé, banque émettrice (BIC), contrôle du code banque au registre national, classification EMI/vIBAN, joignabilité SEPA/VoP et indicateurs de risque — les mêmes données que POST /v1/iban/validate.

{ "iban": "CH1000230000000012345" }

batch_validate_iban

Jusqu'à 100 IBAN en un appel, chaque résultat identique en structure à validate_iban — comme POST /v1/iban/batch.

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

lookup_bic

Détails d'un code BIC/SWIFT : nom, pays, ville, agence, LEI le cas échéant — comme GET /v1/bic/:code.

{ "code": "UBSWCHZH80A" }

lookup_ch_clearing

Recherche d'un BC-Nummer / IID suisse : institution, type, localité, participation SIC/euroSIC et attribution QR-IID — comme GET /v1/ch/clearing/:iid.

{ "iid": "230" }

check_compliance

Pré-contrôle complet en un appel : filtrage sanctions sur le BIC bancaire résolu, statut FATF, joignabilité SEPA Instant, participation VoP et score de risque composite de 0 à 100 — comme POST /v1/iban/compliance.

{ "iban": "CH1000230000000012345" }

validate_payment_reference

Valide une référence de paiement structurée — RF/ISO 11649 (SCOR), référence QR suisse (QRR), OGM/VCS belge, viitenumero finlandais — et, si un iban est fourni, tranche si les deux ont le droit de voyager ensemble. Gratuit ; même contrat que GET /v1/reference/validate, plus le verdict d'appariement.

valid et pairing sont indépendants : une référence peut être arithmétiquement valide et rester illicite sur ce compte. Le KID norvégien et l'OCR suédois répondent valid: null — leurs règles sont configurées par compte créancier par la banque du bénéficiaire — et ne doivent jamais être relayés comme « invalides ».

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

check_postal_address

Contrôle une adresse postale ISO 20022 structurée contre les règles publiées d'un rail de paiement — sps (Swiss Payment Standards), hvps_plus (T2) ou fedwire — règle par règle, chaque constat citant le document et sa date de validité. Gratuit ; même contrat que POST /v1/address/check. Il n'y a volontairement pas de schéma cbpr+ : cette directive est inaccessible aux lecteurs automatisés, et le champ note de la réponse le rappelle à chaque appel.

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

check_swiss_qr_bill

Contrôle une charge utile de QR-facture suisse, le texte contenu dans le code QR (il commence par SPC), règle par règle : en-tête, IBAN du créancier et plage QR-IBAN, sommes de contrôle des références QRR / SCOR / NON et leur appariement avec l'IBAN, montant, monnaie, et si les adresses du créancier et du débiteur sont structurées (type S) ou encore combinées (type K). La norme a retiré le type K le 21 novembre 2025 et les banques cessent de traiter les paiements qui s'appuient dessus dès le 14 novembre 2026 ; une adresse combinée revient avec proposed_structured, les champs de type S dérivés des lignes combinées. Gratuit, routé vers POST /v1/ch/qr-bill/check.

{ "payload": "SPC\n0200\n1\nCH4431999123000889012\nS\nRobert Schneider AG\nRue du Lac\n1268\n2501\nBiel\nCH\n\n\n\n\n\n\n\n1949.75\nCHF\nS\nPia Rutschmann\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 conformité d'adresse structurée suisse avant l'échéance du 14 novembre 2026. 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.

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

audit_status

Vérifie le statut d'un job d'audit de fichier créanciers créé par audit_creditor_file : s'il est payé, et le lien de téléchargement une fois payé. Passez le session_id reçu à la redirection de succès de l'URL Checkout pour confirmer un paiement qui vient d'avoir lieu immédiatement, sans attendre le webhook. Gratuit.

{ "job": "42aefe9921c83ff967591a89a013598aea91", "session_id": "cs_test_..." }

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

Signaler un résultat faux, une donnée périmée ou absente, ou tout ce qui vous empêche d'utiliser ou de PAYER le service, directement aux opérateurs. Gratuit, et l'outil continue de répondre une fois l'allocation gratuite quotidienne épuisée : plafonner la boîte à réclamations avec la limite qui produit la réclamation ferait taire précisément les rapports qu'elle sert à recevoir. Un humain lit chaque rapport ; une erreur de donnée avérée sur un appel x402 payé est remboursée on-chain. error_type et notes sont requis, le reste est optionnel.

{ "error_type": "wrong_bic", "notes": "BIC résolu vers une banque fusionnée en 2024", "endpoint": "/v1/iban/validate", "contact": "acme@example.com" }

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.

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. Disponible sur les deux transports.

Des résultats qui disent quoi faire ensuite

Chaque résultat de validation porte un champ next_steps ordonné : ce qui bloque un paiement d'abord, ce qui l'enrichit ensuite. Chaque entrée a un code stable sur lequel brancher, une phrase do que l'agent peut relayer, et un because qui nomme le champ de la réponse qui l'a produite — le conseil est auditable au lieu d'être cru sur parole. bank_code_not_allocated veut dire stop ; verify_payee_name veut dire continuer et laisser trancher un contrôle du nom du bénéficiaire.

Exemple de conversation avec un agent

Vous : Cet IBAN est-il valide ? CH10 0023 0000 0000 1234 5

Claude : Je valide cet IBAN. [appelle validate_iban]

Oui, cet IBAN est valide — et le code banque est confirmé au registre SIX : UBS Switzerland AG à Zurich, BIC UBSWCHZH, BC-Nummer 00230, participant SIC avec paiements instantanés en CHF.

Vous : Peux-tu vérifier ces 3 IBAN de la facture fournisseur ?

Claude : Je valide les trois d'un coup. [appelle batch_validate_iban]

2 sur 3 sont valides. Le troisième (FR76...) a une erreur de clé — il semble que deux chiffres aient été inversés.

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 est un client léger de api.ibanforge.com : la donnée vit côté serveur, rien à télécharger, et les résultats reflètent toujours le dernier rafraîchissement des registres.
  • Les résultats sont rendus en texte et en structuredContent MCP. Deux outils d’audit sont propres au module npm ; les autres sont disponibles à distance également.
  • Les versions sont publiées sur npm et reflétées sur le registre MCP.

Voir aussi : Recettes · Ce que « verified » veut dire · Sources des données