@iso-compliant/mcp-server

MIT-licensed Model Context Protocol server for iso-compliant — the distribution wedge for the headless ISO 20022 compliance engine. Free-tier tools (IBAN / QRR / SCOR checksums, structured-address lint, ISO 20022 field reference) run pure-local with no network and no API key. Paid tools (pain.001, camt.053, pain.002, Swiss QR-bill) proxy to https://api.iso-compliant.com under a bearer token.

Install

npx -y @iso-compliant/mcp-server

Node 18+. Pure ESM.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "iso-compliant": {
      "command": "npx",
      "args": ["-y", "@iso-compliant/mcp-server"],
      "env": { "ISOCOMPLIANT_API_KEY": "iso_live_..." }
    }
  }
}

Cursor (~/.cursor/mcp.json) — stdio or remote SSE

{
  "mcpServers": {
    "iso-compliant": {
      "url": "https://mcp.iso-compliant.com/sse",
      "headers": { "Authorization": "Bearer iso_live_..." }
    }
  }
}

For local stdio in Cursor, use the same shape as the Claude Desktop snippet.

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | ISOCOMPLIANT_API_KEY | (unset) | Bearer token for gated tools. Free tools work without it. | | ISOCOMPLIANT_API_BASE | https://api.iso-compliant.com | Override for staging / self-hosted deployments. | | ISOCOMPLIANT_MCP_TELEMETRY | 1 | Set to 0 (or false / off / no) to disable anonymous invocation counters. | | ISOCOMPLIANT_MCP_LOCALE | en | Tool descriptions and hint copy locale: en / de / fr / it. | | PORT | 3939 | SSE transport port when launched with --sse. |

Tool catalog

| Tier | Tool | Endpoint or compute | |------|------|---------------------| | free | isocompliant.validate_iban | local — ISO 13616 mod-97 | | free | isocompliant.qrr_checksum | local — Swiss QRR mod-10 (Lührmann) | | free | isocompliant.scor_checksum | local — ISO-11649 mod-97-10 | | free | isocompliant.structured_address_lint | local — SWIFT 2026 structured-address check | | free | isocompliant.iso20022_schema_docs | local — field reference markdown | | gated | isocompliant.qrbill.generate | POST /v1/qr-bill | | gated | isocompliant.sepa.credit_transfer | POST /v1/iso20022/pain.001 | | gated | isocompliant.sepa.direct_debit | POST /v1/iso20022/pain.008 | | gated | isocompliant.camt053.parse | POST /v1/iso20022/camt.053/parse | | gated | isocompliant.pain002.parse | POST /v1/iso20022/pain.002/parse | | gated | isocompliant.address.restructure | POST /v1/address/restructure — deterministic stub; real DistilBERT in Phase 2 | | gated | isocompliant.reconcile | POST /v1/reconcile — the durable moat: closes the loop from outbound payment file to bank statement, mapping each entry back to the customer's internal invoice/order ID across per-bank dialect quirks. No model required — deterministic carrier-field extraction + per-bank handler ranking. |

When a gated tool is invoked without ISOCOMPLIANT_API_KEY, the server returns an isError response carrying the locale-aware sign-up prompt with https://iso-compliant.com/signup.

Resources catalog

The server exposes eight read-only resources via the MCP resources/list and resources/read methods. Each is a hand-authored summary that primes a model (or a developer) with the field map, key cardinalities, and citation links for the authoritative source. Full XSDs (100-500 KB each) are not bundled — these summaries are the structural reference, and the iso-compliant API validates against the authoritative schema on every emit.

| URI | Type | Content | |-----|------|---------| | iso20022://pain.001.001.09/xsd | text/markdown | pain.001.001.09 XSD summary (Customer Credit Transfer Initiation). | | iso20022://pain.001.001.09.ch.03/xsd | text/markdown | Swiss pain.001 profile (CH-03) — narrowings on top of pain.001.001.09. | | iso20022://pain.008.001.02/xsd | text/markdown | pain.008.001.02 XSD summary (Customer Direct Debit Initiation). | | iso20022://camt.053.001.08/xsd | text/markdown | camt.053.001.08 XSD summary (Bank-to-Customer Statement). | | iso20022://pain.002.001.10/xsd | text/markdown | pain.002.001.10 XSD summary (Customer Payment Status Report). | | swiss-qr-bill://spc-v0200/spec | text/markdown | Swiss Payment Code v0200 specification (QR-bill payload). | | structured-address://swift-2026-11-14/rules | text/markdown | SWIFT MX / CBPR+ structured-address mandate (effective 2026-11-14). | | rule-pack://ubs/2026.06/manifest | application/json | UBS Switzerland pain.001.001.09.ch.03 rule pack v2026.06 manifest (skeleton, public-IG sourced). |

Prompts catalog

Four MCP prompts wire the tools and resources above into end-to-end workflows. The MCP host surfaces them as slash commands (Claude Desktop), palette entries (Cursor), or chips (Continue / Cline).

| Name | Required args | Workflow | |------|---------------|----------| | generate-sepa-payroll | debtor_iban, payments_csv_path | Validate IBANs → lint addresses → emit a pain.001 payroll batch with CtgyPurp=SALA. | | reconcile-bank-statement | camt053_path, expected_invoices_csv | Parse a camt.053 → join entries against expected invoices via isocompliant.reconcile → classify matched / partial / unmatched. | | audit-structured-address-readiness | sample_addresses_csv | Lint a sample for the SWIFT 2026-11-14 cut-over → bucket compliant / hybrid / structurable / incomplete → 90-day remediation plan. | | qr-bill-from-invoice | invoice_json | Validate the IBAN → choose reference type (QRR / SCOR) → compose and emit the Swiss QR-bill via isocompliant.qrbill.generate. |

Transports

• stdio (default) — for Claude Desktop, Cursor, Continue, Cline.
• SSE — iso-compliant-mcp --sse. Mounts GET /sse and POST /messages?sessionId=.... Listens on $PORT (default 3939). Also exposes GET /health.

Telemetry

Opt-in, anonymous, counter-only. The server tracks install and tool-invocation counts plus the active locale. Payload content is never logged — no IBAN, no address, no amount, no name leaves the local process when a free tool runs. Gated tools transmit only to api.iso-compliant.com under the customer's own bearer token under a zero-retention contract. Disable entirely with ISOCOMPLIANT_MCP_TELEMETRY=0.

Development

npm install
npm test          # vitest
npm run build     # tsup → dist/index.js with shebang preserved
npm start         # node dist/index.js (stdio)