MCP Integration

IBANforge ships an official MCP server for AI agents: ibanforge-mcp on npm, plus a hosted endpoint with nothing to install. Claude, Cursor, or any MCP-compatible client can validate IBANs, resolve BICs, check Swiss clearing numbers and run a compliance pre-check as tool calls.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants use external tools. Instead of asking the user to copy-paste API results, the agent calls the tool directly and gets structured data back.

Option 1 — the npm package (stdio)

Claude Desktop — add IBANforge to the configuration file:

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_your_key" }
    }
  }
}

Claude Code — one command:

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

The key is optional and free — 25 requests/month without email. Generate one with a bodyless POST, then send Authorization: Bearer ifk_.... Claim the same key with an emailed code to raise its quota to 200/month, without a card.

After saving, restart the client. The npm package exposes 13 tools, the remote HTTP server 11. The two file-audit tools are only available in the npm package. See the catalogue by transport.

Option 2 — the hosted endpoint (nothing to install)

https://api.ibanforge.com/mcp

Streamable HTTP transport, 25 free tool calls a week per source address, no key at all (ISO week in UTC, reset on Monday 00:00 UTC; a batch counts one call per IBAN; separate from the keyless REST trial): the fastest way for an agent to evaluate the data before committing to anything. For sustained use, send your free key with each request (below), or run the npm package with it.

With your key

The hosted endpoint reads an IBANforge key sent in a request header, Authorization: Bearer ifk_… or X-API-Key: ifk_…, the same two headers as the REST API. The tool calls are then counted against that key exactly as REST calls are: its own allowance, one unit per call, one per IBAN in a batch, nothing on the free tools, and the same refusals. The keyless allowance above is no longer used. A key written in the address (?api_key=) is not read. If the key is unknown, revoked or used up, the tool answers with the REST message for that key and never falls back to the keyless allowance.

Claude Code:

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

Claude and Claude Desktop (custom connector, steps below): under Request headers, add the header Authorization with the value Bearer ifk_your_key. Claude's page, read on 7 October 2026, describes this field for fixed credentials such as API keys. On Team and Enterprise, everyone who uses the connector then shares that key. Not tried by us.

ChatGPT: OpenAI's authentication page, read on 7 October 2026, says ChatGPT connects to an MCP server with OAuth or with no authentication, and cannot present a custom API key. In ChatGPT the hosted endpoint therefore stays on its keyless allowance; your key serves on the REST API, or with the npm package in another client.

Gemini: not checked by us.

Add it as a connector in a chat assistant

In a chat assistant, the address above becomes a custom connector: the assistant then calls the MCP tools itself instead of guessing an answer it cannot fetch.

A connector with no key draws on the same keyless allowance as any other caller, counted per source address. In Claude, a connector's calls leave from Anthropic's cloud, not from your device (official page below, section "Network requirements"): that allowance is therefore shared with other users and may already be spent when you start. Other assistants: not checked by us. With your own key, the connector is counted on that key instead: see With your key above (Claude takes it as a request header, ChatGPT sends none). A POST to https://api.ibanforge.com/v1/keys/generate with no body returns a key, no e-mail.

Where to click, from the linked official pages. Claude, ChatGPT and Gemini: read on 24 September 2026; Mistral and Perplexity: read on 23 October 2026. Menus move; the linked page is the reference.

Claude (official page, updated 11 August 2026). Custom connectors are available on the Free, Pro, Max, Team and Enterprise plans; Free users are limited to one custom connector. Not tried by us.

Individual plan (the page lists these steps under Pro and Max): open Customize > Connectors, click + then Add custom connector, enter https://api.ibanforge.com/mcp, and click Add. The OAuth fields under Advanced settings are optional; this server asks for no authentication. To use your key, fill Request headers (see With your key above).
Team or Enterprise: an Owner opens Organization settings > Connectors, clicks Add, hovers over Custom and selects Web, enters the address and clicks Add; members then find it in Customize > Connectors and click Connect.
In a conversation: the + button at the lower left of the chat, then Connectors, to switch it on.

ChatGPT (official page). Developer mode, on the web, for Pro, Plus, Business, Enterprise and Education accounts: not on the free plan. Not tried by us.

Turn it on: Settings → Security and login, then Developer mode.
Add the server: go to ChatGPT Plugins, select the plus button and create a developer-mode app for the remote MCP server https://api.ibanforge.com/mcp. The page lists streaming HTTP among the protocols and No Authentication among the options.
In a conversation: choose Developer mode from the Plus menu and select the app.

Gemini (official page). Custom apps require being 18 or over and in the US, a personal Google Account (not a work or school one), Keep Activity turned on, and English; they are added in the Gemini web app only, then work on the web and in the mobile app. Not tried by us.

At gemini.google.com, click Settings at the bottom, then Connected Apps; under "Custom apps", add a custom app, enter https://api.ibanforge.com/mcp, click Next and follow the on-screen instructions.
The page asks for credentials under "Advanced features" when a server does not support Dynamic Client Registration. This server asks for no authentication; whether Gemini accepts that is not checked by us.
In a prompt: type @ and select the app.

