MCP tool reference

Look up MCP tools and their main parameters when writing calls or troubleshooting an assistant’s actions.

The Calends MCP server provides 27 tools: 14 read tools and 13 write tools. Read-only tokens can only see and call the read tools. For setup, see MCP access.

Conventions

• Dates are always YYYY-MM-DD strings.
• subscription is a subscription id or its name (fuzzy match); if several match, candidates are returned so the assistant can retry with an id.
• method is a payment method id or name.
• currency_out converts amounts into that currency; defaults to the base currency.
• period: today, next_3_days, next_7_days, next_30_days, this_month, next_month, last_30_days, this_year, or custom (requires from and to).
• cycle is a billing cycle such as {"unit":"month","every":1}; unit is day, week, month, year or lifetime (one-time purchase).
• scope: mine excludes paid-for-others and counts only your share of shared plans; gross is the full card amount including paid-for-others; proxy is paid-for-others only.
• dry_run: supported by every write tool. true returns a preview without saving; otherwise the change is saved and the updated subscription plus its next few charges are returned.
• Problems such as bad arguments or an unknown subscription come back as a tool result (isError), so the assistant can see why and fix it.

Read tools

Tool	Purpose	Main parameters
get_overview	Ledger snapshot: today, base currency, monthly cost (excluding paid-for-others, only your share of shared plans), active count, payment methods (with ids), categories and regions in use, top checkup items. Call this first.	currency_out
list_categories	Categories in display order: name, icon, color, built-in code, and how many subscriptions use each (total / live).	none
list_subscriptions	Subscriptions with status, current price, monthly cost, next and last charge, payment method and region.	query (fuzzy on name, tags, notes, category), status (active, trial, paused, ending, ended, upcoming, lifetime, live, all; live = active + trial + ending + paused), kind (mine, share_owner, share_member, proxy, all), category, method, region, sort (next_charge, monthly_cost, name, start), limit (default 100)
get_subscription	Everything about one subscription: every phase (region or plan switches, lapses), price history, intro and free periods, recent and upcoming charges, shared plan member dues, paid-for repayments, total spent.	subscription (required), months_back (default 12), months_forward (default 6), currency_out
list_charges	Charges (actual and projected) in a period.	period (default next_30_days), from, to, scope (default mine), subscription, method, include_projected (default true), currency_out
spending_stats	Spending grouped by month, year, category, payment method, currency, region or subscription. Cash basis: each past charge at its own day’s rate.	period (default this_year), from, to, group_by (default category), scope, include_projected, top (default 30), currency_out
get_trends	Time series: monthly MRR history, cash vs. accrual by month, or MRR movement between two dates (new, expansion, contraction, churn, FX effect).	metric (mrr, cash_vs_accrual, movement), months_back (default 12), months_forward (default 3, cash_vs_accrual only), from, to (movement only)
list_payment_methods	Payment methods with estimated balance, monthly drain, runway (how long it lasts, first shortfall) and a top-up suggestion.	topup_months (default 6)
list_people	The people list: contact, which shared plans and paid-for subscriptions they’re in, what they owe now, what they’ve paid so far, and their last payment.	query, owing_only
get_receivables	Money owed to you: totals per person, shared plan members due or overdue, and paid-for charges not yet repaid.	kind (share, proxy, all), currency_out
get_insights	Checkup and reports.	section (insights, year_review, prepaid, cancel_savings), year (year_review only)
list_events	Changelog of spending decisions: started, ended, paused, resumed, price changes, plan and region switches, each with its effect on monthly cost.	since, until, subscription, limit (default 50)
search_app_store	Look up an app by name or App Store link: name, icon URL, store URL, seller and genre. Used to fill in icons and URLs for new subscriptions.	query (required), country (two-letter store region, default us)
get_carpool	Shared plans: for each plan you host or joined, seats (taken / total / free), members’ fees, paid-through dates and amounts owed; per year the cost, members’ expected payments, and what you still pay or earn; since the start, paid, received and the result.	subscription (optional, just this plan)

