Orchune personal finance

Orchune is a personal finance service operated entirely over MCP. Endpoint: https://www.orchune.com/mcp (Streamable HTTP, stateless JSON). Every request needs Authorization: Bearer <token> — except the signup/login flow below.

Connect and authenticate

Send an access token as Authorization: Bearer <token> on every request for the full toolset. First-time setup, no token configured, or a 401 with a token you thought was valid → read references/setup.md — it walks through registering the MCP server, the passwordless email-code signup/login flow, token storage rules, and troubleshooting.

Always-on auth facts:

• One token per user. Minting a new token (email flow or web Settings) revokes the previous one everywhere; complete_email_verification reports this via replacedExistingToken — warn the user if they run agents elsewhere.
• Store the token in the ORCHUNE_ACCESS_TOKEN environment variable (or the client's MCP config), never in conversation text or tool arguments. After adding or changing it, have the user restart/refresh the MCP connection — header changes rarely apply live.
• A 401 means your token is dead — never retry it unchanged.
• Rate limits: ~60 requests/minute authenticated, ~10/minute anonymous. On 429, respect Retry-After.

Money, dates, and name resolution

These conventions apply to every tool; getting them wrong is the main failure mode.

• Inputs are major units, outputs are minor-unit strings. Send amount: 12.34. Read money back as { amountMinor: "1234", digits: 2, code: "CNY" } → major = amountMinor / 10^digits. Never do float math on amountMinor; it is a string on purpose.
• Amounts are always positive; direction comes from the tool or type/action field, never the sign. Exceptions: record_fund_return.amount may be negative (loss day) and create_account.openingBalance may be negative.
• Each account has a fixed currency; a transaction's currency is its account's. Cross-currency transfers are rejected — tell the user to use the web app.
• Dates: pass a local date or datetime (2026-06-10 or 2026-06-10T14:30). Without a UTC offset it is interpreted in the request's timezone (default: the user's configured timezone from get_my_profile). list_transactions endDate is inclusive and defaults to the current month.
• Accounts and categories accept a name or a UUID. Names match case-insensitively, exact first, then substring. On *_AMBIGUOUS errors, retry with the id from the corresponding list tool. Categories are scoped by type (EXPENSE | INCOME).
• Payees auto-create. Before passing a payee, call search_payees and reuse the returned full name to avoid near-duplicate merchants.
• Credit cards: on CREDIT_CARD accounts an optional card field (id, label, or last-4) picks the card; default is the primary card. Passing card on any other account type is an error.

Common workflows

Record a transaction (expense / income / transfer):

1. list_accounts once per session to resolve the account (cache the names).
2. Optionally get_category_list(type) and search_payees(query).
3. record_expense / record_income / record_transfer. Default status CLEARED is right for completed transactions.

Import a bank/payment statement: you parse the file (CSV, PDF, screenshot) into rows yourself; the server validates and imports them in two steps (preview_bill_import → fix INVALID rows → commit_bill_import). Read references/bill-import.md before your first import — it has the row schema, dedup rules, and the validation loop.

Investments: open_*_position only for a brand-new holding (it fails if one exists); otherwise record_*_trade against the existing position, resolved by symbol/code or positionId via the matching list_*_positions tool. For money-market fund earnings use record_fund_return, not record_fund_trade with INCOME.

Reports: list_transactions returns totals (income/expense/count) alongside rows — prefer its filters over fetching everything and summing yourself. list_budgets and list_goals return per-line progress ready to present.

For exact parameters of any tool, read references/tools.md.

Gotchas

• delete_transaction on a transfer leg deletes both legs. update_transaction cannot edit transfers at all — send the user to the web app.
• merge_categories cannot be undone automatically; confirm with the user before calling it. delete_category only archives (existing transactions keep the reference); recreating the same name reactivates it.
• System (default) categories cannot be renamed, deleted, or merged away (CATEGORY_SYSTEM_PROTECTED).
• record_fund_return upserts by date — re-recording the same day overwrites it (safe for corrections). delete_fund_return accepts YYYY-MM-DD, YYYY-MM, or YYYY ranges for cleanup.
• Committed import batches can only be reverted by the user from the web app's import history — there is no revert tool. Say so when reporting an import.
• Account type, currency, and balances cannot be changed after creation via MCP; update_account only covers name/provider/notes/archive.
• Changing the user's timezone via update_my_settings triggers a recalculation of monthly statistics — expect brief inconsistency right after.
• Errors come back as isError results with a leading code (e.g. ACCOUNT_AMBIGUOUS: ...). The message usually tells you the fix (use an id, list available names); read it before retrying.