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

A high-level orchestration Model Context Protocol 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) 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.

• 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 the underlying servers over stdio via uvx, so those servers must be installed / resolvable for the two tools to succeed. list_profiles and simulate_bank_response compute purely locally and always work standalone.

HTTP transport & authentication

By default the gateway speaks stdio — launched by a local MCP client, one process 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 optional streamable-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 none configured is refused. Two modes apply, strongest first.

OAuth 2.1 resource server (RFC 9728) — production. Set the ISO20022_READINESS_OAUTH_* environment variables and the server validates Authorization: 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 9728 protected-resource metadata is served unauthenticated at /.well-known/oauth-protected-resource. Rejections return 401 (403 for insufficient_scope) with a WWW-Authenticate challenge pointing at that metadata.

Static bearer token — dev mode only. When no OAuth variables are set, a single shared secret in ISO20022_READINESS_TOKEN is accepted instead (compared with hmac.compare_digest). This is explicitly dev-mode — one shared secret, 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 a per-request tenant context; the authenticated token's scopes are exposed to tools 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 the orchestration: an orchestrator depends only on a SubServerInvoker protocol, and the production StdioSubServerInvoker spins up an underlying server over stdio, calls one tool, and tears the session down. Every failure — a missing server, a spawn error, a tool error — is returned as data (a typed ToolOutcome), never raised across the caller boundary.

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

The command map is overridable per deployment, so you can point the gateway at locally installed console scripts, a pinned virtualenv, or a remote-launched process instead of uvx. See docs/orchestration.md for 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 the generic scheme profiles are open source and always available. Higher-tier, institution-specific capabilities are commercial add-ons that plug into the same profile-engine and orchestration seams (the profile engine already exposes a register() hook for runtime-loaded rule packs).

The paid tiers are on the roadmap (premium rule-pack entitlement gating, plus the sister iso20022-bank-profile-mcp and iso20022-evidence-pack-mcp servers), not in this release. Nothing in the open-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 an MCP-aware host (Claude Desktop, the IDE plugins, an agent framework).
• You only need one message operation. If you just want to validate a pain.001 or parse a camt.053, call the relevant foundational server directly — the gateway's value is composing them.
• You need run_readiness_check / remediate_payload without the sub-servers. Those two tools require the foundational servers to be resolvable (via uvx or an overridden command map). If you cannot install them, you are limited to list_profiles and simulate_bank_response.
• You need a long-lived network service. stdio (the default) is one process per operator, launched by the client, with no network surface. For shared, multi-tenant deployments use the optional streamable-HTTP transport (--transport=http, with OAuth 2.1 or a dev-mode token) — see HTTP transport & authentication.
• You need streaming responses. Tool calls return whole values, not streams.

Development

iso20022-readiness-suite-mcp uses Poetry and mise.

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 not need the foundational servers installed to run the tests — only to exercise run_readiness_check / remediate_payload against real servers. See CONTRIBUTING.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 the documented domain, validation, and value errors (and every sub-server failure) and returns an {"error": ...} envelope; it never propagates raw exceptions to the MCP client. XML payloads reached through the clearing-profile engine are parsed with defusedxml only (no XXE / billion-laughs). Reporting practice, supported versions, the meta-client attack surface, and the full supply-chain posture (SLSA L3 provenance, PEP 740 attestations, SBOMs, and the NIST SP 800-218 SSDF practice mapping) are documented in SECURITY.md. Vulnerabilities go via GitHub Private Vulnerability 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 submitted for inclusion shall be licensed as above, without additional terms.

Contributing

Contributions are welcome — see the contributing instructions. Thanks to all contributors.

Acknowledgements

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