Python API reference

The standalone server’s importable Python surface (used by the runnable example and any agent that wraps the server instance directly).

acmt001-mcp: a Model Context Protocol server for the acmt001 library.

Tool, prompt and resource module

Every tool, the prompt and both resources are plain functions registered on the server object at import time, so they can be called in-process without a transport.

Model Context Protocol (MCP) server for Acmt001.

This server exposes the Acmt001 library’s ISO 20022 acmt capabilities as MCP tools so that any MCP-compatible client (Claude Desktop, IDEs, agents) can discover message types, inspect input schemas, validate records and financial identifiers, and generate validated XML messages.

Every tool is a thin, typed wrapper over acmt001.services – the single shared facade also used by the CLI, REST API, and LSP server – so all interfaces behave identically. Tools return JSON-serializable data (dicts, lists, or strings); on a ValueError they return an {"error": ...} dictionary rather than raising.

Launching the server:

  • As a console script (installed with the servers extra):

    acmt001-mcp

  • Programmatically:

    from acmt001_mcp.server import main
main()

  • In an MCP client config (e.g. Claude Desktop claude_desktop_config.json):

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

stdio by default; --transport streamable-http or --transport sse listens on --host/--port instead. See acmt001_mcp._cli.

acmt001_mcp.server.describe_message_type_resource(message_type)[source]

Describe a single acmt message type’s input record as a JSON resource.

This is the resource form of get_required_fields + get_input_schema for one message type: it returns both the required-field names and the full input JSON Schema, serialized as a JSON string. On an unknown message type it returns an {"error": ...} payload instead of raising, mirroring the tools’ error contract.

Parameters:

message_type (str) – A supported ISO 20022 acmt message type.

Return type:

str

Returns:

A JSON object string {"message_type", "required_fields", "input_schema"}, or {"error": ...} for an unknown type.

acmt001_mcp.server.generate_message(message_type, records)[source]

Generate a validated ISO 20022 acmt XML message from in-memory records.

This is the primary generation tool: pass account records you already hold in memory and receive an XSD-validated XML document; no file is written. Run validate_records first to surface record-level errors, and list_message_types to confirm the message_type string.

Returns the validated XML document as a string, or an {"error": ...} payload (serialized) if generation fails.

Parameters:

  • message_type (str) – A supported ISO 20022 acmt message type.

  • records (list[dict]) – One or more flat account records.

Return type:

str

acmt001_mcp.server.get_input_schema(message_type)[source]

Return the full JSON Schema for a message type’s flat input record.

Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use get_required_fields; to actually check records against this schema use validate_records.

Parameters:

message_type (str) – A supported ISO 20022 acmt message type.

Return type:

dict

acmt001_mcp.server.get_required_fields(message_type)[source]

List only the required input field names for an acmt message type.

Use this for a quick checklist of the mandatory columns before building account records. When you need full type/format constraints (not just which fields are required), call get_input_schema instead.

Parameters:

message_type (str) – A supported ISO 20022 acmt message type.

Return type:

list[str]

acmt001_mcp.server.list_message_types()[source]

List every supported ISO 20022 acmt message type and its human name.

Use this first, before any generation or validation call, to discover the exact message_type strings this server accepts (e.g. acmt.001.001.08 Account Opening Instruction). Do not use it to fetch a type’s fields or schema – call get_required_fields or get_input_schema for that.

Returns a list of {"message_type": ..., "name": ...} dictionaries, one per supported message type (e.g. acmt.001.001.08).

Return type:

list[dict]

acmt001_mcp.server.main(argv=None)[source]

Run the acmt001 MCP server (the acmt001-mcp entry point).

stdio by default; --transport streamable-http or --transport sse listens on --host/--port instead. See acmt001_mcp._cli.

Parameters:

argv (list[str] | None) – Command-line arguments; None reads sys.argv[1:].

Return type:

None

acmt001_mcp.server.message_types_resource()[source]

Expose the full acmt message type catalogue as a JSON resource.

This is the resource form of list_message_types: it returns the same [{"message_type": ..., "name": ...}, ...] catalogue, serialized as a JSON string for clients that consume resources rather than tool calls.

Return type:

str

Returns:

A JSON array string of {"message_type", "name"} objects.

acmt001_mcp.server.onboard_corporate_account(company_name='', country='')[source]

