Skip to main content
Glama
camt-exceptions

camt-exceptions

camt-exceptions: ISO 20022 Exceptions & Investigations, generated + XSD-valid

Build Status PyPI version Glama MCP server score OpenSSF Scorecard License Python Version

Generate and validate ISO 20022 Exceptions & Investigations (E&I) camt messages — with an MCP server. Starts with camt.056 (FI-to-FI Payment Cancellation Request): the message a bank sends to recall or cancel a payment it already dispatched — a duplicate, an erroneous amount, a fraud recall. Output is validated against the official bundled XSD before it's returned.

Latest release: v0.0.20: camt.056 + camt.029 generation + validation, 4 MCP tools over stdio, streamable HTTP or SSE, 100% branch coverage, for Python 3.10+. Part of the ISO 20022 MCP suite. Additional E&I messages (camt.029, camt.026, camt.027, camt.087) plug into the same engine.

Why E&I

When a payment goes wrong, the fix is an Exceptions & Investigations message — and these are the least tooled corner of ISO 20022. camt.056 alone covers the single most common need: "I need to cancel/recall that payment." This library makes it a one-call, schema-valid operation for an agent, with the same depth as the credit-transfer generators elsewhere in the suite.

Related MCP server: acmt001-mcp

Install

pip install camt-exceptions
# or run the MCP server without installing:
uvx camt-exceptions

MCP client config (e.g. Claude Desktop):

{
  "mcpServers": {
    "camt-exceptions": {
      "command": "camt-exceptions-mcp"
    }
  }
}

Quick start — cancel a payment

from camt_exceptions import generator as g

xml = g.generate_message("camt.056.001.12", {
    "assignment_id": "CXL-001",
    "assigner_agent_bic": "DEUTDEFF",
    "assignee_agent_bic": "COBADEFF",
    "creation_date_time": "2026-03-02T10:00:00",
    "original_msg_id": "MSG-ORIG-001",
    "original_msg_nm_id": "pacs.008.001.08",
    "transactions": [{
        "original_end_to_end_id": "E2E-001",
        "original_interbank_settlement_amount": "1000.00",
        "original_interbank_settlement_currency": "EUR",
        "cancellation_reason_cd": "DUPL",       # duplicate payment
    }],
})
assert g.validate_xml("camt.056.001.12", xml)["is_valid"]   # True

Transports

One command line, three transports:

Command

Transport

Endpoint

Protocol revisions

camt-exceptions-mcp

stdio

the client spawns the process

2026-07-28, 2025-11-25

camt-exceptions-mcp --transport streamable-http

Streamable HTTP

http://127.0.0.1:8000/mcp

2026-07-28 (stateless, server/discover) and 2025-11-25 (initialize, Mcp-Session-Id) on the same endpoint; responses stream as server-sent events, GET opens the server-to-client stream

camt-exceptions-mcp --transport sse

HTTP+SSE (2024-11-05)

http://127.0.0.1:8000/sse and /messages/

for clients that still expect the older transport

--host and --port change the bind address (defaults 127.0.0.1 and 8000). The HTTP transports carry no authentication of their own: bind loopback, or put the server behind a gateway you trust before binding a routable address. Every release is verified over streamable HTTP with scout in both protocol eras and over SSE with the MCP SDK client; see ADR 0001.

