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

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

A high-level orchestration Model Context Protocol server — theWhite-Label ISO 20022 Readiness & Testing Gateway. It is an MCP server toyour agent and an MCP client to the foundational servers of theISO 20022 MCP Suite. It composes them intoreadiness scoring, automated remediation, clearing-profile linting (CBPR+,SEPA_Instant, FedNow, Generic), and bank-response simulation — one gateway anagent 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 addresseschief among them — a payment that was fine yesterday can be rejectedtomorrow. iso20022-readiness-suite-mcp puts a single readiness gateway infront of your agent: run_readiness_check scores a payload against aclearing profile, remediate_payload proposes the compliant form, andsimulate_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) is an open standard that lets AI agentsand assistants discover and call external tools in a uniform way.iso20022-readiness-suite-mcp is the orchestration front door of the ISO20022 MCP Suite: it presents four high-level tools to the outer agent, andunderneath it acts as an MCP client that spawns the foundational suiteservers over stdio and composes their results — the meta-client pattern.

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

Every tool returns typed, JSON-serialisable data; on any failure — a badinput, an unparseable payload, a missing or erroring sub-server — it returnsan {"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 sixfoundational servers below it. list_profiles and simulate_bank_responseare fully local and need none of them; run_readiness_check andremediate_payload reach the sub-servers and therefore require them to beinstalled and resolvable (seeOrchestration & the meta-client pattern).

The ISO 20022 MCP Suite

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

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

Install

iso20022-readiness-suite-mcp runs on macOS, Linux, and Windows andrequires 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, alsomake the foundational servers resolvable — the gateway launches them withuvx, so installing uv is enough for azero-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 theclient'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 MCPclient, not used interactively. The agent can then call the tools below.

You can also invoke the tools in-process — without a transport — straightthrough the FastMCP instance. This mirrors what an agent receives over stdio.The two local tools (list_profiles, simulate_bank_response) need nosub-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)
        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, orsub-server error they return an {"error": ...} payload rather than raising.

• list_profiles — List the available clearing profiles (CBPR+, SEPA_Instant, FedNow, Generic) with their market practice and rules. Fully local; no sub-servers needed.
• run_readiness_check — Detect, structurally validate, profile-lint, and score an ISO 20022 payload's readiness against a target clearing profile. Reaches the foundational sub-servers.
• remediate_payload — Apply automated remediation (e.g. the Nov 2026 structured-address fixes) driven by a clearing profile, delegating to structured-address-fix-mcp. Reaches the foundational sub-servers.
• simulate_bank_response — Emit a pacs.002 status report mocking a bank's ACCP / RJCT / PDNG response to an inbound initiation (a reason code is required for RJCT). Fully local; no sub-servers needed.

Reachability. run_readiness_check and remediate_payload spawn theunderlying servers over stdio via uvx, so those servers must beinstalled / resolvable for the two tools to succeed. list_profiles andsimulate_bank_response compute purely locally and always work standalone.

HTTP transport & authentication

By default the gateway speaks stdio — launched by a local MCP client, oneprocess per operator, with no network surface and no authentication needed:

iso20022-readiness-suite-mcp                 # stdio (default)

For shared, multi-tenant deployments it also offers an optionalstreamable-HTTP transport. The default --bind is loopback-only(127.0.0.1:8080); expose it explicitly with --bind=0.0.0.0:8080:

iso20022-readiness-suite-mcp --transport=http --bind=0.0.0.0:8080

The HTTP transport requires authentication — starting it with noneconfigured is refused. Two modes apply, strongest first.

OAuth 2.1 resource server (RFC 9728) — production. Set theISO20022_READINESS_OAUTH_* environment variables and the server validatesAuthorization: Bearer <jwt> against your authorization server's JWKS:

JWTs are checked for signature (JWKS, with key rotation on an unknown kid),iss / aud / exp / nbf, and the required scopes. The RFC 9728protected-resource metadata is served unauthenticated at/.well-known/oauth-protected-resource. Rejections return 401 (403 forinsufficient_scope) with a WWW-Authenticate challenge pointing at thatmetadata.

Static bearer token — dev mode only. When no OAuth variables are set, asingle shared secret in ISO20022_READINESS_TOKEN is accepted instead(compared with hmac.compare_digest). This is explicitly dev-mode — one sharedsecret, no expiry, no scopes — and is ignored when OAuth is also configured:

ISO20022_READINESS_TOKEN=s3cret \
  iso20022-readiness-suite-mcp --transport=http --bind=127.0.0.1:8080

