Sebastien Rousseau
Aerial view of illuminated financial district at night

ISO 20022 MCP Suite: documentation.

Add the suite to Claude Code, Claude Desktop or any MCP client in one step, then make your first validated ISO 20022 message from a plain-language prompt.

The ISO 20022 MCP Suite is the open bank-message layer for AI agents: nine vendor-neutral servers to generate, validate, reconcile and settle ISO 20022 payments from natural language. Connect it to the AI client you already use, in one command or one block of JSON, and go from a plain-language prompt to a validated bank message in under a minute. No account, no key, no lock-in.

CHAPTER 1 · CONNECT

Plug the suite into your client.

One command or one block of JSON. Pick the client you already use; every path ends at the same nine servers.

About 5 minutes

CLAUDE CODE

One command in your terminal.

Claude Code registers MCP servers with a single CLI command. The gateway routes every request to whichever of the nine servers the job needs.

  • 1 · Check the prerequisites. Python 3.10+ and uv (brew install uv on macOS). uvx then runs the gateway with nothing to install.
  • 2 · Add the server. One command, from any directory:
claude mcp add iso20022 -- uvx --from "iso20022-mcp[all]" iso20022-mcp
  • 3 · Verify. claude mcp list shows iso20022 as connected, and typing /mcp inside a session lists the gateway's seven meta-tools.
  • 4 · Ask for a payment. Try: "Generate a pain.001 credit transfer paying Acme GmbH EUR 4,200, executing Friday." Claude picks the right tool and returns XSD-validated ISO 20022 XML.

CLAUDE DESKTOP

One block of JSON.

Open Settings › Developer › Edit Config. That opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). Add the server and restart:

{
  "mcpServers": {
    "iso20022": {
      "command": "uvx",
      "args": ["--from", "iso20022-mcp[all]", "iso20022-mcp"]
    }
  }
}
  • Where it shows up. After a restart, the suite's tools appear under the tools icon in the chat box. Claude asks before every tool call, so you approve each step.
  • Installed with pip instead? If you ran pip install "iso20022-mcp[all]", the config is just "command": "iso20022-mcp", no args needed.
  • One entry, every family. Since camt053 0.0.14 and acmt001 0.0.3, the [all] extra resolves cleanly and this single entry covers all nine servers, statements included. Per-family extras such as [pain,pacs] remain available for slimmer installs.

ANY MCP CLIENT

Cursor, VS Code, agents and everything else.

Every server is a standard stdio MCP server on the official registry, so any MCP-capable client can run it with the same command.

  • Registry name. io.github.sebastienrousseau/iso20022-mcp on the official MCP registry; clients that browse the registry can install it from there.
  • Generic config. Command uvx, arguments --from "iso20022-mcp[all]" iso20022-mcp, transport stdio. That is all any client needs.
  • Slimmer installs. Extras select families: pip install "iso20022-mcp[pain,pacs]" covers initiation and interbank transfers only, and each family server (pain001-mcp, pacs008-mcp, camt053-mcp, ...) also runs standalone.
  • Beyond payments. The suite is nine of the thirteen MCP servers published under this account. The other four: corral (query your local mirror of cloned repositories), inclusio-mcp (accessibility-first LaTeX publishing), noyalib-mcp (lossless YAML parsing and validation) and rlg-mcp (log streams for agents). All thirteen are on the official registry.

EVERY MCP CLIENT

Works with every MCP client.

Claude Code and Claude Desktop are covered above. Below is the same stdio server in each other client's documented config shape, checked against the official documentation in July 2026. Remote-first platforms connect to hosted MCP servers instead, so they get an honest sentence, not a fake command.

Cursor

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json to make the suite available everywhere:

{
  "mcpServers": {
    "iso20022": {
      "command": "uvx",
      "args": ["--from", "iso20022-mcp[all]", "iso20022-mcp"]
    }
  }
}

Windsurf

Same mcpServers shape, in ~/.codeium/windsurf/mcp_config.json. Add the identical iso20022 entry shown for Cursor.

VS Code with GitHub Copilot

Create .vscode/mcp.json in your workspace. VS Code is the odd one out: the top-level key is servers, not mcpServers:

{
  "servers": {
    "iso20022": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "iso20022-mcp[all]", "iso20022-mcp"]
    }
  }
}

Google Gemini CLI

Add an mcpServers block to ~/.gemini/settings.json (or .gemini/settings.json per project), with the identical iso20022 entry shown for Cursor. Transport is inferred: a command key means stdio.

OpenAI Agents SDK

The Python Agents SDK spawns local stdio servers itself through MCPServerStdio, with the same command and args:

async with MCPServerStdio(
    name="iso20022",
    params={
        "command": "uvx",
        "args": ["--from", "iso20022-mcp[all]", "iso20022-mcp"],
    },
) as server:
    agent = Agent(name="Treasury", mcp_servers=[server])