Guide an agent through onboarding a corporate account end to end.

Renders a step-by-step playbook naming the tools to call and their order: list_message_types to pick a message type, then get_required_fields / get_input_schema to learn the input record, then validate_records to check the batch, and finally generate_message to emit the validated acmt XML.

Parameters:

  • company_name (str) – The legal name of the company being onboarded.

  • country (str) – The ISO 3166-1 alpha-2 country code of the account owner.

Return type:

str

Returns:

A guidance string describing the recommended tool workflow.

acmt001_mcp.server.validate_identifier(kind, value)[source]

Validate a single financial identifier (IBAN, BIC, or LEI).

Use this for a one-off identifier check with a clear pass/fail. To validate identifiers embedded across a whole batch of account records, prefer validate_records rather than calling this per field.

Returns {"kind": str, "value": str, "valid": bool}.

Parameters:

  • kind (str) – One of "iban", "bic", or "lei" (case-insensitive).

  • value (str) – The identifier value to check.

Return type:

dict

acmt001_mcp.server.validate_records(message_type, records)[source]

Validate flat account records against a message type’s input JSON Schema.

Use this before generate_message to catch structural/type errors per record and get a row-by-row error report. This checks JSON-Schema shape only; to validate a single financial identifier in isolation use validate_identifier.

Returns a report {"valid": bool, "total": int, "valid_count": int, "errors": [...]}.

Parameters:

  • message_type (str) – A supported ISO 20022 acmt message type.

  • records (list[dict]) – One or more flat account records to validate.

Return type:

dict

acmt001_mcp.server.verify_lei_online(lei_code)[source]

Verify a LEI against the live GLEIF register (reaches the network).

Unlike validate_identifier, which checks an LEI’s format and check digits entirely offline, this tool performs a live HTTP GET against the public GLEIF REST API (api.gleif.org) to confirm the LEI is actually registered and to return the registered entity’s details. It therefore requires network access and is marked open-world.

Requires the optional online extra (pip install acmt001-mcp[online]) for the httpx HTTP client; without it a graceful {"error": ...} is returned rather than raising.

Returns a dict with the lei, registered legal_name, entity status, country, and registration registration_status, initial_registration_date, last_update_date and next_renewal_date. On failure returns {"error": ...}: an LEI not found error for an unregistered LEI (HTTP 404), or a GLEIF API unavailable error for any other non-200 response or a transport/connection error.

Parameters:

lei_code (str) – A 20-character ISO 17442 Legal Entity Identifier.

Return type:

dict

Transports and command line

One command line for the three MCP transports.

Every server in the suite is started the same way:

<server>                                   # stdio, for a client that spawns it
<server> --transport streamable-http       # HTTP on 127.0.0.1:8000, path /mcp
<server> --transport sse --port 8001       # the older HTTP+SSE transport

Over streamable HTTP the SDK speaks both current protocol revisions on one endpoint: 2026-07-28 (stateless, server/discover, per-request _meta) and 2025-11-25 (initialize handshake, Mcp-Session-Id). Responses stream as server-sent events; a GET on the same path opens the server-to-client event stream. --transport sse serves the 2024-11-05 HTTP+SSE transport for clients that still expect it.

The listener binds the loopback interface unless told otherwise. There is no authentication here: put the server behind a gateway you trust before binding a routable address.

This module holds the transport dispatch; the flags that drive it live in _cli. Both files are copied verbatim into every server of the suite and work on mcp 1.x and 2.x.

acmt001_mcp._transports.run(server, transport='stdio', host='127.0.0.1', port=8000)[source]

Serve server over transport; returns when the server stops.

Raises:

ValueError – If transport is not one of TRANSPORTS, or port is outside 1-65535.

Return type:

None

Parameters:

The command line every server in the suite shares.

serve is the body of each main(): it parses --transport, --host, --port and --version and hands the result to _transports.run(). Flag names, defaults and help text live here and nowhere else, so the suite is started and documented the same way.

Copied verbatim into every server of the suite.

acmt001_mcp._cli.add_arguments(parser)[source]

Add --transport, --host and --port to parser.

Return type:

None

Parameters:

parser (ArgumentParser)

acmt001_mcp._cli.serve(server, argv, prog, version)[source]

Parse argv and run server: the body of every main().

Return type:

None

Parameters: