ISO 20022 Payment Evidence & Investigation MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ISO 20022 Payment Evidence & Investigation MCP Validate this pacs.008 message and map any issues to likely reject codes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ISO 20022 Payment Evidence & Investigation MCP
Python MCP server for read-only ISO 20022 payment validation and evidence-backed rejection investigation. Correlates pacs.008 and pacs.002 messages using exact identifiers, provides traceable bank-reported status/rejection reasons, and supplies deterministic tools for safe AI-assisted payment analysis.
GitHub repository: iso20022-payment-evidence-investigation-mcp · Python package / CLI: iso20022-mcp · Glama listing: maintainer instructions and listing copy · Deployment: local stdio server; no live bank integration or remote hosting.
Agents handling payments fail in predictable ways: they invent reject codes, miss IBAN checksum errors, and follow instructions hidden in free-text fields like remittance information. This server gives them deterministic tools for the parts that must be exact, and treats message free text as untrusted data.
FinServ Evidence Intelligence (FEI) — product direction
The repository also contains a proposed FinServ Evidence Intelligence (FEI) solution blueprint. Its first product is an evidence-backed, read-only payment exception investigation copilot, reusing the deterministic ISO 20022 MCP tools. This is an evolution of the existing project, not a live banking product or an AI payment executor.
Gamma AI creates executive presentations; Glama is a separate MCP discovery and hosting provider. Neither is part of the bank's payment execution path.
Related MCP server: camt053-mcp
Tools
Tool | What it does |
| pacs.008 / pacs.002 XML → structured results (version-aware, bounded, XXE-safe) |
| IBAN mod-97, BIC format, amounts and currency decimals, required parties, counts, free-text limits, prompt-injection patterns — each issue mapped to its likely reject code |
| Deterministic plain-language summary: who pays whom, how much, status and reasons |
| Status reason / transaction status / charge bearer codes — returns |
| Synthetic valid and defective messages for testing (no real customer data) |
| Exactly correlate a supplied pacs.008 and pacs.002; return bank-reported rejection evidence, limits and human-reviewed next steps |
Glama source discovery and reproducibility
The current server exposes six MCP tools, including investigate_payment. The integration test checks a real stdio initialize, asserts exactly six results from tools/list, and calls the investigation tool with synthetic messages.
pip install -e ".[dev]"
pytest -q tests/test_mcp_integration.py
docker build -t iso20022-evidence-mcp .The Dockerfile supports reproducible, least-privilege source introspection (including Glama's sandbox builds). It has no network listener or banking credentials. If the Glama listing still displays the previous repository name or five tools, follow the Glama rescan and ownership guidance.
Architecture and complete happy-path walkthrough
The Word/PPTX and rendered diagrams are generated reproducibly with
python docs/build_documents.py. The GitHub documentation workflow publishes
them to the feature branch. Production bank connections and a remote authenticated
MCP gateway are not implemented.
Quick start
pip install -e ".[dev]"
pytest -q
iso20022-mcp # runs the server over stdioClaude Desktop / any MCP client config:
{ "mcpServers": { "iso20022": { "command": "iso20022-mcp" } } }Security design
Free-text fields are returned with an
_UNTRUSTEDsuffix and the server instructions tell agents to treat them as data.validate_messageflags instruction-like content in free text (severitysecurity).XML parsing disables entity resolution and network access.
Only synthetic data and public example IBANs/BICs are used anywhere in this repo.
Benchmark
evals/ contains a generator for a banking-agent task set (python evals/make_tasks.py) covering validation, rejection investigation and prompt injection, plus a
deterministic scorer. Results across model families: coming soon.
Hardened validation and enterprise integration (experimental)
The server remains a local stdio MCP process. Its ISO 20022 business tools do not execute, modify or transmit payments.
Supported XML versions and safety limits
pacs.008.001.08andpacs.002.001.10are explicitly supported. A mismatched message root or unrecognized namespace/version is rejected.XML input is limited to 1,000,000 UTF-8 bytes and 10,000 elements. DTDs are rejected; external entities and XML network access are disabled.
IBAN mod-97 and maintained country lengths, supported currency codes/minor units, UETR, BIC and transaction counts are checked.
Currency codes and status reason tables are curated subsets. Maintain them from authoritative sources before accepting production traffic.
Optional offline XSD validation
Official ISO 20022 XSDs are not bundled. Obtain the corresponding authoritative schemas and review them through your bank's change-control process. Install version-named local files into a trusted directory:
export ISO20022_XSD_DIR=/path/to/approved/iso20022/xsd
# Expected filenames include:
# pacs.008.001.08.xsd
# pacs.002.001.10.xsd
iso20022-mcpThe XSD validator reads only locally configured schema files and does not
download schemas. Imported/included files should be reviewed and kept within
the trusted schema bundle. A missing file is reported as unavailable, not
as a successful validation.
validate_message includes independent outcomes:
Field | Meaning |
| Business checks produced no |
| Backwards-compatible alias for |
|
|
|
|
| XSD diagnostic messages, separate from business-rule findings |
|
|
|
|
A conformant result is not an authorization to settle or release a
payment; scheme rules and payment-hub controls are still required.
Typed MCP responses
parse_message, validate_message, and lookup_code now return
Python dictionaries, allowing MCP SDKs to expose structured responses.
Previously these functions returned JSON-serialized strings. Clients that
assume a text-only response should be adapted to accept structured content.
explain_message and generate_test_message remain text tools.
Governed read-only integration boundary
iso20022_mcp.adapters.PaymentInspectionService is a framework-neutral,
read-only integration contract. A bank must supply both:
PaymentMessageSource.read_xml(reference), backed by an approved payment hub or message archive.PaymentReadAuthorizer.may_read(principal, reference), backed by authenticated identity and bank policy.
An unauthorized request is rejected before the payment-hub adapter reads any message. This service is not automatically exposed as an MCP tool, and there are no default credentials, unauthenticated endpoints, payment execution methods or live bank connections.
For centralized deployment, put a separately reviewed MCP HTTP gateway in front of the service with OAuth/OIDC, tool scopes, transport security, rate limits, PII masking, durable audit trails and observability. A fully secured remote gateway and concrete payment-hub adapters are not implemented.
Test
pip install -e ".[dev]"
pytest -qThe suite includes actual stdio MCP initialization/tool-discovery checks, validation security regression tests, and authorization tests for the read-only adapter interface.
Evidence-backed payment investigations (experimental)
The investigate_payment(pacs008_xml, pacs002_xml) MCP tool
correlates supplied pacs.008 and pacs.002 messages by original message ID
and exact transaction identifiers. It returns a read-only evidence ledger,
reported status codes, interpretation limits, and safe human-reviewed
recommendations. It refuses to attribute unrelated statuses to a payment.
Example (Python API, synthetic messages):
from iso20022_mcp import generate, parser
from iso20022_mcp.investigate import investigate_payment
original = generate.generate_pacs008()
p = parser.parse_message(original)
status = generate.generate_pacs002(
"AC04", p["msg_id"], p["transactions"][0]["end_to_end_id"]
)
report = investigate_payment(original, status)
assert report["cases"][0]["correlation"] == "matched"
assert report["cases"][0]["reported_reasons"][0]["code"] == "AC04"The engine does not query live banking systems, verify real account status, apply CBPR+/SEPA business rules or initiate any repair. A reason reported in pacs.002 remains a bank-reported reason, not an independently verified cause.
Synthetic, transparent capability comparison:
python evals/compare_investigation.pyThis comparison demonstrates exact correlation, unknown-code safety, and provenance in fixture cases; it is not a real-world accuracy study.
Roadmap
Official XSD validation · pain.001 and camt.053 · MT103 → pacs.008 (subset) · remote HTTP deployment with auth and OpenTelemetry
Disclaimer
Not affiliated with ISO, SWIFT or any bank. Code sets here are a curated subset; consult the official ISO 20022 external code sets for production use.
Available Tools
6 toolsexplain_messageC
Plain-language summary of who pays whom, how much, and status/reasons. Deterministic, no guessing.
Inputs: xml (required). Returns: result
generate_test_messageA
Generate a synthetic test message. kind: 'pacs.008' or 'pacs.002'. defect (pacs.008): none, bad_iban, bad_bic, missing_creditor_name, bad_decimals, count_mismatch, injection_in_remittance, missing_creditor_address. reason_code is used for pacs.002.
Inputs: kind, defect, reason_code. Returns: result
investigate_paymentA
Correlate pacs.008 with pacs.002 and report bank-reported reasons with exact provenance, uncertainty, and human-approved next steps. Read-only. Requires two supplied XML messages; no external banking connectivity.
Inputs: pacs002_xml (required), pacs008_xml (required).
lookup_codeB
Look up an ISO 20022 status reason, transaction status or charge bearer code. Use this instead of guessing.
Inputs: code (required).
parse_messageA
Parse an ISO 20022 pacs.008 (credit transfer) or pacs.002 (status report) XML message into structured JSON.
Inputs: xml (required).
validate_messageA
Validate a pacs.008/pacs.002 message against business rules (IBAN checksum, BIC format, amounts, required parties, counts, free-text limits, prompt-injection patterns). Returns issues with likely reject codes.
Inputs: xml (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct role: parse converts XML to JSON, validate applies business rules, explain produces a plain-language summary, and investigate correlates two messages. The only mild overlap is between explain_message and investigate_payment, both of which surface status/reasons, but the descriptions make the boundary (single message vs. correlation of two) reasonably clear.
All six tools follow a consistent snake_case verb_noun pattern: explain_message, generate_test_message, lookup_code, investigate_payment, parse_message, validate_message. No mixed conventions or vague standalone verbs.
Six tools is well-scoped for an ISO 20022 payment investigation server, with each tool covering a distinct stage of the parse-validate-explain-investigate workflow. Nothing feels redundant or missing at the count level.
The surface covers the core lifecycle for pacs.008/pacs.002: parse, validate, explain, generate test data, look up codes, and investigate. Minor gaps exist—no support for related message types like pacs.004 returns or camt.056 recalls, and no batch/report export—but the stated scope is well covered.
Maintenance
Related MCP Connectors
Generate and validate SEPA ISO 20022 XML (pain.001, pain.008) and SWIFT MT103 payment messages.
Check ISO 20022 messages (pacs.008, pain.001, camt.053, seev.031) against schema and rules.
Decode ISO 20022 pain.002 bank status reports & AC04/AM04/BE04/MD01/RC01 errors into plain English
Cross-border payment & banking intelligence for AI agents: SWIFT/BIC, IBAN, sanctions, FX, tracking.
Related MCP Servers
- AlicenseAqualityDmaintenancePactus is an MCP server for parsing and validating ISO 20022 payment messages directly from chat. It exposes nine tools that let AI assistants inspect or validate pacs.008, pacs.002, pain.001, and camt.053 messages — the message types at the centre of the CBPR+ migration — without leaving the conversation.917 PyPI2MIT
- AlicenseAqualityBmaintenanceMCP server that enables AI agents to parse, validate, and reverse ISO 20022 bank statements, with tools for discovering message types and return reasons.24190 PyPI2Apache 2.0
- AlicenseAqualityBmaintenanceA Model Context Protocol server that exposes the pain001 ISO 20022 Customer Credit Transfer Initiation library as agent tools, enabling AI assistants to generate and validate standardized payment XML messages.301,471 PyPI1Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server that exposes the pacs008 ISO 20022 FI-to-FI Customer Credit Transfer library as tools for AI agents and assistants, enabling generation, validation, and parsing of pacs.008 credit transfer XML messages.1684 PyPI1Apache 2.0