---
name: milyo-reconcile
description: Reconcile two files of transactions (a ledger and a bank statement, say) and convert CAMT.053 or MT940 bank files to CSV, using Milyo's hosted MCP server. Use when a person has two transaction files to compare, or a bank statement file to turn into CSV. The three tools involved work on the free plan but need an API key.
---

# Reconcile two transaction files with Milyo

Milyo's MCP server matches two files of transactions and returns four groups: matched, exceptions (each with a reason), only in A, and only in B. Three tools work on the free plan. They read the files you send, keep nothing, and need an API key.

## When to use it

- A person has two files to compare: a ledger export against a bank statement, or a payment processor's payout report against a bank statement.
- A person has a CAMT.053 or MT940 bank statement and wants a CSV.

## When something else fits

- The person has no API key and only wants to try it: the free matcher at https://try.milyo.app/ runs in the browser, needs no account, and uploads nothing.
- The files are small and the person is happy in a spreadsheet: a spreadsheet works. https://milyo.app/compare/ says where each option is better.
- One payout against many charges (1:N): the free `reconcile` tool matches one row to one row only.

## Connect

Get a key: sign in at https://app.milyo.app, open Settings, then API keys. The key looks like `milyo_sk_...` and is shown once. The paid app is in private beta, so the person may need to ask for access first. Do not ask them to paste the key into chat. Put it in an environment variable.

Claude Code:

```sh
claude mcp add --transport http milyo https://app.milyo.app/mcp \
  --header "Authorization: Bearer $MILYO_API_KEY"
```

Cursor, in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "milyo": {
      "url": "https://app.milyo.app/mcp",
      "headers": { "Authorization": "Bearer ${env:MILYO_API_KEY}" }
    }
  }
}
```

The server speaks Streamable HTTP, takes `POST` only, and reads the Bearer key, never cookies. Full docs: https://milyo.app/docs/mcp/

## The free tools, in order

Each file goes in as `content_base64`: standard base64 of the file's bytes, up to 20 MB. A file may have up to 100,000 rows. Card numbers are masked in what comes back.

1. `parse_file`, once per file. Send `name` and `content_base64`. It returns `kind` (csv, xlsx, camt053 or mt940), `header`, a `preview` of the first rows, `row_count`, and a suggested `mapping` from columns to fields (date, amount, reference and so on).
2. Check each suggested mapping against its preview and fix what is wrong: `currency` when the file has no currency column, `date_format`, `decimal_comma`, `negate` for a file that records amounts from the other party's side. Do not guess a column. If the preview is unclear, ask the person.
3. `reconcile`. Send `a` and `b` (each with `name`, `content_base64` and its `mapping`) and `passes`. A usual start:

```json
[
  { "name": "key", "kind": "key", "on": [{ "a": "reference", "b": "reference" }],
    "amount_tolerance_minor": 0, "date_window_days": 3 },
  { "name": "fallback", "kind": "fallback", "on": [],
    "amount_tolerance_minor": 0, "date_window_days": 3 }
]
```

The key pass matches rows with equal references whose amount and date fit. The fallback pass matches what is left, one to one, on amount and date. Amounts are whole minor units (cents): a tolerance of 5 is 0.05 in a 2-decimal currency.

To convert a bank file instead, call `convert` with `name` and `content_base64`. It returns `kind`, `row_count` and `csv`, one row per entry, every row as it is in the file.

## Reading the result

`reconcile` returns:

- `counts`: `matched`, `exceptions`, `only_in_a`, `only_in_b`.
- `matches`: each names the pass that made it.
- `exceptions`: each has a `reason`, the row ids on both sides (`a` and `b`), the `currency` and `diff_minor`, the amount difference in minor units. `exponents` gives each currency's decimal places.
- `files`: per file, the `rows` read, `set_aside` (rows that could not be read) and `skipped`.

The reasons:

- `ambiguous`: more than one row could fit. Milyo flags it and does not pick one. Show it to the person to decide.
- `amount_mismatch`: one row on each side shares a key, but the amounts differ.
- `date_out_of_window`: the same, but the dates are too far apart.
- `only_in_a` and `only_in_b`: no row on the other side fits.

Report the counts first, then the exceptions with their reasons. Do not present an exception as a match, and do not leave one out of the summary. If `set_aside` is above zero, say so: those rows were not compared.

## Errors

A failure has `isError: true` and an `error` with `code`, `message` and `field`. Switch on `code`. The `message` says what to do next.

- `quota_exceeded`: a free org has 100 calls a day, MCP and HTTP together. The message says when it resets (00:00 UTC).
- `plan_required`: the tool needs a paid plan. Tell the person.
- `invalid_mapping`, `invalid_rules`, `invalid_request`, `bad_file`: fix the input named in `field`.
- `file_too_large`, `run_too_large`: send a smaller file.
- A missing, unknown or revoked key gets HTTP 401. The person needs a new key.

## What the paid plan adds

The other tools store data: sources, versioned mappings, uploaded files, saved rule sets, runs with history, and exceptions to work through. They answer `plan_required` on the free plan. The list is in https://milyo.app/docs/mcp/ and prices are at https://milyo.app/#pricing. The free tools above do not need any of it.
