iso20022-bank-profile-mcp: The ISO 20022 Bank Clearing-Profile Server

iso20022-bank-profile-mcp: The ISO 20022 Bank Clearing-Profile Server

A fully local, closed-world Model Context Protocol server thatmanages, validates, and serves bank-specific ISO 20022 clearing profiles /rule packs — the market-practice rules that sit beyond structural XSDvalidation. It is a foundational member of theISO 20022 MCP Suite and a sibling ofiso20022-readiness-suite-mcp,whose readiness gateway can consume the profiles this server serves.

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-bank-profile-mcp turns those scheme rules intoversioned, agent-callable clearing profiles: list_profiles andget_profile serve them, lint_payload evaluates a payload against one,and validate_profile_definition vets a bank-supplied rule pack. v0.0.2,stdio by default (plus an optional OAuth 2.1 HTTP transport), 4 read-onlytools, premium rule-pack entitlement gating, Python 3.10+.

Contents

• Overview
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Tools
• HTTP transport & authentication
• How it fits the suite
• Open-core vs premium
• When not to use iso20022-bank-profile-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-bank-profile-mcp owns the market-practice profile layer of theISO 20022 MCP Suite: the scheme-specific and bank-specific rules a payment mustsatisfy to clear, which live above the XSD and vary by clearing system.

A clearing profile is pure data — a profile_id, its market_practice,the messages it supports, and a list of declarative custom_rules. The serverships open baseline profiles (Generic, CBPR+, SEPA_Instant, FedNow) andexposes four read-only tools to discover them, fetch them in full, lint apayload against one, and validate a candidate rule pack.

It is a fully local, closed-world server: no network surface, nosub-servers, no meta-client. Every tool computes from the bundled profile dataand returns typed, JSON-serialisable output; on any failure — a bad input, anunparseable payload, an unknown profile — it returns an {"error": ...}payload rather than raising into the client transport. XML payloads are parsedwith defusedxml only (no XXE / billion-laughs).

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

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["iso20022-bank-profile-mcp<br/>(clearing-profile server)"]
    B --> C["ProfileEngine<br/>(bundled JSON + register() seam)"]
    C --> D["Generic"]
    C --> E["CBPR+"]
    C --> F["SEPA_Instant"]
    C --> G["FedNow"]
    H["iso20022-readiness-suite-mcp<br/>(readiness gateway)"] -.consumes profiles.-> B

The ISO 20022 MCP Suite

iso20022-bank-profile-mcp is one of a set of coordinated, vendor-neutral MCPservers for the ISO 20022 migration. Dependency ranges are kept aligned acrossthe suite, so the servers co-install cleanly in a single Python environment.

Where the foundational servers each do one message job well and the readinessgateway composes them, this server owns the clearing profiles: it manages,validates, and serves the market-practice rule packs the rest of the suitelints against.

Install

iso20022-bank-profile-mcp runs on macOS, Linux, and Windows andrequires Python 3.10+ and pip. It pulls in the MCP SDK, pydantic,and defusedxml automatically — all published on PyPI.

python -m pip install iso20022-bank-profile-mcp

Or run it without installing, straight from PyPI, withuvx:

uvx iso20022-bank-profile-mcp

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U iso20022-bank-profile-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-bank-profile-mcp

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