Mistral (Le Chat) (official connector guide, now under Vibe Work, read on 23 October 2026). Administrator access is required; Free, Pro and Student account owners are administrators by default. Not tried by us.

Open Connectors → + Add Connector → Custom MCP Connector. Name it IBANforge, enter https://api.ibanforge.com/mcp as the server URL, then Connect.
The guide describes automatic authentication detection, including no authentication. IBANforge can be tried without a key; adding a key in this assistant has not been checked by us.

Perplexity (official page, read on 23 October 2026). Available on Pro, Max and Enterprise, according to the release announcement. Organization members need their administrator to allow custom connectors. Not tried by us.

Open Plugins → Add custom → Connector → Add MCP connector → Remote. Without Plugins, start from Customize → Connectors.
Name it IBANforge, enter https://api.ibanforge.com/mcp, choose Streamable HTTP and None for authentication to try it without a key. Read the acknowledgement, then Add and open the connector card to enable it. The guide also lists API-key authentication; its header handling with IBANforge has not been checked by us.

For connector directories, https://api.ibanforge.com/mcp/directory exposes the same tools without prices or offers. It shares the limits and counters of /mcp: switching addresses does not give another allowance. This address does not mean IBANforge has been accepted into an assistant's directory.

On the official MCP registry the server is listed as io.github.cammac-creator/ibanforge.

Available tools

validate_iban

Validate a single IBAN: structure and checksum, issuing bank (BIC), bank-code check against the national register, EMI/vIBAN classification, SEPA/VoP reachability and risk indicators — the same data as POST /v1/iban/validate.

{ "iban": "CH1000230000000012345" }

batch_validate_iban

Up to 100 IBANs in one call, each result identical in structure to validate_iban — same as POST /v1/iban/batch.

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

lookup_bic

Institution details for a BIC/SWIFT code: name, country, city, branch, LEI where available — same as GET /v1/bic/:code.

{ "code": "UBSWCHZH80A" }

lookup_ch_clearing

Swiss BC-Nummer / IID lookup: institution, type, town, SIC/euroSIC participation and QR-IID allocation — same as GET /v1/ch/clearing/:iid.

{ "iid": "230" }

check_compliance

Full pre-check in one call: sanctions screening on the resolved bank BIC, FATF status, SEPA Instant reachability, VoP participation and a composite risk score from 0 to 100 — same as POST /v1/iban/compliance.

{ "iban": "CH1000230000000012345" }

validate_payment_reference

Validate a structured payment reference — RF/ISO 11649 (SCOR), Swiss QR reference (QRR), Belgian OGM/VCS, Finnish viitenumero — and, when an iban is supplied, decide whether the two may legally travel together. Free; same contract as GET /v1/reference/validate plus the pairing verdict.

valid and pairing are independent: a reference can be arithmetically valid and still illegal on that account. Norwegian KID and Swedish OCR answer valid: null — their rules are configured per creditor account by the beneficiary bank — and must never be relayed as "invalid".

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

check_postal_address

Check a structured ISO 20022 postal address against a payment rail's published rules — sps (Swiss Payment Standards), hvps_plus (T2) or fedwire — rule by rule, each finding citing the document and its validity date. Free; same contract as POST /v1/address/check. There is deliberately no cbpr+ scheme: that guideline is unreachable to automated readers, and the response's note says so on every answer.

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

check_swiss_qr_bill

Check a Swiss QR-bill payload, the text inside the QR code (it starts with SPC), rule by rule: header, creditor IBAN and QR-IBAN range, QRR / SCOR / NON reference checksums and their pairing with the IBAN, amount, currency, and whether the creditor and debtor addresses are structured (type S) or still combined (type K). Address type K has not been permitted in a QR-bill since 21.11.2025 (SIX, QR-bill IG 2.3). The banks guarantee payment of such a QR-bill only until the end of September 2026 (UBS: 30.09.2026; ZKB: end of September 2026 at the latest). A type K QR-bill may therefore be refused at payment: reissue it with type S. From 14.11.2026, the Swiss Payment Standards require a structured or hybrid address in a payment order, with the town and country in their own fields. The SIC system does not validate addresses: each bank decides. Some still accept domestic Swiss payments for now; a SEPA or international payment without a town may be rejected. Also redo the standing orders and templates captured from a type K QR-bill. A combined address comes back with proposed_structured, the S-type fields derived from the combined lines. Free, routed to 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

