Skip to content
IBANforge

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): where the Add custom connector dialog shows a Request headers section, add the header Authorization with the value Bearer ifk_your_key. Anthropic's documentation, read on 10 November 2026, says this section is in beta and open to a limited set of organizations: if you do not see it, your account does not have it yet. The authentication settings of an existing connector, request headers included, cannot be changed: remove it, then add it again with the key. On Team and Enterprise, everyone who uses the connector then shares that key. Without that section, use the npm package in Claude Desktop (Option 1) or Claude Code (above). 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 (Anthropic's help page on custom connectors, 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 where its dialog offers that section, 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: read on 10 November 2026; 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 (Anthropic's documentation, read on 10 November 2026). Custom connectors are available on the Free, Pro, Max, Ultra, Team and Enterprise plans; on the Free plan, one custom connector. Not tried by us.

  • Shortcut (individual plan): open Claude's Add custom connector dialog with this address filled in. Claude shows the values and asks you to confirm before anything is added.
  • Individual plan: open Customize > Connectors, click Add custom connector, enter https://api.ibanforge.com/mcp, then Add. The dialog differs from one account to another: if it asks how people connect, choose No sign-in, since this server asks for no account. To use your key, see With your key above.
  • Team or Enterprise: an Owner opens Organization settings > Connectors, selects Add, then Custom (and Web if Claude asks for the connector type), enters the address and clicks Add; members then find it in Customize > Connectors and click Connect.
  • In a conversation: the + button 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

The JSON objects below are tool arguments, passed through your MCP client. They are documentation examples and do not establish that an account exists. For a free first check on either transport, use validate_payment_reference without an IBAN. Read tools/list in your session: the installed package and hosted server can evolve separately.

validate_iban

Checks the IBAN structure and checksum, then returns the bank information available. Read valid, bank_code_check and bic separately. A missing BIC, unavailable source or default classification needs interpretation; it does not prove a closed account or fraud. Keep source, as_of, basis and authoritative when present. Read the result.

{ "iban": "CH1000230000000012345" }

batch_validate_iban

Accepts 1 to 100 IBANs and returns an object with results, count and valid_count. Results follow input order. Preserve that order and your row identifiers; the tool does not rewrite a supplier file. Key and metering rules follow the selected transport. Batch guide.

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

lookup_bic

Looks up an institution from a BIC you already have. The input field is bic, not code, in both the npm package and hosted server. valid_format describes the BIC's format; found says whether a record was found. Name, LEI and address may be missing or carry different dates. BIC guide.

{ "bic": "UBSWCHZH80A" }

lookup_ch_clearing

Looks up a Swiss or Liechtenstein IID / BC-Nummer. Read found, the institution and participation information available, and their provenance. A qr_iid assignment may come from the register or be inherited from the head office: keep qr_iid_source. An IID in the QR range does not establish that the account exists. Clearing guide.

{ "iid": "230" }

check_compliance

Adds bank and country indicators to the validation result. Read consultation states (screened, bank_screened), null values, flags and source dates before the score. The score does not replace a review. A bank's presence in the VoP register is not a payee-name check; bank screening does not screen the beneficiary. Understand the checks.

{ "iban": "CH1000230000000012345" }

validate_payment_reference

On hosted /mcp without a key, this tool still consumes the free allowance.

Checks an RF/SCOR, QRR, OGM/VCS or viitenumero reference. Without an IBAN, this call is free on both transports. First-check example:

{ "reference": "RF18539007547034" }

An optional IBAN adds a pairing check. Transport difference: the hosted HTTP server performs this check for free; the npm 1.10.0 package instead calls POST /v1/iban/validate, under that route's access conditions. Do not present the following example as free in every client. valid and pairing are independent. For KID and OCR, valid: null means that the creditor account configuration is needed, not that the reference is invalid.

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

check_postal_address

Checks format rules for sps, hvps_plus or fedwire, for free. Keep each finding's source and the note field; not_applicable is not a passed check. The tool does not verify that a street exists. For CH/LI, the separate postcode_locality block describes the postcode/town match where possible. Rules and timelines.

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

check_swiss_qr_bill

Checks Swiss QR-bill text starting with SPC, for free: structure, IBAN, reference and pairing, amount, currency and addresses. It does not decode an image. valid describes the checked content, not the account or acceptance by a bank. A proposed_structured value remains a proposal to review. Keep the sources of findings; QR-bill and payment-order timelines differ. QR-bill guide. The payload names below are fictional.

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.

{ "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

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 the address checks described in the report. 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.

The example contains one fictional row. Base64 encoding does not encrypt the file: its content is sent to the service. Use only data you are authorized to transmit; a masked preview does not mean the file stayed local. File audit.

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

audit_status

Reads the status of the job returned by audit_creditor_file. The identifier below is fictional: replace it with the one from your response. An optional session_id comes from your own Checkout return; do not invent it. This tool does not make a payment. Download availability depends on the job's state.

{ "job": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }

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

Sends feedback to the operators: this action writes a message and is not a connection test. error_type and notes are required; exclude keys, customer files and sensitive bank details. The tool is free and has its own abuse protections. A human reads every one. The example below is a template to adapt, not an observed fault.

{"error_type": "stale_bic", "notes": "Replace with the affected BIC, public source and expected result.", "endpoint": "/v1/iban/validate"}

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 where the dialog shows that section (the connector has to be removed and added again), 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.

Read a response without inventing a verdict

The MCP client receives an envelope with content and, for structured responses, structuredContent. First check whether the call failed. isError: true or a protocol error is not valid: false: neither guarantees a usable business result.

SituationPreserve this distinction
valid: false in a successful responseThe IBAN check failed; read the details.
bic: null, unknown or an unavailable sourceIncomplete or unknown result; keep that state.
Refusal 401, 402 or 429Access, quota or rate issue; read the message and retry_after when present.
Timeout, network failure or unreadable responseNo complete result arrived; the request may have reached the server.

The validate_iban tool in the npm 1.10.0 package can return a degraded format check when a keyless trial is refused with 402: _degraded: true and _scope: "format_only". This is not full bank resolution. A configured key that is refused does not trigger that fallback. The package does not sign x402 payments or recreate a key to continue.

next_steps contains recommendations computed from the result. Keep their code, do and because when present, then inspect the referenced fields. These recommendations do not authorize a payment, a change to bank details or a conclusion about the account holder. Missing sources remain missing sources. Errors and access.

The codes bank_code_not_allocated, modulus_check_failed and national_check_digits_failed flag a blocking check to resolve before continuing processing. They concern bank-code allocation, the UK sort-code/account-number pairing and national check digits respectively. national_check_digits_suspect calls for confirmation of the number without declaring it invalid; verify_payee_name calls for a separate beneficiary-name check. The absence of a code does not authorize payment.

A reproducible first check

Check only the documentation reference RF18539007547034 with validate_payment_reference, without an IBAN. Return the recognized scheme, valid and the source received. If the call fails, explain the error without inventing a result.

For a bank-resolution test, then call validate_iban with the example in its section. Ask the assistant to report the values received and their provenance, including unknown fields. This page does not guarantee a bank name or register result.

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 sends arguments to the IBANforge API. It is not an offline bank-data service.
  • Sources have different dates and coverage. Read the dates actually returned; a recent call can consult an older source.
  • The tools/list schemas describe the connected version. The two audit tools are specific to the npm package.
  • Access, pricing and errors are detailed under API keys, pricing and the error guide.