ChatGPT and the OpenAI Responses API. Remote-first: they connect only to MCP servers reachable over the public internet, via Streamable HTTP or HTTP/SSE and a server_url. They do not run local stdio processes, so pairing them with this suite means hosting it yourself; the verified bridge below is the starting point.

Microsoft Copilot Studio. Adds MCP servers to agents as tools through Power Platform connectors, over the Streamable HTTP transport only. No local stdio support.

Zapier MCP. The inverse case: Zapier hosts a remote MCP endpoint exposing Zapier actions to your AI client via a generated mcp.zapier.com URL. It is a place agents call out to, not a way to run this suite.

SELF-HOST FOR REMOTE-ONLY CLIENTS

One bridge command, verified end to end.

Remote-first platforms only speak Streamable HTTP. The community mcp-proxy bridge serves this suite's stdio gateway over exactly that transport, in one command:

uvx mcp-proxy --port 8096 -- uvx --from "iso20022-mcp[all]" iso20022-mcp
  • Verified, not assumed. On 16 July 2026, with mcp-proxy 0.12.0, a raw Streamable HTTP client against https://sebastienrousseau.com/mcp/ completed the MCP initialize handshake, listed all seven gateway meta-tools and received a schema-valid pain.001.001.03 from generate. The same bridge also exposes an SSE endpoint at /sse.
  • Localhost by default. The bridge binds 127.0.0.1. Remote platforms need a publicly reachable URL, so exposing this to the internet means adding your own TLS, authentication and network policy in front; neither the bridge nor the suite ships an authentication layer.
  • Know the trade. mcp-proxy is a third-party bridge on PyPI, not part of this suite, and self-hosting gives up the local-only posture the stdio servers are built around: requests now cross a network hop that you operate and must secure.

CHAPTER 2 · FIRST PAYMENT

From plain language to validated XML.

Learn the loop with three prompts, then run a template that has been proven end to end.

About 10 minutes

YOUR FIRST FIVE MINUTES

Prompts to paste.

Seven meta-tools (search, list_families, list_servers, describe, validate, generate, parse) cover every family. These three prompts take you from discovery to generated XML; Chapter 3 closes the loop with statements.

  • Discover. "Which ISO 20022 message cancels a payment that already went out?" The gateway's search points at camt.056 and the camt-exceptions server.
  • Understand. "What fields does a pacs.008 need?" describe returns the required fields and the input schema.
  • Generate. "Create a pain.001 paying two suppliers EUR 1,850 and EUR 3,200 from our EUR account." generate returns validated XML, checked against the official XSD before you ever see it.

TESTED PROMPT TEMPLATE

A pain.001 prompt, proven end to end.

Paste this into any connected client. On 15 July 2026 this exact record set was driven over stdio JSON-RPC through the suite's generate tooling and came back as a schema-valid pain.001.001.03 document.

Generate a SEPA pain.001.001.03 customer credit transfer and return the validated XML.
Use exactly these records:
- Message: MsgId MSG-2026-07-15-001, created 2026-07-15T09:30:00.000Z, 1 transaction, control sum 4200.00.
- Initiating party (InitgPty): Acme Treasury GmbH, Mainzer Landstrasse 50, 60325 Frankfurt am Main, DE.
- Payment block (PmtInf): PmtInfId PMT-2026-07-15-001, method TRF, batch booking "false", service level SEPA, requested execution date 2026-07-17.
- Debtor (Dbtr): Acme Treasury GmbH, same address as the initiator, IBAN DE89370400440532013000, agent BIC COBADEFFXXX.
- Creditor (Cdtr): Fournier Conseil SARL, Rue du Faubourg Saint-Honore 8, 75008 Paris, FR, IBAN FR1420041010050500013M02606, agent BIC BNPAFRPP.
- Transaction: payment id TXN-2026-07-15-001, amount EUR 4200.00, charge bearer SLEV, purpose code SUPP.
- Remittance (RmtInf): invoice INV-2026-183 dated 2026-07-01.
Validate the records first, then generate. If validation fails, name the failing field and stop.
  • What came back. A pain.001.001.03 Document (namespace urn:iso:std:iso:20022:tech:xsd:pain.001.001.03) carrying MsgId MSG-2026-07-15-001, structured PstlAdr blocks for all three parties, InstdAmt Ccy="EUR" 4200.00 and structured remittance. The tool validates against the bundled official XSD before returning; we re-validated the returned document independently and it passed.
  • Checked identifiers. Both IBANs pass a mod-97 integrity check (Python stdlib, no library), and both BICs match the ISO 9362 shape the input schema enforces.
  • Two field gotchas we hit. date must be a full ISO datetime (2026-07-15T09:30:00.000Z), not a bare date, and batch_booking must be the lowercase string "false". pain.001.001.03 also requires structured addresses for initiator, debtor and creditor.
  • Gateway note, retested. Gateway 0.0.2 had a response-shape bug returning pain-family generate results, which is why this template was first proven against pain001-mcp directly. Fixed upstream: on 16 July 2026, gateway 0.0.4 (what the [all] one-liner installs today) returned a schema-valid pain.001.001.03 from its generate meta-tool on the first call, driven over stdio JSON-RPC with the same natural flat records.

