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.
The facts
- URL:
https://app.milyo.app/mcp - Transport: Streamable HTTP,
POSTonly, JSON answers. No sessions, no streams. - Protocol versions: 2026-07-28, 2025-11-25 and 2025-06-18.
- Auth: an organisation API key in
Authorization: Bearer milyo_sk_.... Cookies are never read. - Free on any plan:
parse_file,convert,reconcile. Up to 100,000 rows a file, 20 MB a file, card numbers masked, nothing stored, 100 calls a day. - Paid plans: every other tool. On the free plan they answer
plan_required.
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.
- A read key can call the read tools. A write key can call all of them.
- A key acts as a member of its organisation, never as an owner. It can't create, list or revoke keys, so those operations are not tools. Do that in the app.
- A key stops working when it is revoked, or when the person who made it leaves the organisation.
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.
| Plan | Tools | Notes |
|---|---|---|
| Free | parse_file, convert, reconcile | Work on files you send. Nothing is stored. Read keys are enough. |
| Paid | list_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, unmatch | Read 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.
| Code | What to do |
|---|---|
plan_required | The tool needs a paid plan. Tell the user. The message links the plans. |
quota_exceeded | The day's free calls, or the month's rows, are used up. The message says when they reset. |
forbidden | A read key tried a write tool, or the call was for another organisation. |
rate_limited | Too 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_file | Fix the input named in field and call again. |
file_too_large, run_too_large | Send 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
- /.well-known/mcp/server-card.json: the MCP server card, with the tool list. It is generated from the same registry as the server.
- /.well-known/ai-catalog.json: an AI Catalog entry for the server.
- /.well-known/api-catalog: an RFC 9727 API catalog.
- /.well-known/agent-skills/index.json: the open skills index.
- /llms.txt: what Milyo does, in plain text.
No key, or just want to look? The free matcher runs in your browser. Nothing is uploaded.
Match two files