{
  "mcpServers": {
    "iso20022-bank-profile": { "command": "iso20022-bank-profile-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;everything is local, so no other servers are needed:

import asyncio

from iso20022_bank_profile_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?
    print(await call("list_profiles", {}))
    # -> {"profile_id": "...", "market_practice": "...", "rule_count": ...}, ...

    # Lint a payload against a profile: a CBPR+ address missing its town.
    payload = "<Document><PstlAdr><Ctry>DE</Ctry></PstlAdr></Document>"
    print(await call("lint_payload",
                     {"payload_content": payload, "profile_id": "CBPR+"}))
    # -> {"profile_id": "CBPR+", "is_compliant": false,
    #     "findings": [{"code": "CBPR_MISSING_TOWN", "locator": "TwnNm", ...}]}


asyncio.run(main())

Tools

All tools return JSON-serialisable data; on a domain, validation, or valueerror they return an {"error": ...} payload rather than raising. Every toolis a pure, local, read-only, idempotent, closed-world lookup — no network, nosub-servers.

• list_profiles — List the available clearing profiles as lightweight summaries (profile_id, market_practice, tier, entitled, supported_messages, rule_count). Use it to discover the profile_id values the other tools accept and see which ones the current caller is entitled to.
• get_profile — Return one clearing profile in full, including its rule bodies. On a premium profile the caller must be entitled, otherwise it returns a BP_NOT_ENTITLED error (see Open-core vs premium).
• lint_payload — Evaluate a raw ISO 20022 payload against a clearing profile and return the findings (a compliant payload yields none). Like get_profile, a premium profile requires an entitlement or it returns BP_NOT_ENTITLED.
• validate_profile_definition — Validate a bank-supplied profile / rule-pack definition supplied as raw JSON, confirming its shape and that every rule uses a known assertion verb.

HTTP transport & authentication

stdio is the default and needs no authentication — one process per operator,launched by the client, no network surface. For shared, multi-tenantdeployments the server also speaks an optional streamable-HTTP transport:

iso20022-bank-profile-mcp --transport=http --bind=127.0.0.1:8080

--bind defaults to 127.0.0.1:8080 (loopback-only), so exposing the serverbeyond the host is an explicit opt-in (e.g. --bind=0.0.0.0:8080). The HTTPtransport refuses to start without authentication — it never serves anunauthenticated endpoint. Two auth modes apply, strongest first:

• OAuth 2.1 resource server (RFC 9728) — setISO20022_BANK_PROFILE_OAUTH_ISSUER andISO20022_BANK_PROFILE_OAUTH_AUDIENCE (both required), with optionalISO20022_BANK_PROFILE_OAUTH_JWKS_URL (defaults to<issuer>/.well-known/jwks.json) and ISO20022_BANK_PROFILE_OAUTH_SCOPES.Every request must carry Authorization: Bearer <jwt>; the token isvalidated against the JWKS and its iss / aud / exp / nbf / requiredscopes. Failures are rejected 401 / 403 with an RFC 9728WWW-Authenticate challenge, and protected-resource metadata is served at/.well-known/oauth-protected-resource. This server validates tokens fromyour existing authorization server (Okta, Auth0, Entra ID, …); running theauthorization server is out of scope.

  ISO20022_BANK_PROFILE_OAUTH_ISSUER=https://auth.example.com \
  ISO20022_BANK_PROFILE_OAUTH_AUDIENCE=https://mcp.example.com/mcp \
    iso20022-bank-profile-mcp --transport=http --bind=0.0.0.0:8080
  

• Static dev-mode token — set ISO20022_BANK_PROFILE_TOKEN to a sharedsecret; every request must then send Authorization: Bearer <secret>. Thisis a single shared secret with no expiry and no scopes — intended for localdevelopment, not production.

An optional X-MCP-Tenant request header is forwarded into the tool-visiblerequest context for multi-tenant scoping. Seedocs/transport.md for the full setup.

How it fits the suite

This server is the profile authority for the ISO 20022 MCP Suite. Thesibling iso20022-readiness-suite-mcpgateway scores and remediates payments against clearing profiles; thoseprofiles are exactly what this server manages, validates, and serves. Aligningon one profile source keeps the readiness gateway and any bank's own toolingevaluating a payment against the same market-practice rules.

The profile catalogue is extensible at the seam the whole suite shares. TheProfileEngine loads the open baseline from bundled JSON withProfileEngine.from_bundled(), and exposes ProfileEngine.register(profile)to add (or replace) a profile at runtime. A premium, bank-specific rulepack is the same shape as a bundled profile — a ClearingProfile with aprofile_id, a market_practice, its supported_messages, and a list ofcustom_rules — so a deployment that embeds this server can register itslicensed packs and serve them alongside the open baseline without changing thetool surface. See docs/profiles.md for the rulemini-language and the register() seam.

Open-core vs premium

The server is open core: the baseline scheme profiles and the profileengine are open source and always available. Higher-tier, institution-specificcapabilities are commercial add-ons that plug into the same profile-engine seam(the engine already exposes a register() hook for runtime-loaded rule packs).

Nothing in the open-source tier is time-limited or feature-gated.

How the entitlement gate works

Every clearing profile carries a tier: "open" (the baseline profiles —unrestricted and always accessible) or "premium" (a licensed rule pack). Abundled premium sample profile, ACME_Premium, ships so you can exercisethe gate. list_profiles reports each profile's tier and a per-callerentitled boolean; get_profile and lint_payload on a premium profilereturn a BP_NOT_ENTITLED error unless the caller is entitled.

Entitlement is granted by either of two independent sources (ORed):

• OAuth scope (HTTP transport) — a token bearing the profile:premiumscope is entitled to every premium profile; a token bearingprofile:<profile_id> is entitled to just that one.
• Environment allowlist (stdio / dev) — ISO20022_BANK_PROFILE_ENTITLEMENTSlists the premium profile_id values (comma- or space-separated) theoperator is licensed for; * grants all of them.

# stdio: license the ACME_Premium sample pack for this process
ISO20022_BANK_PROFILE_ENTITLEMENTS=ACME_Premium iso20022-bank-profile-mcp

The gate ships in this release; the premium rule packs themselves (andstateful version history / audit logs) remain a paid, out-of-tree concern.See docs/profiles.md for the full entitlement model.

When not to use iso20022-bank-profile-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 need structural XSD validation or message generation. Those live inthe foundational suite servers (iso20022-mcp, camt053-mcp,pain001-mcp). This server evaluates market-practice rules above the XSD;it does not parse, generate, or structurally validate messages.
• You want an end-to-end readiness score and remediation. That is the jobof iso20022-readiness-suite-mcp, which consumes these profiles. Use it ifyou want scoring, remediation, and bank-response simulation composedtogether.
• You need a long-lived network service without auth. stdio is the default(one process per operator, no network surface); the optionalHTTP transport exists for shared,multi-tenant deployments but always requires authentication (OAuth 2.1 or astatic dev-mode token) — it will not serve an unauthenticated endpoint.
• You need streaming responses. Tool calls return whole values, notstreams.

Development

iso20022-bank-profile-mcp uses Poetry andmise.

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

Note: the server is fully local and closed-world, so the test suite runswith nothing else installed. 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-bank-profile-mcp returns errors as data — every tool catches thedocumented domain, validation, and value errors and returns an{"error": ...} envelope; it never propagates raw exceptions to the MCPclient. Payloads reached through the clearing-profile engine are parsed withdefusedxml only (no XXE / billion-laughs), and the server opens no networksockets. Reporting practice, supported versions, the attack surface, and thefull supply-chain posture (SLSA L3 provenance, PEP 740 attestations, SBOMs, andthe NIST 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 shipped (HTTP transport, premium entitlement gating) and what's next (richer bank rule packs)
• MAINTAINERS.md — who can merge
• docs/quickstart.md — 10-minute install → first conversation
• docs/profiles.md — the clearing profiles, the rule mini-language, premium rule packs, and the entitlement gate
• docs/transport.md — the optional HTTP transport and OAuth 2.1 setup
• glama.json — Glama directory manifest

MCP Registry

mcp-name: io.github.sebastienrousseau/iso20022-bank-profile-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 alongside the foundational servers of the ISO 20022 MCP Suite and theModel Context Protocol Python SDK.