Iso20022 Navigator MCP Server

ISO 20022 Navigator MCP server

An MCP server that gives AI assistants grounded answers about ISO 20022 financial messaging, from the reference data behind the ISO 20022 Navigator.

Free and public. The endpoint URL is all a client needs.

Endpoint: https://mcp.isonavigator.io/iso20022 (Streamable HTTP, open access)

Documentation · Privacy · Support: i22navigatorapp@gmail.com

Tools

All tools are read-only.

iso20022_bank_transaction_codes

• Answers: what an ISO 20022 Bank Transaction Code means: the domain, family and subfamily codes that classify entries in bank statements and account reports, for example PMNT-RCDT-ESCT. It also shows which families sit under a domain, which subfamilies under a family, and where a code appears.
• Input: code, written domain-family-subfamily with hyphens. Any part can stand alone or be skipped:
  • PMNT: a domain, with its families.
  • PMNT-RCDT: a domain and family, with the subfamilies.
  • PMNT-RCDT-ESCT: a full code, with the three names and a description.
  • /RCDT and //ESCT: a family or a subfamily on its own (the leading slashes fix the level).
  • /RCDT/ESCT and PMNT//ESCT: two parts with one level skipped.
  • ESCT: no level given; every level where the code exists is returned.
• Returns: official names, counts, lists of the related codes, a description when one combination matches, notes and a provenance block. A code that is not found says where each part exists and lists the closest existing codes.
• Example questions:
  • What does bank transaction code PMNT-RCDT-ESCT mean?
  • Which families does the PMNT domain contain?
  • Which domains use the family RCDT?
  • Is OTHR a family or a subfamily?
• Notes:
  • Covers the ISO external code list. Bank-specific (proprietary) codes are outside it, so a code that is not found may be one of those.
  • Codes are matched, not meanings. To find a code for a type of transaction, browse from the domain down.
  • Combination descriptions are AI-generated and validated against the official ISO definitions.

iso20022_legacy_and_scheme_mappings

• Answers: which ISO 20022 message replaces a legacy message (SWIFT MT, NACHA, CHAPS legacy), for example MT103 → pacs.008, and which payment schemes use an ISO 20022 message.
• Inputs: message (a legacy or ISO 20022 message, such as MT103, 940 or pacs.008) and an optional standard (narrows the answer to one standard or scheme, such as SEPA).
• Returns: message-level mappings with status, scheme usage, notes and a provenance block.
• Example questions:
  • What replaced MT103?
  • What is the ISO 20022 equivalent of MT940?
  • Which payment schemes use pacs.008?
  • Is tsin.004 still current?
• Notes:
  • Latest message version only. A version in the input (for example pacs.008.001.08) maps to its message (pacs.008).
  • Retired messages are returned with the data load in which they were retired.
  • Responses list what the Navigator has recorded. When a mapping is missing, the response says so and directs assistants to answer from the recorded data.

Getting the assistant to use it

Some assistants answer from general knowledge unless asked to use a tool, a choice made by the assistant. Adding the following line to a Project's instructions helps the assistant use the tools where they apply:

For any question about ISO 20022 bank transaction codes, messages, their legacy equivalents (SWIFT MT, NACHA) or which payment schemes use a message, call the ISO Navigator connector first and answer from its data.

Other assistants may behave differently. If an answer comes without a tool call, ask again with "according to the ISO Navigator".

Usage limits

• Shared rate limit. The limit is 600 calls per minute across all users together. When it is reached, the response says how long to wait before retrying.
• Request size. Requests up to 64 KB are accepted, and the server handles up to 20 requests at the same time.

Data

Every response carries a provenance block. Its data_baseline (for example 4Q2025) is the quarter of the Navigator's baseline data load, which marks when the data was added to the Navigator and differs from any ISO 20022 publication date. Check the scheme's or SWIFT's own current documentation before relying on a migration date.

Some explanations are AI-generated. Verify against official ISO 20022 and scheme documentation before use in production.

Connect

Use the endpoint URL above. Menu names change between releases; if a label below differs from what you see, the client's own MCP documentation is the reference.

Claude (web and desktop app)

1. Open Customize → Connectors, choose + Add → Add custom connector.
2. Enter a name (for example ISO 20022 Navigator) and the endpoint URL. Leave authentication off.
3. In a chat, use the + button at the lower left, then Connectors, and switch the connector on.

On Team and Enterprise plans an owner first adds it under Organization settings → Connectors → Add → Custom → Web; members then connect it from Customize → Connectors. The Free plan allows one custom connector. See Anthropic's guide.

Claude Code

claude mcp add --transport http iso20022 https://mcp.isonavigator.io/iso20022

Check it with claude mcp list, or /mcp inside Claude Code. Add --scope user to make it available in every project.

VS Code with GitHub Copilot

1. Run MCP: Open User Configuration from the Command Palette (or create .vscode/mcp.json in a project).

2. Add:

   {
     "servers": {
       "iso20022": {
         "type": "http",
         "url": "https://mcp.isonavigator.io/iso20022"
       }
     }
   }
   

3. Run MCP: List Servers, select iso20022 and start (or restart) it.

4. Use Copilot Chat in Agent mode; the tools appear in the tools list.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "iso20022": {
      "url": "https://mcp.isonavigator.io/iso20022"
    }
  }
}

Tools can be switched on and off from the chat's tools list.

ChatGPT

Custom MCP connectors need developer mode and are available on the web. Availability depends on your plan; see OpenAI's guide. In short: turn on developer mode under Settings → Apps → Advanced settings, choose Create, enter the endpoint URL and leave authentication off, select Scan Tools, then Create. This server reads data, so read-only access is enough.

Any other MCP client

Any client that supports remote MCP servers over Streamable HTTP can use the endpoint URL. A database-independent health check is at https://mcp.isonavigator.io/iso20022/health.

Run locally

Requires Python 3.14 and access to the Navigator database (private).

python -m venv .venv
.venv\Scripts\activate            # Windows; on macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

Put the connection string in a .env file as DATABASE_URL=..., then either:

• python server.py — stdio transport, for Claude Desktop or MCP Inspector
• set MCP_TRANSPORT=http, then python server.py — HTTP transport as deployed, at http://localhost:8000/iso20022 (health check: /iso20022/health)

See the top of server.py for the other settings.

Tests

pip install -r requirements-dev.txt
bandit -q -r . -x ./tests,./.venv
python -m pytest -q

Database tests run when DATABASE_URL is available.

License

The code is under the MIT License. The reference data served by the tools sits outside this repository and its license.