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: create one with an email address (200 requests/month, no card). Without a key the server still starts, and paid tools answer with x402 payment instructions that an agent holding USDC on Base can settle per call.

After saving, restart the client. Five IBANforge tools appear in the tools menu.

Option 2 — the hosted endpoint (nothing to install)

https://api.ibanforge.com/mcp

Streamable HTTP transport, 10 free tool calls per IP per day, no key at all: the fastest way for an agent to evaluate the data before committing to anything. For sustained use, run the npm package with your free key.

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

The five 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" }

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; 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.
All five tools return the same JSON as the REST API, both as text and as MCP structuredContent.
Releases are published on npm and mirrored to the MCP registry.