Write tools

Tool	Purpose	Main parameters
create_subscription	Create a subscription; price is per period. Refuses a duplicate (same name and start date) unless force=true.	name, price, currency, cycle (required), start (default today), category (reuse a name from list_categories; a new name creates a category), tags, method, region, url, icon, notes, account, status (active or trial), trial_end, end, intro ({price, until}), force
update_subscription	Change descriptive fields and settings; only the keys you pass change. Use change_price for price changes and change_plan for plan or region switches.	subscription, set: name, category, tags, url, manage_url, notes, account, method, region, remind_days (-1 = no reminder), end (null clears it), next_due, trial_end, expires
change_price	Record a price change in the current plan from a date; earlier charges keep the old price.	subscription, amount, from (default today)
change_plan	Start a new phase of the same subscription.	subscription, action, at, plan (price, currency, cycle required; optional method, region, note, planned), keep_previous_until, earlier_until
set_status	Pause (stop projecting charges), cancel (no renewal from a date) or reactivate (clear pause and end date).	subscription, action (pause, cancel, reactivate), at (default today; for cancel, the last day / no renewal from this date)
record_payment	Record an actual charge, refund (positive amount, stored negative), adjustment or failed charge in the subscription’s currency. Same-day, same-amount duplicates are refused unless allow_duplicate.	subscription, amount (required), date (default today), kind (charge, refund, adjust, failed), settled ({amount, currency} actually charged to the card), note, allow_duplicate, phase (start date of the phase, when two overlap)
delete_payment	Delete one recorded charge by date.	subscription, date, index (0-based, when there are several that day), phase
delete_subscription	Delete a subscription and its whole history. Irreversible; the assistant should preview with dry_run and let you confirm.	subscription
set_share	Make a subscription shared or change its sharing.	subscription, role (owner = I host, member = I joined, none = stop sharing), seats (total, including you), owner_name (host, for member), since (start date)
save_share_member	Add a member to a plan you host, or update one (pass member).	subscription, member, name, fee (amount per payment), fee_currency (defaults to the shared plan currency), bill_every (1, 3, 6, 12 months), exempt (doesn’t pay), paid_until, joined, left, contact_via, contact, account, note
remove_share_member	Remove a member completely, payment history included. To keep history, set left with save_share_member instead.	subscription, member
record_receivable	Record money received: a shared plan member paid (kind=share; paid-through advances by their billing period unless until is given), or a paid-for charge was repaid (kind=proxy; charge is that charge’s date, the oldest unpaid by default). Pass person alone to pick that person’s single open item.	subscription, person, kind, member, charge, amount, currency (defaults to the shared plan currency), date (received, default today), until, note
update_payment_method	Update a payment method: set the current balance, record a top-up (optionally with what it actually cost in another currency, e.g. a gift card bought with CNY), or change its name or region.	method (required), balance, top_up ({amount, date, cost, cost_currency, note}), name, region

change_plan actions

action	What it does
switch	Switch region, plan, currency or payment method from at. Seamless by default; with keep_previous_until, the previous phase keeps running until that date, overlapping and billing as usual (a new Turkish account while the prepaid US one runs out). plan.planned=true marks it as only planned.
resume	Resubscribe at at after a gap; the gap is recorded as a lapse.
earlier	Add history before the subscription’s start (a one-time purchase before it became a subscription); at is when that phase began. It runs until the original first phase by default, or until earlier_until, leaving a lapse in between.
confirm	Confirm a planned phase; at is its start date.
drop	Drop a planned phase; the previous phase ends on the planned switch date.

Cancelling (set_status with cancel) also drops phases scheduled after the cancel date, including planned switches.

Example

For “Netflix went up to $17.99 from today”, the assistant calls something like:

{ "name": "change_price", "arguments": { "subscription": "Netflix", "amount": 17.99, "dry_run": true } }

Once the preview looks right, it calls it again without dry_run.