Skip to main content
Glama
ISO 20022 Payment Evidence & Investigation MCP

ISO 20022 Payment Evidence & Investigation MCP

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

parse_message

pacs.008 / pacs.002 XML → structured results (version-aware, bounded, XXE-safe)

validate_message

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

explain_message

Deterministic plain-language summary: who pays whom, how much, status and reasons

lookup_code

Status reason / transaction status / charge bearer codes — returns found: false instead of guessing

generate_test_message

Synthetic valid and defective messages for testing (no real customer data)

investigate_payment

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 stdio

Claude Desktop / any MCP client config:

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

Security design

  • Free-text fields are returned with an _UNTRUSTED suffix and the server instructions tell agents to treat them as data.

  • validate_message flags instruction-like content in free text (severity security).

  • 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.08 and pacs.002.001.10 are 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-mcp

The 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_valid

Business checks produced no error findings

valid

Backwards-compatible alias for business_valid, not XSD conformance

schema_status

valid, invalid, not_configured, unavailable, error, or not_evaluated

schema_valid

true, false, or null if schemas are not configured

schema_issues

XSD diagnostic messages, separate from business-rule findings

security_status

clear, review_required, or not_evaluated

conformant

true only if business rules pass, a configured XSD passes and no security finding exists

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:

  1. PaymentMessageSource.read_xml(reference), backed by an approved payment hub or message archive.

  2. 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 -q

The 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.py

This 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 tools
explain_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

    A3.6/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Pactus 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.
      9
      17 PyPI
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that enables AI agents to parse, validate, and reverse ISO 20022 bank statements, with tools for discovering message types and return reasons.
      24
      190 PyPI
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      30
      1,471 PyPI
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      16
      84 PyPI
      1
      Apache 2.0