WHAT THE TOOL RETURNED

The opening of the returned document.

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
    <CstmrCdtTrfInitn>
        <GrpHdr>
            <MsgId>MSG-2026-07-15-001</MsgId>
            <CreDtTm>2026-07-15T09:30:00.000Z</CreDtTm>
            <NbOfTxs>1</NbOfTxs>
            <InitgPty>
                <Nm>Acme Treasury GmbH</Nm>
                <PstlAdr>
                    <StrtNm>Mainzer Landstrasse</StrtNm>
                    <BldgNb>50</BldgNb>
                    <PstCd>60325</PstCd>
                    <TwnNm>Frankfurt am Main</TwnNm>
                    <Ctry>DE</Ctry>
                </PstlAdr>
            </InitgPty>
        </GrpHdr>

CHAPTER 3 · STATEMENTS AND RECONCILIATION

Read what happened. Match it to what you expected.

The money went out in Chapter 2. The bank answers with a camt.053 statement; the suite parses it and reconciles it against your expected payments, explainably.

About 10 minutes

STATEMENTS IN, MATCHES OUT

Four steps, one loop closed.

You registered camt053 as its own server in Chapter 1; these steps use it together with reconcile-mcp.

  • 1 · Parse. "Here is our camt.053 statement, what came in yesterday?" parse turns bank XML into structured data Claude can reason over. On the camt053 server, parse_statement reads the XML, list_entries lists every booked entry, and filter_entries pulls the entries carrying a given return reason code.
  • 2 · Normalise. reconcile-mcp adapts both sides into canonical records: normalize_pain001 turns parsed payment instructions into expected records, normalize_camt053 turns parsed statement entries into observed ones.
  • 3 · Reconcile. reconcile(expected, observed) returns exact matches, short/over payments, split settlements (one-to-many), batch credits (many-to-one) and unmatched residuals, each with an explainable score and reasons; explain_match breaks down every signal for a single pair when you tune.
  • 4 · No data yet? Use the sandbox. list_sandbox_scenarios, load_sandbox_scenario and run_sandbox_scenario ship deterministic fixtures, so you can watch a full, explainable reconciliation with zero real data.

Every parameter of every tool named here is in the camt053 and reconcile sections of the tool reference.

CHAPTER 4 · GO DEEPER

The right server, the guardrails, the migration.

Slim your install to the one server a job needs, see why the suite is safe to hand to an agent, and plan the 2026-2028 move off MT.

About 5 minutes

WHICH SERVER DO I NEED?

One job, one server.

Install the gateway and let it route, or install just the one for the task in front of you. Every server is pip install-able and live on the official MCP registry.

Discover & route

Start here. The gateway's search / describe / generate / validate / parse meta-tools span every family.

iso20022-mcp

Initiate a payment

pain.001 customer credit transfers, with IBAN/BIC and XSD validation and an MT101 converter.

pain001-mcp

Settle interbank

pacs.008 transfers, pacs.004 returns, pacs.002 status, the Nov-2026 address toolkit, MT103.

pacs008-mcp

Reconcile

Match camt.053 statements against expected pain.001 (exact, partial, split, batch), explainably.

reconcile-mcp

Cancel & resolve

camt.056 payment cancellation and camt.029 resolution of investigation, XSD-valid.

camt-exceptions

Full tool reference for every server · End-to-end recipes

SAFE BY DESIGN

Built to hand to an agent.

  • Validated before return. Every generator checks its output against the official bundled XSD before it hands it back; malformed messages never leave the tool.
  • Never moves money. The AP2/x402 bridge only transforms and validates; producing a message is deliberately separate from sending it, so the money-movement step stays a human-guarded action.
  • Read-only where it counts. Reconciliation is pure matching; every tool is marked read-only, idempotent and closed-world so clients can reason about safety.
  • Provenance you can audit. Bundled schemas are the official ISO 20022 XSDs; every server is Apache-2.0 at 100% branch-test coverage, on PyPI and the official MCP registry.

THE 2026–2028 MIGRATION

Move off MT, one message at a time.

MT/MX coexistence ended in November 2025; MT retires through 2028, and structured postal addresses become mandatory in November 2026. The suite ships the tools for exactly this.

  • MT → MX converters. convert_mt103 → pacs.008, convert_mt101 → pain.001, convert_mt940/convert_mt942 → camt, with validated output wired into the servers.
  • Structured-address toolkit. classify / validate-by-policy / repair / batch, in pacs008-mcp, for the November 2026 cliff.
  • Exceptions ready. pacs.004 returns and pacs.002 status in pacs008-mcp; camt.056 cancellation and camt.029 resolution in camt-exceptions.

OPEN SOURCE · APACHE-2.0 · ON PYPI + THE MCP REGISTRY

Back to the suite.

Nine servers, the whole ISO 20022 payment lifecycle, installable in one line.

Explore the suite · Tool reference