Summary: iso20022-mcp is a unified MCP gateway exposing 7 read-only routing meta-tools that discover, describe, validate, generate, and parse ISO 20022 messages across the pain, pacs, camt, and acmt families.
search — find message types by use-case or keyword (e.g. "reconciliation", "pacs.008"), returning family and providing package.
list_families — list routed families, their capabilities, and whether each backing package is installed.
list_servers — map the whole suite: families, E&I messages (camt.056/camt.029), and specialized servers (reconciliation, agent-payment bridge).
describe — return required fields and the input JSON Schema for a given message type.
validate — check flat records against a message type's schema (field types, required fields, dates, IBAN/BIC) without generating XML.
generate — build validated ISO 20022 XML from records for outbound families (pain, pacs, acmt, plus camt.056 via camt-exceptions); camt.053 returns an explanatory error.
parse — convert inbound XML into structured data for pacs and camt only; pain/acmt are outbound-only with no parser.
Ergonomics — bare family aliases resolve to concrete versions (pain.001 → pain.001.001.09), failures return structured {error: ...} payloads listing all missing/invalid fields at once, and uninstalled families tell you exactly what to pip install.
Transports — stdio, streamable HTTP (/mcp), or HTTP+SSE (/sse), with loopback defaults and no built-in auth on HTTP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iso20022-mcp search for reconciliation messages"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
One Model Context Protocol server, one small set of meta-tools —
search, list_families, describe, validate, generate, parse — that
route across every ISO 20022 message family (pain · pacs · camt ·
acmt). Install one thing, discover the whole suite: an agent sees a handful
of verbs instead of the 60+ tools spread across five individual servers.
Latest release: v0.0.16: 7 routing meta-tools over stdio, streamable HTTP or SSE, light core (only
mcp), backing family servers as optional extras, actionable structured errors on everyvalidate/generatefailure, for Python 3.10+. The front door to the ISO 20022 MCP Suite.
The suite has a dedicated, best-in-class server per message family. That depth
is the point — but an agent shouldn't have to know which of five servers and
which of sixty tools it needs before it can act. iso20022-mcp is the thin
routing layer on top: ask it in plain terms ("I need to reconcile a
statement", "generate a credit transfer"), and it points you at — or executes
against — the right family. Small tool surface, whole-suite reach.
Related MCP server: camt053-mcp
iso20022-mcp is the generic message toolkit of eight coordinated,
vendor-neutral MCP servers that together cover the ISO 20022 bank-statement
workflow and the November 2026 structured-address cutover, plus a high-level orchestration layer — readiness scoring, clearing-profile linting, and audit evidence — statement depth,
whole-catalogue routing, reconciliation, multi-format ingestion, and address
remediation. Dependency ranges are kept aligned across the suite,
so the servers co-install cleanly in a single Python environment: start with
one, add the rest as your workflow grows.
Server | Scope | Surface | Install | Use it when |
ISO 20022 | 24 MCP tools · 4 prompts · 3 resources |
| You work with bank-to-customer statements end to end — the suite's flagship | |
Unified gateway: | 7 meta-tools |
| You want one entry point to every message family — this package | |
Matches expected | 7 MCP tools |
| You need explainable statement/payment reconciliation | |
Multi-format statement ingestion: ISO 20022 CAMT.053 and pain.001, SWIFT MT940, OFX/QFX, CSV | 5 MCP tools · 1 prompt · 1 resource |
| Your statements arrive in mixed or legacy formats | |
ISO 20022 postal-address classification, assessment & remediation for the November 2026 structured-address cutover ( | 9 MCP tools |
| You need debtor/creditor addresses cliff-ready ahead of 14 Nov 2026 | |
Orchestration gateway: detect → structurally validate → clearing-profile lint → readiness score, plus automated remediation and | 4 MCP tools |
| You want one high-level readiness / orchestration entry point over the suite | |
Manages, validates and serves bank-specific clearing profiles / rule packs (CBPR+, SEPA_Instant, FedNow, Generic); premium rule-pack entitlement gating | 4 MCP tools |
| You lint payments against your own institution's market practice | |
Compiles readiness findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack | 6 MCP tools |
| You need tamper-evident audit / certification artifacts |
In one line each: camt053-mcp is the bank-statement flagship (deepest
camt.05x surface, stdio + authenticated streamable HTTP);
iso20022-mcp is the generic message toolkit (a handful of verbs over
the whole catalogue); reconcile-mcp is the reconciliation workflow
(did the money we expected actually arrive?);
bankstatementparser-mcp is the ingestion layer (many formats in, one
transaction shape out); and structured-address-fix-mcp is the
postal-address specialist (debtor/creditor addresses cliff-ready for the
Nov 2026 cutover).
The gateway also routes to the per-family servers —
pain001-mcp, pacs008-mcp,
acmt001-mcp, and camt-exceptions —
installed as extras (see Routing).
The core is light. Add the families you need as extras (or [all]):
pip install "iso20022-mcp[all]" # every family
pip install "iso20022-mcp[pacs,camt]" # just interbank + statements
pip install iso20022-mcp # core only; families report as not installed
# or run without installing:
uvx --from "iso20022-mcp[all]" iso20022-mcpMCP client config (e.g. Claude Desktop):
{
"mcpServers": {
"iso20022": {
"command": "iso20022-mcp"
}
}
}One command line, three transports:
Command | Transport | Endpoint | Protocol revisions |
| stdio | the client spawns the process | 2026-07-28, 2025-11-25 |
| Streamable HTTP |
| 2026-07-28 (stateless, |
| HTTP+SSE (2024-11-05) |
| 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
passmcp in both protocol
eras and over SSE with the MCP SDK client; see
ADR 0001.
{
"mcpServers": {
"iso20022": { "url": "http://127.0.0.1:8000/mcp" }
}
}The 7 routing meta-tools:
search — Find message types by use-case / keyword ("reconciliation", "pacs.008"). (families: all — catalogue)
list_families — List families, their capabilities, and which backing packages are installed. (families: all)
list_servers — Full suite map: families + E&I messages + specialized servers (reconcile, agent-payment bridge). (families: all)
describe — Required fields + input JSON Schema for a message type. (families: all)
validate — Validate records against a message type's schema. (families: all)
generate — Generate a validated ISO 20022 XML message from records. (families: pain · pacs · acmt)
parse — Parse an inbound ISO 20022 XML message into structured data. (families: pacs · camt)
Operations are capability-aware: generate on a camt.053 statement (an
inbound format) returns a clear, explanatory error rather than failing
obscurely, and every "package not installed" case tells you exactly what to
pip install.
Three ergonomics guarantees hold across the routed families:
Actionable structured errors. Any error a backing server raises —
not just the ones it returns — reaches the agent as an
{"error": "<Type>: <message>"} payload instead of an opaque
tool-execution failure. For pain generation the error lists every
missing or invalid field at once, so one fix-and-retry suffices.
Family aliases for message_type. Bare family names resolve to a
concrete version via the backing server: pain.001 →
pain.001.001.09, pain.008 → pain.008.001.02. Fully-versioned
types are still preferred where you know them.
Per-family parse coverage, stated up front. parse covers the
inbound families only: pacs (e.g. pacs.008) and camt (e.g.
camt.053). The initiation families pain and acmt are
outbound-only — they have no parser here, so don't attempt a
generate→parse round-trip for pain.001 or acmt.001; use validate
(or the backing server's XSD validation) instead.
Prefix | Family | Backing server | generate | parse |
| Customer Credit Transfer Initiation | ✅ | — | |
| FI-to-FI Customer Credit Transfer | ✅ | ✅ | |
| Bank-to-Customer Statement | — | ✅ | |
| Account Opening Instruction | ✅ | — | |
| Cancellation / Resolution (E&I) | ✅ | — |
generate("camt.056.001.12", …) routes to camt-exceptions. The gateway also
surfaces the specialized servers — reconcile-mcp and
ap2-iso20022 — via search and list_servers for discovery
(they're invoked through their own tools).
The gateway imports each backing server lazily and optionally — the core
depends only on mcp, and a family's server is loaded on first use. Message
types are matched on their prefix (pacs.008.001.08 → pacs). The pain
extra requires pain001-mcp >= 0.0.56, the release that carries the
LLM-ergonomic generate surface (field aliases, computed nb_of_txs /
ctrl_sum, all-at-once field errors) the gateway's guarantees build on.
search(query="reconciliation")
→ [{ "message_type": "camt.053", "family": "camt", "package": "camt053-mcp" }]
describe(message_type="pacs.008") # required fields + input schema
validate(message_type="pacs.008", records=[…])
generate(message_type="pain.001", records=[…]) # → { "xml": "<Document>…" }
# bare "pain.001" resolves to pain.001.001.09; on failure the payload is
# { "error": "Missing required fields for pain.001.001.09: …" } listing
# every missing or invalid field at once — fix them all and retry once
parse(message_type="camt.053", xml="<Document>…")
# parse covers pacs + camt only; pain and acmt are outbound-onlyFor the dedicated reconciliation engine that matches camt.053 statements
against expected pain.001 payments, see reconcile-mcp.
git clone https://github.com/sebastienrousseau/iso20022-mcp
cd iso20022-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest # 100% branch coverage gate (backends faked)
ruff check iso20022_mcp tests && black --check iso20022_mcp tests && mypy iso20022_mcpThis project is dual-licensed under either:
Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.
mcp-name: io.github.sebastienrousseau/iso20022-mcp
Describe a message type: its required fields and input JSON Schema, resolved from the family's backing server. When to use: After 'search', to obtain the schema and required field names for the flat records that 'validate' and 'generate' take. Not for: Raw XML payloads; 'parse' reads those. Behavior: Read-only, idempotent resolution from local schemas. Errors return a structured {'error': ...} payload rather than raising.
| Name | Required | Description | Default |
|---|---|---|---|
| message_type | Yes | ISO 20022 message type, e.g. 'pain.001.001.09', 'pacs.008' or 'camt.053'. For pain messages a fully-versioned type is preferred; the bare family name 'pain.001' resolves to 'pain.001.001.09'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description usefully adds that resolution comes from local schemas and that errors return a structured {"error": ...} payload instead of raising, which is behavior beyond the annotations. It does not detail return shape, but that is covered by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: core purpose first, then When to use, Not for, and Behavior. Every sentence carries distinct routing or behavioral information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not explain return values. It covers purpose, usage timing, exclusions, resolution behavior, and error handling, leaving no meaningful gap for an agent selecting or invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter is fully documented in the schema, including examples and the bare-family-name resolution rule. The description does not add parameter syntax beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Describe a message type: its required fields and input JSON Schema.' It also names the backing source and clearly differentiates itself from siblings by explaining that it feeds 'validate' and 'generate' and is not the tool for raw XML (that is 'parse').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage timing ('After search, to obtain the schema...') and an explicit exclusion ('Not for: Raw XML payloads; parse reads those'). An agent can decide when to call this versus its siblings without inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a validated ISO 20022 XML message from records; the XML document is returned in the 'xml' key. On failure the 'error' value lists every missing or invalid field at once — fix them all and retry once. When to use: Outbound initiation and interbank messages (pain.001, pacs.008, acmt.001, camt.056). Not for: Inbound statements (camt.053); they have no generator and return an explanatory error. Behavior: Pure transformation; read-only and idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| records | Yes | List of flat record objects (field name → value). Field names come from the family's input schema — call describe(message_type) for the required fields. For pain.001 credit transfers the key fields are: id, date ('YYYY-MM-DD' accepted), initiator_name, payment_id, requested_execution_date ('YYYY-MM-DD'), debtor_name, debtor_account_IBAN, debtor_agent_BIC, creditor_name, creditor_account_IBAN, creditor_agent_BIC, payment_amount (alias 'amount'), currency (alias 'payment_currency'), remittance_information; batch_booking takes JSON true/false, and nb_of_txs/ctrl_sum are computed automatically. IBAN and BIC values are strictly validated, never coerced. | |
| message_type | Yes | ISO 20022 message type, e.g. 'pain.001.001.09', 'pacs.008' or 'camt.053'. For pain messages a fully-versioned type is preferred; the bare family name 'pain.001' resolves to 'pain.001.001.09'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/destructive=false, so 'pure transformation; read-only and idempotent' is largely redundant. However, the description adds genuinely new behavior: errors list every missing/invalid field at once and the caller should fix all and retry once. That error/retry contract is valuable context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and return value, then clearly labeled 'When to use', 'Not for', and 'Behavior' segments. Dense but every clause carries signal; no filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be fully re-explained, yet the 'xml'/'error' keys are still surfaced. Purpose, routing, failure behavior, and validation strictness are all covered for a 2-parameter transformation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in depth (fields, aliases, validation). The description adds little parameter-specific meaning beyond reiterating validation behavior, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Generate a validated ISO 20022 XML message from records') and immediately names the return key. It is clearly distinguishable from siblings like parse and validate, and the message-family examples make the scope concrete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Has explicit 'When to use' (outbound initiation and interbank messages) and 'Not for' (inbound camt.053, which has no generator). Both inclusion and exclusion conditions are spelled out, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every ISO 20022 family the gateway routes to (pain, pacs, camt, acmt): its capabilities, backing package, and whether that package is installed in this environment. When to use: Use to check environment readiness and verify whether optional backing packages (pain001-mcp, pacs008-mcp, camt053-mcp, acmt001-mcp) are installed. Not for: Searching specific schemas; 'search' and 'describe' cover those. Behavior: Pure in-memory introspection; read-only and idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description's 'read-only and idempotent' restates that. What it adds beyond the annotations is the operational nature — 'pure in-memory introspection' — which tells the agent there is no network I/O or external side effect, plus the fact that it reports installation status per backing package.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and resource, then organized into clearly labeled 'When to use', 'Not for', and 'Behavior' segments. Every sentence carries routing or behavioral information; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Zero parameters, rich annotations, and an output schema that carries the return shape, so the description's job is primarily routing and readiness semantics — both delivered. An agent has everything it needs to decide to call this and to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. Describing the return contents (capabilities, backing package, installed flag) is useful but belongs to output semantics rather than parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List every ISO 20022 family the gateway routes to') and enumerates the concrete families covered (pain, pacs, camt, acmt) plus what each entry contains. It clearly distinguishes itself from the schema-oriented siblings by naming 'search' and 'describe' as the tools for a different job.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' (check environment readiness, verify optional backing packages are installed) and an explicit 'Not for' that routes searching specific schemas to 'search' and 'describe'. Both the condition and the alternative are stated, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the whole ISO 20022 suite the gateway knows: the message families (pain/pacs/camt/acmt), the Exceptions & Investigations messages (camt.056/camt.029), and the specialized servers (reconciliation, agent-payment bridge) with what each does. When to use: Use to discover available specialized servers across the suite and route cross-cutting payments workflows. Not for: Building or reading messages; the gateway tools 'generate', 'parse' and 'validate' do that. Behavior: Pure in-memory catalog listing; read-only and idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context by calling it a 'pure in-memory catalog listing', but mostly repeats the read-only and idempotent traits rather than adding deeper operational detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the scope, then uses labeled 'When to use', 'Not for' and 'Behavior' sections. Every sentence contributes to routing or behavioral understanding, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the empty input schema, comprehensive annotations and existing output schema, the description supplies the remaining needed context: what is listed, when to use it, what it is not for, and that it is a read-only in-memory catalog. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the empty schema is fully consistent with the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb, 'List', and a specific resource: the whole ISO 20022 suite, including message families and specialized servers, with those contents enumerated. It also explicitly separates itself from generate/parse/validate for building or reading messages, so an agent can tell what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit 'When to use' section about discovering specialized servers and routing cross-cutting payments workflows. It also includes a clear 'Not for' section naming the alternative tools 'generate', 'parse' and 'validate' for message building and reading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse an inbound ISO 20022 XML message into structured data. Parse coverage is per-family: pacs (e.g. pacs.008) and camt (e.g. camt.053) only. The initiation families pain and acmt are outbound-only — they have NO parser here, so a generate→parse round-trip for pain.001 or acmt.001 fails; 'validate' or the backing server's XSD validation checks those instead. When to use: Use to extract structured transactions, entries, debtor/creditor data, and balances from inbound messages (pacs.008 customer credit transfers, camt.053 statements). Not for: Outbound initiation families (pain.001, acmt.001). Behavior: Pure in-memory XML parsing; read-only and idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| xml | Yes | Raw ISO 20022 XML to parse. | |
| message_type | Yes | ISO 20022 message type, e.g. 'pain.001.001.09', 'pacs.008' or 'camt.053'. For pain messages a fully-versioned type is preferred; the bare family name 'pain.001' resolves to 'pain.001.001.09'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses the per-family parser coverage limit, that pain/acmt round-trips fail, and that parsing is pure in-memory. These are consequential behavioral constraints an agent cannot derive from the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and structured with 'When to use / Not for / Behavior' labels. There is mild redundancy between the coverage sentence and the 'Not for' line, both restating that pain/acmt are outbound-only with no parser.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter parsing tool with an output schema and full annotations, the description covers coverage limits, usage boundaries, alternatives, and execution behavior. No material gap remains for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description meaningfully constrains the valid domain of message_type by stating only pacs and camt families are parseable. It adds practical meaning beyond the schema's example values without restating syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Parse an inbound ISO 20022 XML message into structured data') and immediately bounds scope to inbound messages. It clearly distinguishes itself from siblings like validate and generate, which the 'Not for' section reinforces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Has explicit 'When to use' and 'Not for' sections naming the exact conditions (pacs.008, camt.053 inbound) and the excluded families (pain.001, acmt.001), routing the agent to 'validate' or XSD validation as the alternative. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the ISO 20022 catalogue by use-case, message type or keyword (e.g. 'reconciliation', 'make a payment', 'pacs.008') and get the matching message types, their family, and which package provides them. When to use: First, to discover which ISO 20022 message type fits your workflow and which backing package supplies it. Not for: Inspecting fields or checking records once the message type is known; 'describe' and 'validate' cover those. Behavior: Pure in-memory lookup; read-only and idempotent with zero network or filesystem I/O.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Use-case, message type or keyword. Empty = all. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds context the annotations do not: pure in-memory lookup with zero network or filesystem I/O, which tells the agent this call is cheap and cannot fail on external dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the purpose, then segments usage into labeled 'When to use', 'Not for' and 'Behavior' clauses. Dense but every sentence carries routing or behavioral information; nothing is redundant with the name or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be re-explained. For a single-parameter discovery tool, the description covers purpose, alternatives, and I/O cost profile completely, leaving nothing an agent needs before calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already documents the single 'query' parameter including the empty-equals-all behavior. The description still adds value by giving concrete example query values ('reconciliation', 'make a payment', 'pacs.008'), showing both natural-language and identifier-style inputs are accepted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) plus resource (ISO 20022 catalogue), the searchable facets (use-case, message type, keyword) with concrete examples, and the return shape (matching message types, their family, providing package). This clearly separates it from 'describe' and 'validate', which are named as the alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains explicit 'When to use' (first step to discover which message type fits a workflow and which package supplies it) and explicit 'Not for' (field inspection and record checks once the type is known), naming 'describe' and 'validate' as the tools that cover those cases. No routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate records for a message type against its JSON Schema, via the family's backing server. When to use: Ahead of 'generate', to verify record field types, required fields, date formats (YYYY-MM-DD), and IBAN/BIC constraints without generating XML. Not for: Raw XML documents; the backing server's XSD validation tools and 'parse' handle those. Behavior: Pure deterministic validation; read-only and idempotent with zero network I/O.
| Name | Required | Description | Default |
|---|---|---|---|
| records | Yes | List of flat record objects (field name → value). Field names come from the family's input schema — call describe(message_type) for the required fields. For pain.001 credit transfers the key fields are: id, date ('YYYY-MM-DD' accepted), initiator_name, payment_id, requested_execution_date ('YYYY-MM-DD'), debtor_name, debtor_account_IBAN, debtor_agent_BIC, creditor_name, creditor_account_IBAN, creditor_agent_BIC, payment_amount (alias 'amount'), currency (alias 'payment_currency'), remittance_information; batch_booking takes JSON true/false, and nb_of_txs/ctrl_sum are computed automatically. IBAN and BIC values are strictly validated, never coerced. | |
| message_type | Yes | ISO 20022 message type, e.g. 'pain.001.001.09', 'pacs.008' or 'camt.053'. For pain messages a fully-versioned type is preferred; the bare family name 'pain.001' resolves to 'pain.001.001.09'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the 'read-only and idempotent' phrasing is partially redundant. It nonetheless adds real context beyond the annotations: 'pure deterministic validation' and 'zero network I/O', plus the specific class of checks performed (types, required fields, date formats, IBAN/BIC).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded, then cleanly labeled 'When to use:', 'Not for:' and 'Behavior:' blocks. It is dense but every clause carries information an agent needs, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation, and the description covers prerequisites, the validation scope, side-effect profile and sibling alternatives. Nothing an agent needs to invoke this two-parameter tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the records parameter is exhaustively documented, so the schema does the heavy lifting. The description still adds meaning by framing the parameters as validation targets: it names the accepted date format (YYYY-MM-DD) and the IBAN/BIC constraints enforced, telling the agent what the two inputs are scrutinized against.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb (validate) and resource (records for a message type against its JSON Schema), and even names the mechanism (the family's backing server). It clearly separates itself from 'generate' and 'parse' by describing validation-before-generation rather than XML production or parsing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'When to use' (ahead of 'generate' to verify types, required fields, date formats and IBAN/BIC) and an explicit 'Not for' boundary (raw XML, XSD tools, and 'parse'). Both the triggering condition and the excluded cases are stated, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.0.5describegeneratelist_familieslist_serversparsesearchvalidateScored across 7 tools
The core transform tools (search, describe, validate, generate, parse) each target a distinct action and are hard to confuse. However, list_families and list_servers both perform catalogue-style listing and could be misselected, and search overlaps with them at the discovery level. The explicit 'When to use / Not for' notes mitigate this, but the boundary between the three listing/discovery tools is not perfectly crisp.
Most names are single imperatives (search, describe, validate, generate, parse) with a consistent snake_case, verb-first pattern for the two listing tools (list_families, list_servers). The mix of bare verbs and verb_noun is a minor deviation but remains predictable and readable.
Seven tools is well-scoped for an ISO 20022 gateway spanning discovery, schema description, validation, generation, and parsing. Each tool earns its place with no redundant entries.
The surface covers the discovery-to-transform lifecycle (search, describe, validate, generate, parse) and documents direction-specific limits. Minor gaps exist—pain/acmt messages have no parser and camt.053 has no generator—but these are intentional, documented, and covered by backing-server XSD validation, so agents are not left at a dead end.
Look up ISO 20022 messages, bank transaction codes, legacy MT replacements, schemes and code sets.
Generate and validate SEPA ISO 20022 XML (pain.001, pain.008) and SWIFT MT103 payment messages.
ISO20022Oracle - 12 ISO 20022 tools: pacs/pain/camt parsing, MX validation, MT migration.
Single-connection MCP & A2A gateway indexing 490+ verified tools with x402 & MPP settlement.
