Pain001

AI agents

pain001-mcp: The MCP Server for ISO 20022 Payments

Seventeen read-only tools that let AI agents validate, migrate, convert, and generate ISO 20022 payment files locally, over stdio.

4 min readLast reviewed

pain001-mcp v0.0.70 exposes the Pain001 suite to AI agents as 21 Model Context Protocol tools. Claude Desktop, Claude Code, Cursor, and any MCP-compatible orchestrator can validate IBANs, migrate message versions, convert SWIFT MT101, and generate schema-validated pain.001 XML inside a conversation, on your own machine.

Card networks and PSPs have built agentic checkout rails. The corporate payment-file layer, where credit transfers are actually initiated, had no agent interface. This server fills that gap. Payment data never leaves your machine: the transport is stdio, and every tool is annotated read-only and idempotent, so an agent can explore safely without side effects.

01. The 21 tools#

Tool What it does
list_message_types List the 11 supported message definitions with human-readable names.
get_required_fields Return the required input fields for a message type.
get_input_schema Return the full JSON Schema for a message type.
validate_records Validate flat payment records against the input schema.
validate_identifier Check a single IBAN (ISO 13616 mod-97) or BIC (ISO 9362).
generate_message Generate XSD-validated pain XML from in-memory records.
generate_message_async Off-event-loop generation for large batches.
generate_message_from_file Generate XML from a CSV file on disk.
list_supported_formats List loadable on-disk formats (CSV, SQLite, JSON, JSONL, Parquet).
parse_camt053 Parse a camt.053 bank statement XML file.
parse_pain002 Parse a pain.002 payment status report.
inspect_template Show the CSV column headers of a bundled template.
validate_payment_scheme Enforce a scheme rulebook: SEPA SCT, Instant, SDD Core, B2B, or cross-border.
migrate_records Migrate records between pain.001 versions (e.g. .03 → .09).
validate_xml_against_schema Validate raw XML against the bundled official XSD.
sanitize_to_iso20022_charset Transliterate text to the ISO 20022 Latin character set.
convert_mt101 Convert a legacy SWIFT MT101 message into pain.001 records.
list_corpus_files List the validated example files pain001 ships: market scenarios by country and rail, and the schema coverage sets.
get_corpus_file Return the XML of one validated example file from the market corpus.
get_corpus_provenance Return the provenance sidecar of one example file: sources, retrieval dates, evidence state.
get_corpus_coverage Return the schema coverage verdict for one message type's coverage set.

The server also publishes a pain001://schema/{message_type} resource and a build_payment_batch prompt. Shorthand aliases resolve sensibly: pain.001 → pain.001.001.09, pain.008 → pain.008.001.02.

02. Registration#

The server is published in three places that agents and their clients browse. In the official MCP registry it is io.github.sebastienrousseau/pain001-mcp, published from the same tag as the PyPI release. The Glama directory listing carries its independent quality grades. The container image is ghcr.io/sebastienrousseau/pain001-mcp, tagged per release and multi-arch.

pip install pain001-mcp

Claude Desktop (claude_desktop_config.json):

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

claude mcp add pain001 -- pain001-mcp

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):

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

VS Code (.vscode/mcp.json in a workspace):

{
  "servers": {
    "pain001": {
      "type": "stdio",
      "command": "pain001-mcp"
    }
  }
}

Every block starts the same stdio server; only the file that carries it differs. The example corpus is reachable through list_corpus_files, get_corpus_file and get_corpus_provenance, and the same files are published for direct fetch at /corpus/index.json with the JSON Schema per edition under /corpus/schemas/.

A Docker image is published as ghcr.io/sebastienrousseau/pain001-mcp with build provenance attestation, and the server is listed in the MCP registry as io.github.sebastienrousseau/pain001-mcp.

03. Design decisions that matter in a payments context#

  • Read-only by contract. All 21 tools carry MCP ToolAnnotations with readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The server never writes to your filesystem.
  • Errors are data, not crashes. Tools return structured {"error": ...} payloads instead of raising, so agent loops degrade gracefully.
  • Local-only transport. stdio only: no network listener, no credentials, no payment data leaving the host.
  • Validated output or nothing. generate_message runs the same JSON Schema → scheme rulebook → XSD pipeline as the CLI; an agent cannot produce a malformed file.

Note the distinction: pain001 mcp (the core library's built-in server) exposes a minimal 5-tool surface. The full 17-tool surface documented here is the standalone pain001-mcp package.

FAQ#

No. The server generates and validates payment files; it has no bank connectivity and no tool with side effects beyond returning XML as text. Submission to your bank channel remains, by design, a human-controlled step.

It complements them. AP2 and similar protocols handle mandates and authorisation for agent-initiated commerce; pain001-mcp handles the ISO 20022 file layer that corporate banking channels actually consume. The related ap2-iso20022 project bridges the two.

Any MCP client speaking stdio works. Claude Desktop, Claude Code, and Cursor configurations are documented in the repository, and CI runs the official MCP Inspector against every release.