Connector reference

What your assistant can do with Zeno

Zeno is a Model Context Protocol server at https://api.zenonest.com/mcp (streamable HTTP). It has35 tools: 16 read, 18 write and 1 sensitive write. None of them moves money.

Connecting

Endpoint: https://api.zenonest.com/mcp
Authentication: OAuth 2.1 with PKCE and dynamic client registration. The 401 response points to /.well-known/oauth-protected-resource, the issuer is https://app.zenonest.com, and a signed-in person approves each connection as full or view only. Access tokens last 14 days, and refresh tokens rotate on every use. Assistants that take an API key (Muse) use a personal token made at app.zenonest.com → Settings, sent as Authorization: Bearer zn_… or X-API-Key. Every connection is scoped to one household, stored only as a hash, and revocable in Settings with immediate effect.
Server instructions: on connecting, the server tells the assistant how to use it: numbers come from the tools, check with Zeno before a purchase, propose rather than assume, and the guide's rules and boundaries.
Errors: every tool returns {"ok": true, …} or {"ok": false, "error", "hint"}. The hint says how to recover, for example "List it first to get the id." A view-only token gets view_only on writes.

Classes

Read tools change nothing. A purchase check (ask_before) is a read, so an assistant can run it at checkout.
Write tools change the household's record: accounts, scheduled money, transactions brought in at your request, proposals, check-ins. What an assistant notices is saved as a proposal until you confirm it.
Sensitive write: changing the adopted Plan (amend_plan) requires a reason in your words and your explicit say-so, and assistants that support it ask you every time.

