For agents

Milyo MCP server and API for AI agents

An agent can reconcile two files of transactions through Milyo's MCP server at https://app.milyo.app/mcp. It needs an API key. Three tools work on any plan: parse_file, convert and reconcile. They read the files you send and store nothing. The other tools work with an organisation's stored data and need a paid plan.

Published 2026-11-19. The paid app is in private beta, so you may need to ask for access before you can create a key: hello@milyo.app.

The facts

Get a key

An owner of the organisation signs in to the app, opens Settings, then API keys, and creates a key. The key is shown once.

Connect

Claude Code

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

Or share it in a project's .mcp.json, with the key in the environment:

{
  "mcpServers": {
    "milyo": {
      "type": "http",
      "url": "https://app.milyo.app/mcp",
      "headers": { "Authorization": "Bearer ${MILYO_API_KEY}" }
    }
  }
}

Cursor

In ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

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

Keep the key out of files you commit. Both clients read it from the environment.

Reconcile two files

Call parse_file for each file. It returns the file's format, its header, the first rows and a suggested mapping from columns to fields. Then call reconcile with the mapping each one suggests and the passes you want. The result has four groups: matched, exceptions with the reason for each, only in A and only in B. If more than one row could fit, the rows are an exception. Milyo never picks one. To turn a CAMT.053 or MT940 file into CSV, call convert.

Tools that take a file (parse_file, convert, reconcile, upload_file) take it as content_base64: standard base64 of the file's bytes, up to 20 MB decoded per file.

An open skill walks an agent through this: milyo-reconcile. It is plain markdown. You can read it before you use it.

Tools

tools/list is the source of truth. Every operation of the API is a tool of the same name, with the same input schema and the same error codes.

PlanToolsNotes
Freeparse_file, convert, reconcileWork on files you send. Nothing is stored. Read keys are enough.
Paidlist_sources, create_source, get_mapping, preview_mapping, save_mapping, upload_file, list_uploads, download_set_aside, create_rule_set, list_rule_sets, get_rule_set, dry_run, save_rules, start_run, list_runs, get_run, list_exceptions, get_exception, resolve_exception, match_rows, unmatchRead and write the organisation's stored data. Write tools need a write key.

Free versus paid. The free tools are the free matcher as an API: key and fallback passes only, card numbers masked. A free organisation may make 100 calls a day in total, over MCP and HTTP together. Call 101 gets quota_exceeded and the reset time (00:00 UTC). A paid organisation has no daily limit. upload_file counts against its monthly rows, and an upload over the quota adds nothing. Prices are on the pricing section.

Retries. Tools that write take an optional idempotency_key. Send a fresh one, and reuse it when you retry: a repeat replays the first answer instead of acting twice.

HTTP API

The same operations are on plain HTTP, with the same keys and the same error JSON. Each tool is one operation under https://app.milyo.app/api/v1/orgs/{org}/. parse_file is POST .../parse, convert is POST .../convert and reconcile is POST .../reconcile, each with a JSON body. Send Authorization: Bearer milyo_sk_.... An OpenAPI document is planned, not built.

Results and errors

A success has structuredContent (the API's JSON) and the same JSON as text. A failure has isError: true, and structuredContent is the API's error:

{ "error": { "code": "plan_required", "message": "Stored data needs a paid plan: ...", "field": null } }

code is stable, so switch on it. message says what to do next. field names the input at fault. The result's _meta["app.milyo/requestId"] is the id to quote in a support request.

CodeWhat to do
plan_requiredThe tool needs a paid plan. Tell the user. The message links the plans.
quota_exceededThe day's free calls, or the month's rows, are used up. The message says when they reset.
forbiddenA read key tried a write tool, or the call was for another organisation.
rate_limitedToo many calls: 5 a second a key, and one engine run at a time per organisation. Retry after a moment.
invalid_request, invalid_mapping, invalid_rules, bad_fileFix the input named in field and call again.
file_too_large, run_too_largeSend a smaller file, or use a paid plan for more rows.

A key that is missing, unknown or revoked is refused at the HTTP level: 401 with WWW-Authenticate: Bearer. For key_revoked, stop retrying and ask for a new key.

Discovery files

No key, or just want to look? The free matcher runs in your browser. Nothing is uploaded.

Match two files