Ap2 Iso20022 MCP server

ap2-iso20022: Agent-payment mandates → wire-valid ISO 20022

Bridge [AP2][ap2] (Google's Agent Payments Protocol) and [x402][x402] (Coinbase's HTTP-402) mandates into ISO 20022 pain.001 / pacs.008 records — with spending-cap, expiry and authorisation guardrails, and an [MCP][mcp] server. These agentic-payment protocols authorise a payment; this library turns that authorisation into the bank-rail message that actually settles it — the rail the card networks and stablecoins don't cover.

Latest release: v0.0.5 — 11 MCP tools over stdio, streamable HTTP or

SSE, pure-Python (only mcp), 100% branch coverage, for Python 3.10+. Output feeds straight into

[pain001][pain001-mcp] / [pacs008][pacs008-mcp] to generate wire-valid XML.

Part of the ISO 20022 MCP suite.

Why

An agent with a signed AP2 mandate (or an x402 payment authorisation) can prove it's allowed to pay — but nothing in those protocols emits the pain.001 a bank needs to move the money. ap2-iso20022 is that missing hop. And because moving money is consequential, it only transforms and validates — producing the ISO record is deliberately separate from generating and sending it, so the actual payment stays an explicit, guarded step.

Install

pip install ap2-iso20022
# or run the MCP server without installing:
uvx --from ap2-iso20022 ap2-iso20022-mcp

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

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

Transports

One command line, three transports:

--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": {
    "ap2-iso20022": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

Flow: normalise → guardrail → convert

from ap2_iso20022 import bridge

# 1. Normalise the protocol payload into a canonical mandate.
mandate = bridge.from_ap2({
    "intent_id": "AP2-CoffeeRun-7",
    "payer": "Alice's Shopping Agent",
    "payer_account": "DE89370400440532013000",
    "merchant_name": "Blue Bottle Coffee",
    "payee_account": "GB29NWBK60161331926819",
    "amount": "12.50", "currency": "EUR", "memo": "oat latte",
    "spending_limit": "50.00",
    "signature": "eyJ...", "signature_type": "jws",
})

# 2. Guardrail before it becomes a payment.
check = bridge.check_mandate(mandate, as_of="2026-03-02T09:00:00")
assert check["ok"]          # required fields ok, within cap, not expired, signed

# 3. Convert to a pain.001 record that feeds pain001 -> wire-valid XML.
record = bridge.to_pain001(mandate)   # exact pain001 field names + JSON number amounts

Tools

Shortened. The full README is on GitHub.