Audit an entire creditor/supplier payment file (CSV or XLSX) row by row: IBAN structure and checksum, bank code against the national register, bank name and BIC, SEPA reachability and issuer type, plus checks a single IBAN call cannot make because they need the whole file — duplicate IBANs, the BIC the file carries against the BIC the register derives, address country against IBAN country, and Swiss structured-address conformity ahead of the 14 November 2026 deadline. Returns a free preview only (masked IBANs, summary counts, up to 20 rows) — the full annotated .xlsx report is a paid deliverable ($149 up to 5,000 rows, $349 up to 20,000) settled through a one-off Stripe Checkout Session, never paid automatically. Pass checkout: true to also get the Checkout URL for a human to open. Base64-encode the file and send it as file_base64; files over 5 MB are refused locally, before any network call: beyond that the base64 payload breaks the stdio channel and the agent loses its connection instead of getting an error. The HTTP route accepts up to 10 MB — use it for a large file.

{ "file_base64": "Tm9tO0lCQU4KU29jaWV0ZSBBbHBoYTtDSDEwMDAyMzAwMDAwMDAwMTIzNDUK", "filename": "creditors.csv", "lang": "en" }

audit_status

Check the status of a creditor-file audit job created by audit_creditor_file: whether it is paid, and the download link once it is. Pass the session_id from the Checkout URL's success redirect to confirm a just-completed payment immediately, without waiting for the webhook. Free.

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

audit_creditor_file and audit_status are on the npm package (Option 1) only, for now — not yet on the hosted HTTP endpoint (Option 2).

send_feedback

Report a wrong result, stale or missing data, or anything blocking you from using or PAYING for the service, straight to the operators. Free, and it keeps working after the free allowance is spent: capping the complaint box with the limit that produced the complaint would silence the reports it exists for. A human reads every one; a verified data error on a paid x402 call is refunded on-chain. error_type and notes are required, the rest is optional.

{ "error_type": "wrong_bic", "notes": "BIC resolved to a bank that merged in 2024", "endpoint": "/v1/iban/validate", "contact": "acme@example.com" }

request_api_key

Request a key without email: the tool returns a link for a person to open and approve in their browser. Available on both transports.

The key does not unlock the session that asked for it: it works once placed in the client configuration, after a reconnection. Where it goes:

Claude Code with the npm package: the config_line that poll_api_key returns, a claude mcp add … -e IBANFORGE_API_KEY=… command.
Claude Code on the hosted endpoint: --header "Authorization: Bearer ifk_…" (see With your key).
Claude and Claude Desktop: the Request headers of the custom connector, or IBANFORGE_API_KEY in claude_desktop_config.json with the npm package (Option 1).
ChatGPT: nowhere on a connector, which sends no key; the key serves on the REST API.
Any HTTP client: the REST API, with Authorization: Bearer ifk_….

poll_api_key

Collect the approved key with the device_code returned by request_api_key. The key is returned only once: keep it, and put it where the list above says. Available on both transports.

Results that say what to do next

Every validation result carries an ordered next_steps field: what blocks a payment comes first, what merely enriches it after. Each entry has a stable code to branch on, a do sentence the agent can relay, and a because naming the response field that produced it, so the advice is auditable rather than taken on trust. bank_code_not_allocated means stop, and so do modulus_check_failed (a UK sort code and account number that cannot be a real pair) and national_check_digits_failed (the national check key inside the IBAN does not match, so the account number cannot have been issued as written); national_check_digits_suspect (Germany only, a Bundesbank method published without test numbers) means confirm the account number with the beneficiary, never stop; verify_payee_name means carry on and let a beneficiary name check decide.

Example agent conversation

You: Is this IBAN valid? CH10 0023 0000 0000 1234 5

Claude: Let me validate that IBAN for you. [calls validate_iban]

Yes, that IBAN is valid — and the bank code is confirmed in the SIX register: UBS Switzerland AG in Zürich, BIC UBSWCHZH, Swiss BC-Nummer 00230, SIC participant with CHF instant payments.

You: Can you check these 3 IBANs from our supplier invoice?

Claude: I'll validate all three at once. [calls batch_validate_iban]

2 out of 3 are valid. The third one (FR76...) has a checksum error — it looks like a digit was transposed.

Works well with

PayQR — npx -y @czagents/payqr, hosted MCP https://payqr.cz-agents.dev/mcp, registry dev.cz-agents/payqr. Generate and self-check a European payment QR from an IBAN and payment details: SPAYD for CZ/SK accounts, or EUR-only EPC/GiroCode for other SEPA accounts; EPC requires recipient_name. PayQR validates the IBAN checksum but does not verify account ownership or the beneficiary name, and it does not generate native Swiss QR-bills — the register check, VoP readiness and risk indicators are exactly what IBANforge adds on top.

Supported clients

Claude Desktop and Claude Code — native MCP support
Cursor and Continue.dev — via their MCP configuration
n8n — prefer the dedicated community node
Custom agents — any app using the MCP SDK

Notes

The npm package is a thin client for api.ibanforge.com: the data lives server-side, there is nothing to download, and results always reflect the latest register refresh.
Results are returned as text and MCP structuredContent. Two audit tools are exclusive to the npm package; all other tools are also available remotely.
Releases are published on npm and mirrored to the MCP registry.