Tool	Class	What it does
`ask_before` Ask before spending amount, description, on?, account_id?, category?	Read	Check a purchase, booking, gift or other spend BEFORE it happens. amount is positive (what would be spent); on is the charge date (YYYY-MM-DD, default today); account_id defaults to the main checking account. Returns a verdict (clear, tight, short), the tightest day before and after, month-end, the Plan category's room this month, and, when timing is the problem, the same spend moved to just after the next paycheck. Changes nothing. Show the summary to the person before checkout; they decide. Then call log_decision with what they chose.
`find_recurring` Find paychecks and bills	Read	Paychecks and bills found in the imported transactions that aren't scheduled yet: name, typical amount (and how much it varies), how often, the next expected date, the account. For the person to confirm in one go; save each confirmed one with setup_scheduled.
`get_budget` The budget year?	Read	The budget they have (scheduled money plus spending history) beside the Plan they chose: monthly totals with what periodic costs ask to set aside, the year month by month (where December's costs land, which months run short), the category-by-category gap between Plan and spending, the debt plan's payment against the Plan's debt lines, and what to set aside monthly for life events in the next five years.
`get_debts` Debts and the way out monthly_payment?, custom_order?	Read	The balance sheet (assets, debts, net worth), and every payoff order compared at one total monthly payment: minimums only, avalanche (highest rate first), snowball (smallest first), and a custom order (debt account ids) if given. Each shows the debt-free month and total interest. With a saved debt plan, also runs it on today's balances and says how many months ahead or behind it is. Omit monthly_payment to use the saved plan's payment, or the minimums.
`get_forecast` Forecast mode?, days?	Read	Cash by account and date with an 80% range. mode='likely' uses what spending has actually been; mode='plan' uses the Plan's amounts. The two differ on purpose: the gap is the conversation. Returns weekly marks, each account's lowest point, the first day the range dips under the cushion, scheduled money in the next 30 days, and the assumptions behind the numbers. days: 7 to 180.
`get_guide` How to guide this conversation topic	Read	How to walk the person through one part of their money: when it fits, what to ask in order, which tool saves each answer, how to frame it and what to avoid. Read it before starting that conversation; get_path's guide_focus says which topics fit their stage.
`get_lifetime` The lifetime view years?	Read	Year by year from now: income (growing), spending (with inflation), debt payments until each debt is paid, life events, savings and net worth, with each person's age. Highlights: the debt-free year, the first year savings would run out, retirements, final net worth. Built from the Plan, or from the budget they have if there's no Plan yet.
`get_map` What Zeno knows status?	Read	The visible map of the household: financial facts, stated priorities, observed patterns, possible explanations, and experiments with outcomes, each with its source and whether the person agrees. 'current' = proposed + confirmed.
`get_money` Accounts and schedule transactions_days?	Read	Accounts with balances and freshness, every scheduled item (income, bills, debts, transfers, annual costs) with ids, and recent transactions.
`get_needs` The needs lens	Read	Money through the five levels of need (basic needs, security, belonging, esteem, growth): for each, planned and actual monthly spending as a share of income, the household's target if they set one, how satisfied they last said they feel (0-10), and the categories in it. Also the overall shape and where spending and satisfaction disagree, each put as a question to ask, not a verdict.
`get_path` My path	Read	The seven-stage path: every stage with its milestones (passed, current, ahead), the current stage's goal, checklist and next milestone, the conversations (get_guide topics) that fit it, first-setup progress, and every move along the path with its reason. see_it links the journey map.
`get_plan` The Plan	Read	The adopted Plan: monthly lines by category (fixed, flexible, annual, income), protected priorities, totals, and the amendment history with each reason.
`get_setup` First setup checklist	Read	The first-setup checklist: each step's state (open, done, skipped), what to ask for it, and the next open step. Before setup starts it also returns intro: what to tell the person first (what's about to happen, how long, what they'll get, what Zeno does and doesn't do). get_today carries a short form while setup is unfinished.
`get_today` Today	Read	The home screen: what's likely next (lowest point in 30 days, next income), what changed since the last check-in, which decision matters now (including things you proposed that wait for a yes or no), and the one thing the household agreed to work on. Also returns the household's ask threshold for ask_before. Start most conversations here.
`open_checkin` Open the weekly check-in	Read	Everything the five-minute weekly review needs: this week's spending by category against plan and likely, commitments under review, and the next two weeks of scheduled money.
`run_scenario` Explore a scenario changes, days?	Read	What happens if the household makes a change, without adopting it. changes is a list of: {"kind":"one_time","amount":-640,"on":"2026-11-14","name":"Trip"} {"kind":"recurring","amount":-45,"cadence":"monthly","on":"2026-11-01","name":"Gym"} {"kind":"category_rate","category":"Dining","monthly":300} {"kind":"stop_item","item_id":"...","on":"2026-12-01"} {"kind":"move_once","item_id":"...","on":"2026-11-03","to":"2026-11-17"} Spending is negative. Returns the likely forecast and the scenario side by side. The Plan is untouched; adopting a scenario is a separate amend_plan the person asks for.
`decide_map_entry` Confirm or reject a map entry entry_id, verdict, correction?	Write	Record the person's answer to a proposed entry. Only call this when the person has said so explicitly. correction rewords the statement before confirming ("it's Tuesdays, not Mondays"). Rejecting an explanation keeps the pattern it was explaining.
`delete_life_event` Remove a life event event_id	Write	Remove a life event the person no longer expects.
`import_transactions` Bring in bank transactions transactions	Write	Bring in transactions the person asked you to copy from their bank (for example from the bank connection they have in Muse). Up to 500 per call; send older history in more calls. Each row: {"account_id", "posted_on" (YYYY-MM-DD), "amount" (spending negative), "description", "category"?, "external_id"?}. Use the bank's own transaction id as external_id: rows already on file are skipped, so resending is safe. Skip pending transactions. Send only these fields, never account or routing numbers. Afterwards call set_balance with each account's current balance.
`log_decision` Log a decision question, choice, amount?, on?, note?, prediction_id?	Write	Record what the person chose after ask_before (pass its prediction_id), so the outcome can be compared with what was expected.
`mark_milestone` Mark a milestone key, done?	Write	Tick (or untick) a milestone on the current stage's checklist (keys from get_path).
`propose_observation` Propose something noticed kind, statement, evidence?, amount?, on?, cadence?, account_id?	Write	Add something you noticed to the household's map as PROPOSED, naming you as the source. The person confirms or rejects it; nothing counts until they do. For a money fact give amount (spending negative, income positive), on (YYYY-MM-DD) and cadence: once confirmed it becomes scheduled money in the forecast. Example: kind='fact', statement='Car insurance renews', evidence='Renewal email from Geico, Oct 9', amount=-612, on='2026-11-14', cadence='yearly'. Send only what this entry needs; never paste whole emails.
`rate_needs` Record how each need feels ratings, note?	Write	How satisfied the person feels at each level right now, 0 to 10, in their own judgment (one or more levels). Kept over time, so a later rating can be compared. Ask; never infer it.
`record_checkin` Save the weekly check-in happened, went_well?, explanation?, verdict?, commitment_id?, outcome?, new_commitment?	Write	Save the review the person just did with you. verdict/outcome close out the commitment under review (commitment_id from open_checkin). new_commitment is {"action", "obstacle", "backup", "owner"?, "review_on"? (YYYY-MM-DD, default a week)}.
`record_transaction` Record a transaction account_id, amount, description, on?, category?, scheduled_item_id?	Write	Record money that moved, e.g. a purchase you just completed for the person. Spending is negative. Pass scheduled_item_id when this pays a scheduled bill so it isn't expected twice.
`set_balance` Update a balance account_id, balance, as_of?	Write	Set an account's actual balance as the person reports it (credit cards and loans are negative). Fresh balances narrow the forecast's range.
`set_debt_plan` Save the debt plan strategy, monthly_payment, reason, custom_order?	Write	Save the order and total monthly payment the person chose, with their reason, as the baseline later runs are measured against. Only after they choose. It moves no money and changes no Plan line; offer amend_plan for that.
`set_life_event` Add or edit a life event name, kind, year, amount, month?, years?, inflate?, person?, note?, event_id?	Write	A big thing ahead, in today's dollars. cost: money out that year, repeated for `years` (tuition: years=4). income: money in that year. income_change / expense_change: monthly income or spending changes by amount from that year on (retirement: income_change of -3200; mortgage paid off: expense_change of -1850). Only things the person told you or confirmed.
`set_lifetime` Set up the lifetime view people?, income_growth?, inflation?, savings_return?, years?	Write	people: [{"name", "birth_year"?, "retire_age"?}] for everyone in the household (replaces the list). Assumptions are yearly percentages (defaults: income growth 3, inflation 2.5, savings return 4); change them only when the person wants to. years is how far to look (max 60).
`set_needs` Set needs targets or move a category preset?, targets?, category_levels?	Write	Targets are shares of take-home income per level, adding up to 100; a preset is a starting shape to react to, not a prescription. Set them only when the person chooses to. category_levels moves a category to another level ({"Phone": "physiological"}); null puts it back to the automatic level.
`set_stage` Set the stage on the path number, reason	Write	Place the household on the seven-stage path (1 Steady the ground ... 7 Flourish), with the reason in the person's words. Only with their agreement. Moving back is normal, never failure. Resets the stage's checklist.
`setup_account` Add or edit an account name, kind?, balance?, spendable?, cushion?, apr?, minimum_payment?, note?, account_id?	Write	Create an account, or edit one by account_id. Debts are credit or loan accounts with a negative balance (what's owed), apr (yearly %) and minimum_payment; an informal loan from family is a loan with apr 0 and a note ("from Mom, no fixed terms"). investment, retirement and property count toward net worth and are kept out of spending. spendable=false keeps savings (an emergency fund) out of everyday spending. cushion is the floor the person wants to stay above.
`setup_scheduled` Add or edit scheduled money account_id, name, amount, cadence, first_date, kind?, certainty?, category?, to_account_id?, ends_on?, item_id?	Write	Paychecks, bills, debt payments, transfers and annual costs with a date. Income positive, bills negative. A card payment is kind='transfer' from checking with to_account_id = the card. certainty='likely' for money that isn't promised (overtime, a bonus); the low edge of the range leaves it out. Use only for things the person told you; for things you noticed, use propose_observation.
`update_setup` Update the setup checklist step, done?, skipped?, note?	Write	Mark a first-setup step done when the person says that's everything for it, or skipped (with a short note: "no debts", "no income right now"). step='rest' is for when they want to stop the questions and get going: every open step is skipped and, if no starting point was chosen, they start at stage 2. For 'household', note who shares the money in a sentence.
`amend_plan` Amend the Plan reason, set_lines?, remove_categories?, priorities?	Sensitive Write	Adopt a new version of the household's Plan. Only when the person explicitly asks to change the Plan, never to make the Plan match spending. reason is required, in their words ("We postponed the car because three months of reserve matters more right now"). set_lines adds or replaces lines by category, e.g. {"category":"Dining","kind":"flexible","amount":350} (monthly), {"category":"Pay","kind":"income", "amount":2400,"cadence":"biweekly"}, {"category":"Holidays","kind":"periodic","amount":1200, "cadence":"yearly","months":[12]}, {"category":"Car registration","kind":"periodic","amount":180, "cadence":"yearly","months":[3]}. kind: income \| fixed \| flexible \| periodic \| debt \| saving; cadence: weekly \| biweekly \| semimonthly \| monthly \| quarterly \| semiannual \| yearly \| once (with once_on). Optional level (physiological, safety, belonging, esteem, growth) and protected. Amounts are positive. The old version stays in the history.