iso20022-readiness-suite-mcp: The ISO 20022 Readiness & Testing Gateway

[![PyPI Version][pypi-badge]][07] [![Python Versions][python-versions-badge]][07] [![License][license-badge]][01] [![Tests][tests-badge]][tests-url] [![Quality][quality-badge]][quality-url] [![OpenSSF Scorecard][scorecard-badge]][scorecard-url] [![Documentation][docs-badge]][docs-url]

A high-level orchestration [Model Context Protocol][mcp] server — the White-Label ISO 20022 Readiness & Testing Gateway. It is an MCP server to your agent and an MCP client to the foundational servers of the ISO 20022 MCP Suite. It composes them into readiness scoring, automated remediation, clearing-profile linting (CBPR+, SEPA_Instant, FedNow, Generic), and bank-response simulation — one gateway an agent can drive to answer "is this payment ready, and if not, fix it".

The November 2026 milestones. As the major schemes (CBPR+, HVPS+, T2, FedNow) tighten their ISO 20022 requirements — structured postal addresses chief among them — a payment that was fine yesterday can be rejected tomorrow. iso20022-readiness-suite-mcp puts a single readiness gateway in front of your agent: run_readiness_check scores a payload against a clearing profile, remediate_payload proposes the compliant form, and simulate_bank_response mocks how a bank would answer. v0.0.2, stdio (default) or streamable HTTP, 4 tools, Python 3.10+.

Contents

• Overview
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Tools
• HTTP transport & authentication
• Orchestration & the meta-client pattern
• Open-core vs premium
• When not to use iso20022-readiness-suite-mcp
• Development
• Security
• Documentation
• License
• Contributing
• Acknowledgements

Overview

The [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents and assistants discover and call external tools in a uniform way. iso20022-readiness-suite-mcp is the orchestration front door of the ISO 20022 MCP Suite: it presents four high-level tools to the outer agent, and underneath it acts as an MCP client that spawns the foundational suite servers over stdio and composes their results — the meta-client pattern.

The headline capability is the one-shot readiness workflow: hand it a raw ISO 20022 payload and a target clearing profile, and it detects the message type, routes it to the correct base validator, lints it against the profile's market-practice rules, and returns a single readiness score with the findings — then, on request, remediates the payload and simulates how a bank would respond.

Every tool returns typed, JSON-serialisable data; on any failure — a bad input, an unparseable payload, a missing or erroring sub-server — it returns an {"error": ...} payload rather than raising into the client transport.

• Website: https://sebastienrousseau.github.io/iso20022-readiness-suite-mcp/
• Source code: https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp
• Bug reports: https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp/issues

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["iso20022-readiness-suite-mcp<br/>(orchestration gateway)"]
    B -->|spawns over stdio via uvx| C["iso20022-mcp"]
    B -->|spawns over stdio via uvx| D["camt053-mcp"]
    B -->|spawns over stdio via uvx| E["pain001-mcp"]
    B -->|spawns over stdio via uvx| F["reconcile-mcp"]
    B -->|spawns over stdio via uvx| G["bankstatementparser-mcp"]
    B -->|spawns over stdio via uvx| H["structured-address-fix-mcp"]

The gateway is a server to the client above it and a client to the six foundational servers below it. list_profiles and simulate_bank_response are fully local and need none of them; run_readiness_check and remediate_payload reach the sub-servers and therefore require them to be installed and resolvable (see Orchestration & the meta-client pattern).

The ISO 20022 MCP Suite

iso20022-readiness-suite-mcp is the orchestration gateway that sits on top of a set of coordinated, vendor-neutral MCP servers for the ISO 20022 migration. Dependency ranges are kept aligned across the suite, so the servers co-install cleanly in a single Python environment: install the foundational servers you need, then let this gateway compose them.

Where each foundational server does one job well, this gateway composes them: it detects and routes a payload to the right validator, lints it against a clearing profile, scores its readiness, remediates it, and simulates the bank's answer — all behind four agent tools.

Install

iso20022-readiness-suite-mcp runs on macOS, Linux, and Windows and requires Python 3.10+ and pip. It pulls in the MCP SDK, pydantic, and defusedxml automatically.

python -m pip install iso20022-readiness-suite-mcp

To exercise run_readiness_check and remediate_payload end to end, also make the foundational servers resolvable — the gateway launches them with uvx, so installing uv is enough for a zero-install spawn:

python -m pip install uv        # provides the `uvx` launcher

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U iso20022-readiness-suite-mcp

Quick Start

For the 10-minute install → MCP client config → first conversation tutorial, see docs/quickstart.md.

Launch the server over stdio (the FastMCP default transport):

iso20022-readiness-suite-mcp

Register it with any MCP client (e.g. Claude Desktop) by adding it to the client's configuration:

{
  "mcpServers": {
    "iso20022-readiness-suite": { "command": "iso20022-readiness-suite-mcp" }
  }
}

The command speaks MCP on stdin/stdout — it is meant to be launched by an MCP client, not used interactively. The agent can then call the tools below.

You can also invoke the tools in-process — without a transport — straight through the FastMCP instance. This mirrors what an agent receives over stdio. The two local tools (list_profiles, simulate_bank_response) need no sub-servers:

import asyncio

from iso20022_readiness_suite_mcp import server


async def main() -> None:
    async def call(name, args):
        result = await server.server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (read .content); 1.x
        # returns the content list, or a (content, meta) tuple.
        content = getattr(result, "content", None)
        if content is None:
            content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # Which clearing profiles can I target? (fully local)
    print(await call("list_profiles", {}))
    # -> [{"profile_id": "CBPR+", ...}, {"profile_id": "SEPA_Instant", ...}, ...]

    # Mock how a bank would answer an initiation. (fully local)
    pacs008 = '<Document><CdtTrfTxInf><Amt Ccy="EUR">10</Amt></CdtTrfTxInf></Document>'
    print(await call("simulate_bank_response",
                     {"inbound_payload": pacs008, "desired_behavior": "ACCP"}))
    # -> {"status": "ACCP", "generated_response_type": "pacs.002.001.10", ...}


asyncio.run(main())

Tools

All tools return JSON-serialisable data; on a domain, validation, or sub-server error they return an {"error": ...} payload rather than raising.