HTTP callers may send an optional X-MCP-Tenant header, forwarded into aper-request tenant context; the authenticated token's scopes are exposed totools too, so tool code can scope behaviour without branching on the transport.See docs/transport.md for the full setup.

Orchestration & the meta-client pattern

The gateway implements the "server that is also a client" half of theorchestration: an orchestrator depends only on a SubServerInvoker protocol,and the production StdioSubServerInvoker spins up an underlying server overstdio, calls one tool, and tears the session down. Every failure — a missingserver, a spawn error, a tool error — is returned as data (a typedToolOutcome), never raised across the caller boundary.

By default each foundational server is launched with a zero-install uvxcommand:

The command map is overridable per deployment, so you can point the gateway atlocally installed console scripts, a pinned virtualenv, or a remote-launchedprocess instead of uvx. See docs/orchestration.mdfor the full pattern and how to point it at local or remote sub-servers.

Open-core vs premium

The gateway is open core: the baseline validation workflows and thegeneric scheme profiles are open source and always available. Higher-tier,institution-specific capabilities are commercial add-ons that plug into thesame profile-engine and orchestration seams (the profile engine alreadyexposes a register() hook for runtime-loaded rule packs).

The paid tiers are on the roadmap (premium rule-pack entitlementgating, plus the sister iso20022-bank-profile-mcp andiso20022-evidence-pack-mcp servers), not in this release. Nothing in theopen-source tier is time-limited or feature-gated.

When not to use iso20022-readiness-suite-mcp

• You have no MCP client. This server only makes sense paired with anMCP-aware host (Claude Desktop, the IDE plugins, an agent framework).
• You only need one message operation. If you just want to validate apain.001 or parse a camt.053, call the relevant foundational serverdirectly — the gateway's value is composing them.
• You need run_readiness_check / remediate_payload without thesub-servers. Those two tools require the foundational servers to beresolvable (via uvx or an overridden command map). If you cannot installthem, you are limited to list_profiles and simulate_bank_response.
• You need a long-lived network service. stdio (the default) is oneprocess per operator, launched by the client, with no network surface. Forshared, multi-tenant deployments use the optional streamable-HTTP transport(--transport=http, with OAuth 2.1 or a dev-mode token) — seeHTTP transport & authentication.
• You need streaming responses. Tool calls return whole values, notstreams.

Development

iso20022-readiness-suite-mcp uses Poetry andmise.

git clone https://github.com/sebastienrousseau/iso20022-readiness-suite-mcp.git && cd iso20022-readiness-suite-mcp
mise install
poetry install
poetry shell

Note: the test suite injects a fake sub-server invoker, so you do notneed the foundational servers installed to run the tests — only to exerciserun_readiness_check / remediate_payload against real servers. SeeCONTRIBUTING.md.

A Makefile orchestrates the quality gates (kept in lockstep with CI):

make check        # all gates (REQUIRED before commit): lint + type-check + test
make test         # pytest (100% line + branch coverage)
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

Security

iso20022-readiness-suite-mcp returns errors as data — every tool catches thedocumented domain, validation, and value errors (and every sub-server failure)and returns an {"error": ...} envelope; it never propagates raw exceptionsto the MCP client. XML payloads reached through the clearing-profile engineare parsed with defusedxml only (no XXE / billion-laughs). Reportingpractice, supported versions, the meta-client attack surface, and the fullsupply-chain posture (SLSA L3 provenance, PEP 740 attestations, SBOMs, and theNIST SP 800-218 SSDF practice mapping) are documented inSECURITY.md. Vulnerabilities go via GitHub PrivateVulnerability Reporting, not public issues.

Documentation

• README.md — this file
• CHANGELOG.md — release notes
• SECURITY.md — disclosure + supported versions
• SUPPORT.md — how to get help
• ROADMAP.md — what's next (sister servers, premium rule-pack entitlement)
• MAINTAINERS.md — who can merge
• docs/quickstart.md — 10-minute install → first conversation
• docs/transport.md — the HTTP transport and OAuth 2.1 (RFC 9728) auth setup
• docs/orchestration.md — the meta-client pattern and pointing the gateway at local/remote sub-servers
• docs/profiles.md — the clearing profiles and how premium rule packs plug in
• glama.json — Glama directory manifest

MCP Registry

mcp-name: io.github.sebastienrousseau/iso20022-readiness-suite-mcp

License

Licensed under the Apache License, Version 2.0. Any contribution submittedfor inclusion shall be licensed as above, without additional terms.

Contributing

Contributions are welcome — see the contributing instructions. Thanks toall contributors.

Acknowledgements

Built on the foundational servers of the ISO 20022 MCP Suite and theModel Context Protocol Python SDK.