acmt001-mcp

<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->

# acmt001-mcp: An MCP Server for ISO 20022 Account Management

![acmt001-mcp banner][banner]

[![PyPI Version][pypi-badge]][07]
[![Python Versions][python-versions-badge]][07]
[![PyPI Downloads][pypi-downloads-badge]][07]
[![Licence][licence-badge]][01]
[![Tests][tests-badge]][tests-url]
[![Quality][quality-badge]][quality-url]
[![Documentation][docs-badge]][docs-url]
[![Glama MCP server score][glama-badge]][glama-url]

**A [Model Context Protocol][mcp] server that exposes the [`acmt001`][core]
ISO 20022 Account Management library as tools for AI agents and assistants** —
discover message types, inspect input schemas, validate records and financial
identifiers, and generate validated XML, all from your favourite MCP client.

> **Latest release: v0.0.11**: 7 MCP tools over stdio, streamable HTTP or
> SSE, all backed by the shared `acmt001.services` layer, for Python 3.10+.
> [See what's new →][release-005]

<p align="center">
  <img src=".github/demo.gif" alt="acmt001-mcp Demo" width="100%" />
</p>

---

## Contents

- [Overview](#overview)
- [Install](#install)
- [Quick Start](#quick-start)
- [Transports](#transports)
- [Tools](#tools)
- [Using the tools](#using-the-tools)
- [Benchmarks](#benchmarks)
- [Documentation](#documentation)
- [Development](#development)
- [License](#license)
- [Contribution](#contribution)
- [Acknowledgements](#acknowledgements)

## Overview

The [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents
and assistants discover and call external tools in a uniform way. **acmt001-mcp**
is an MCP server that turns the [`acmt001`][core] library into a set of
first-class agent tools, so an assistant can generate and validate **ISO 20022
`acmt` Account Management XML messages** — the standardised instructions,
confirmations, and reports that govern the lifecycle of a bank account (opening,
maintenance, closing, identification, and switching) — directly from a
conversation.

Every tool is a thin, typed wrapper over `acmt001.services` — the single shared
facade also used by the CLI and REST API — so all interfaces behave identically.
Tools return JSON-serialisable data; on a validation error they return an
`{"error": ...}` payload rather than raising.

- **Website:** <https://acmt001.com>
- **Source code:** <https://github.com/sebastienrousseau/acmt001-mcp>
- **Bug reports:** <https://github.com/sebastienrousseau/acmt001-mcp/issues>

This package is part of the **acmt001 suite** — a set of independently
installable packages that share the `acmt001.services` layer:

- [`acmt001`][core] — the core library (CLI + REST API)
- `acmt001-mcp` — this package, the **Model Context Protocol** server
- [`acmt001-lsp`][lsp] — the **Language Server Protocol** server for editors

```mermaid
flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["acmt001-mcp"]
    B -->|delegates to| C["acmt001.services"]
    C -->|render + validate| D["ISO 20022 acmt XML"]
```

## Install

**acmt001-mcp** runs on macOS, Linux, and Windows and requires **Python 3.10+**
and **pip**. It pulls in the core `acmt001` library and the MCP SDK
automatically.

```sh
python -m pip install acmt001-mcp
```

> **Note:** while the core `acmt001` library is not yet on PyPI, install it from
> source first:
>
> ```sh
> python -m pip install "git+https://github.com/sebastienrousseau/acmt001.git"
> python -m pip install acmt001-mcp
> ```

<details>
<summary>Using an isolated virtual environment (recommended)</summary>

```sh
python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U acmt001-mcp
```
</details>

## Quick Start

Launch the server over stdio (the default transport):

```sh
acmt001-mcp
```

Register it with any MCP client (e.g. Claude Desktop) by adding it to the
client's configuration:

```json
{
  "mcpServers": {
    "acmt001": { "command": "acmt001-mcp" }
  }
}
```

The agent can then call the tools below to validate account data and generate
ISO 20022 messages on demand.

## Transports

One command line, three transports:

| Command | Transport | Endpoint | Protocol revisions |
| :--- | :--- | :--- | :--- |
| `acmt001-mcp` | stdio | the client spawns the process | 2026-07-28, 2025-11-25 |
| `acmt001-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 |
| `acmt001-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](https://github.com/sebastienrousseau/scout) in both protocol
eras and over SSE with the MCP SDK client; see
[ADR 0001](docs/adr/0001-three-transports-one-command-line.md).

```json
{
  "mcpServers": {
    "acmt001": { "url": "http://127.0.0.1:8000/mcp" }
  }
}
```

## Tools

All tools delegate to the shared `acmt001.services` layer, so they behave
identically to the CLI and REST API.

- `list_message_types` — List the 34 supported acmt message types
- `get_required_fields` — Required input fields for a message type
- `get_input_schema` — Full input JSON Schema for a message type
- `validate_records` — Validate flat records against a message type
- `validate_identifier` — Validate an IBAN, BIC, or LEI
- `generate_message` — Generate a validated acmt XML message
- `verify_lei_online` — Look an LEI up in the live GLEIF register (needs the `online` extra)

## Using the tools

You can invoke the tools in-process — without a transport — straight through the
server instance. This mirrors what an agent receives over stdio. The runnable
version of this snippet lives in [`examples/mcp_tools.py`](https://github.com/sebastienrousseau/acmt001-mcp/blob/main/examples/mcp_tools.py).

```python
import asyncio

from acmt001_mcp.server import server

# A single flat account-opening record.
record = [
    {
        "msg_id": "ACMT-MSG-0001",
        "creation_date_time": "2026-01-15T10:30:00",
        "process_id": "ACMT-PRC-0001",
        "account_id": "GB29NWBK60161331926819",
        "account_currency": "EUR",
        "account_name": "Treasury Operating Account",
        "account_type_cd": "CACC",
        "account_servicer_bic": "NWBKGB2LXXX",
        "account_owner_name": "Acme Embedded Finance Ltd",
        "account_owner_country": "GB",
        "org_full_legal_name": "Acme Embedded Finance Limited",
        "org_country_of_operation": "GB",
        "org_id_lei": "5493001KJTIIGC8Y1R12",
    }
]


async def main() -> None:
    async def call(name, args):
        result = await server.call_tool(name, args)
        content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # Validate an identifier.
    print(await call("validate_identifier",
                     {"kind": "lei", "value": "5493001KJTIIGC8Y1R12"}))
    # -> {"kind": "lei", "value": "5493001KJTIIGC8Y1R12", "valid": true}

    # Generate a validated ISO 20022 Account Opening Request.
    xml = await call("generate_message",
                     {"message_type": "acmt.007.001.05", "records": record})
    print(xml[:46])  # -> <?xml version="1.0" encoding="UTF-8"?> ...


asyncio.run(main())
```

Run it directly:

```sh
python examples/mcp_tools.py
```

## Benchmarks

```sh
python benches/bench_tool_dispatch.py           # full run
python benches/bench_tool_dispatch.py --quick   # what CI runs
```

The benchmark measures what an *agent* waits for: the dispatch floor
(`list_message_types`, around a microsecond), the metadata lookups used
to build a request, and the two batch tools side by side.

The result worth knowing is the asymmetry between those two.
`validate_records` checks every record, so it is linear in batch size.
`generate_message`, for a single-account message type like the default
`acmt.007.001.05`, renders **only the first record** — twenty-seven of
the thirty-four templates work this way. So validating a hundred records
and generating from them costs roughly 260 ms of validation against 6 ms
of generation, and returns one message rather than a hundred.

That is correct ISO 20022 behaviour and a real trap when batching, which
is why the benchmark prints output size beside the timings: flat bytes
across growing input is what tells you the rest of the batch was not
rendered. See [docs/benchmarks.md](docs/benchmarks.md).

## Documentation

- **Rendered docs (API reference, ADRs, benchmarks, changelog):**
  [sebastienrousseau.github.io/acmt001-mcp](https://sebastienrousseau.github.io/acmt001-mcp/)
- **Runnable example:** [`examples/mcp_tools.py`](https://github.com/sebastienrousseau/acmt001-mcp/blob/main/examples/mcp_tools.py)
- **Architecture decisions:** [docs/adr/](docs/adr/index.md)
- **Release history:** [CHANGELOG.md](https://github.com/sebastienrousseau/acmt001-mcp/blob/main/CHANGELOG.md)
- **Core library docs:** [acmt001.com](https://acmt001.com)
- **MCP specification:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

## Development

**acmt001-mcp** uses [Poetry](https://python-poetry.org/) and
[mise](https://mise.jdx.dev/).

```bash
git clone https://github.com/sebastienrousseau/acmt001-mcp.git && cd acmt001-mcp
mise install
poetry install
poetry shell
```

> This package depends on the core `acmt001` library. Until it is on PyPI,
> install it from source first:
> `pip install "git+https://github.com/sebastienrousseau/acmt001.git"`.

A `Makefile` orchestrates the quality gates (kept in lockstep with CI):

```bash
make chec