{
  "mcpServers": {
    "camt-exceptions": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

Tools

  • list_message_types — List supported E&I message types and names.

  • get_required_fields — Required top-level fields for a message type.

  • generate_message — Generate a validated E&I XML message from a record (validated against the bundled XSD before return).

  • validate_xml — Validate raw XML against a message type's bundled XSD.

Supported messages

Message

Name

Status

camt.056.001.12

FI to FI Payment Cancellation Request

✅

camt.029.001.14

Resolution of Investigation

✅

camt.026

Unable to Apply

planned

camt.027

Claim Non-Receipt

planned

camt.087

Request to Modify Payment

planned

Each new message plugs into the same engine: bundle its official XSD + template.xml and register it in MESSAGE_TYPES. Generated output is always XSD-validated before return, so correctness is machine-checked, not asserted.

Note: the payment-status and return messages of the E&I family — pacs.002 (Payment Status Report) and pacs.004 (Payment Return) — are already generated, XSD-valid, by pacs008-mcp.

The suite

Part of a family of vendor-neutral, Python-native ISO 20022 MCP servers:

Documentation

Development

git clone https://github.com/sebastienrousseau/camt-exceptions
cd camt-exceptions
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov hypothesis ruff black mypy interrogate "mutmut>=3.7,<4"
pytest                      # 100% branch coverage gate; output is XSD-validated
ruff check camt_exceptions tests && black --check camt_exceptions tests && mypy camt_exceptions
interrogate -c pyproject.toml camt_exceptions   # 100% docstring gate
mutmut run && mutmut export-cicd-stats && python scripts/mutation_gate.py --floor 90

License

Licensed under the Apache License, Version 2.0 or the MIT License, at your option. Bundled ISO 20022 message schemas (*.xsd) are © ISO 20022 and redistributed under the ISO 20022 terms; they are the same schemas published at iso20022.org.


mcp-name: io.github.sebastienrousseau/camt-exceptions

Available Tools

4 tools
generate_messageA
Read-onlyIdempotent

Generate a schema-validated ISO 20022 E&I XML message from a record.

Purpose: Renders a complete, XSD-compliant ISO 20022 XML document (e.g. camt.056 payment cancellation or camt.029 investigation resolution) from structured field dictionaries, validating the result against the bundled official schema before returning.

When to use:

  • When raising payment cancellation, recall, or investigation response messages for interbank transmission.

  • When requiring guaranteed XSD-valid XML output for downstream payment processing.

When NOT to use:

  • Do NOT use to validate pre-existing XML files without generating; use validate_xml instead.

  • Do NOT pass incomplete records; check get_required_fields first.

Behavioral transparency: Pure template rendering and in-memory schema validation; side-effect-free and idempotent.

Inputs: record (required), message_type (required). Returns: object

get_required_fieldsA
Read-onlyIdempotent

Get required schema fields for an ISO 20022 E&I message type.

Purpose: Returns the list of mandatory top-level data fields required to construct a valid message record (e.g. assignment identification, instruct team agent, and transaction arrays).

When to use:

  • When preparing input payloads before calling generate_message.

  • When validating payload completeness prior to XML serialization.

When NOT to use:

  • Do NOT use with unsupported message types; discover supported types via list_message_types.

Behavioral transparency: Deterministic field dictionary lookup; pure, read-only, and idempotent.

Inputs: message_type (required). Returns: object

list_message_typesA
Read-onlyIdempotent

List supported ISO 20022 Exceptions & Investigations message types.

Purpose: Returns the catalog of supported E&I message identifiers (e.g. camt.056.001.12 Payment Cancellation Request, camt.029.001.14 Resolution of Investigation) and their human-readable definitions.

When to use:

  • When discovering valid message_type parameters before generating or validating messages.

  • When verifying schema version support for payment recall or resolution workflows.

When NOT to use:

  • Do NOT use for payment initiation (pain) or statement (camt.053) messages.

Behavioral transparency: Static catalogue retrieval; pure, deterministic, and side-effect-free.

Inputs: no named parameters. Returns: object

validate_xmlA
Read-onlyIdempotent

Validate raw ISO 20022 E&I XML against bundled XSD schemas.

Purpose: Validates an XML string against the official bundled XSD schema for the specified E&I message type, returning validation status and detailed schema violation diagnostics.

When to use:

  • When inspecting received or pre-generated ISO 20022 E&I XML before ingesting or routing.

  • When diagnosing schema structural, datatype, or constraint errors in message payloads.

When NOT to use:

  • Do NOT use for payment initiation (pain) or statement (camt.053) documents.

  • Do NOT pass unparseable binary content; requires valid XML text.

Behavioral transparency: Pure, in-memory schema validation using local bundled XSDs; zero network access or side effects.

Inputs: xml (required), message_type (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct stage of the E&I message workflow: catalogue discovery (list_message_types), schema field lookup (get_required_fields), XML rendering (generate_message), and XML validation (validate_xml). Descriptions explicitly cross-reference alternatives (e.g. 'use validate_xml instead'), leaving no ambiguity.

    Naming Consistency5/5

    All four names follow a consistent snake_case verb_noun pattern: list_message_types, get_required_fields, generate_message, validate_xml. Verb-first, predictable, and readable throughout.

    Tool Count4/5

    Four tools form a tight, well-scoped workflow for a focused domain (ISO 20022 E&I message generation and validation). Slightly lean, but each tool clearly earns its place with no redundancy.

    Completeness4/5

    The surface covers the full lifecycle: discover valid message types, learn required fields, generate XSD-valid XML, and validate existing XML. Minor gaps exist (e.g. no batch validation or per-type example payloads), but core workflows are fully supported.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
      2
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for ISO 20022 acmt.001 Account Opening (and companion acmt.* messages): message-type discovery, required-field lookup, JSON Schema introspection, IBAN/BIC/LEI validation, flat-record validation, and validated acmt XML generation.
      7
      163 PyPI
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Matches expected payments (pain.001) against observed booked entries (camt.053) for ISO 20022 cash reconciliation, providing explainable match results with scoring and classification.
      10
      1
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Unified gateway for ISO 20022 message families, providing meta-tools to search, describe, validate, generate, and parse financial messages.
      7
      89 PyPI
      1
      Apache 2.0