A reference for agents using all 18 Habit Credit MCP tools. The connector endpoint is /mcp on this site. Sign in through OAuth with the same account as the web app. Treat tools retain the API name indulgence.
Success returns an MCP content array containing a text item whose text is JSON. The return fields below describe that decoded JSON. Errors return isError set to true and a JSON object with an error message. Invalid arguments can also produce MCP validation errors.
All tools except audit_ledger and send_feedback include structuredContent with view, changed and snapshot. Object results also merge the snapshot fields into their text JSON. Array results keep the array in text. get_ledger and all canvas tools also include the array as structuredContent.rows.
view is habits for setting, listing or deleting habits, treats for tools containing indulgence, logged for recording a habit or spend, and week otherwise. changed.tool names the tool. Changes may include entry_id for new entries, points, name for a habit or treat definition, and deleted set to true for deleted definitions.
If the action completes but its snapshot cannot be read, structuredContent.snapshot_error replaces snapshot. The original text result and any rows remain. Refresh with get_week_status. Do not repeat a completed write.
Reads that include accounting can close due weeks and create their charges. audit_ledger only reports mismatches and never repairs them. An audit mismatch blocks reconciliation. All tools operate on the signed in account.
Every write accepts an optional operation_id, a string of 1 to 128 characters. Supply a fresh ID for each action and reuse it with identical arguments on retries. Reusing it for different arguments fails. The server generates an ID if omitted. Every successful write returns operation_id and balance along with the fields listed below. A replay may return the original saved response and snapshot.
Names are strings of 1 to 200 characters. All point values must be finite. Habit rules and treat pricing rules are natural language for the agent to interpret, not formulas executed by the server. Read the definitions and history before deciding points. Check the balance before spending and let the user make the final decision.
log_habit and spend_credit accept optional occurred_at, at most 64 characters, as an ISO timestamp with a timezone or a calendar date in year month day format separated by hyphens. A date is interpreted at noon in the account time zone. Omission means now. Future calendar days are rejected.
Both accept optional context text up to 1000 characters, location text up to 200 characters, and travel as a boolean. Omit unknown values. Both also accept adjust, default false. Closed weeks require the user’s agreement and adjust set to true, which corrects the week charge together with the entry. delete_entry follows the same correction rule.
These shared return fields are available on every state tool. Amounts are numeric points. In conversation, lead with balance, the actual ledger total, then the weekly goal. A possible future charge is not debt.
balance and raw_balancein_debtprojected and spendable_balanceweek_close_deduction and charge_if_no_more_habitscarried_balancenet_spends_and_adjustmentsweekly_contributionshortfallshortfall_penaltyweek_end and timezoneEurope/Amsterdam.goaltarget, earned, remaining and days_left, plus boolean met. A zero target is met.weekweek_start, numeric earned, target, remaining, penalty_per_point and days_left_incl_today, plus mode and settlement_preview. The preview contains raw_balance, week_close_deduction, projected and a note. No active target produces zero target and charge, with mode none.Earned points count positive habit entries in the current week. In mode bonus, the charge is remaining points times the rate. Legacy mode obligation also absorbs earned points up to the target. Weeks begin Monday in the account time zone.
get_balanceGet the current balance, goal and possible week charge.
Inputs None.
Returns The shared snapshot plus next_week_goal, an object with the next Monday date starts, numeric target and penalty_per_point. An active current goal also adds a note describing the conditional charge.
get_week_statusGet progress toward this week’s goal.
Inputs None.
Returns The shared snapshot. With an active target, it also includes the fields of week at the top level. Without one, it adds a note saying there is no goal this week.
list_habitsList active habits alphabetically, excluding retired definitions.
Inputs None.
Returns An array of objects with name, numeric base_points, text rules, integer times_logged and numeric points_earned. Counts and totals cover the habit’s retained history. The snapshot is in structured content.
list_indulgencesList saved treats alphabetically.
Inputs None.
Returns An array of objects with name, numeric base_cost and text rules. The snapshot is in structured content.
get_ledgerRead individual entries in descending entry ID order, including week charges and corrections.
Inputs Optional integer limit from 1 to 200, default 20.
Returns An array in both text JSON and structuredContent.rows. Every row contains integer id, text description, numeric points, timestamps created_at and occurred_at, kind, settlement_id, habit, treat, context, location and travel. Kind is earn, treat, settlement or adjustment. Settlement ID is the related week date or null. Habit, treat, context and location are strings or null. Travel is a boolean or null. The snapshot is in structured content.
audit_ledgerReport recorded week charges that disagree with their ledger entries. Does not reconcile or repair anything.
Inputs None.
Returns An object with issues, an array containing week_start, numeric penalty, numeric ledger_charge and integer charge_entries. An empty array means no detected mismatches. No shared snapshot or structured content.
All write results include the shared receipt fields operation_id and balance. All except send_feedback also include the shared snapshot.
set_habitCreate or update a named habit. Reusing a retired name makes it active again.
Inputs Required name and numeric base_points from −100 to 100. Optional rules up to 2000 characters, default empty, and operation_id.
Returns habit containing the name, base_points and rules.
log_habitRecord an active habit using points chosen from its rules and history.
Inputs Required habit name and numeric points from −100 to 100. Optional note up to 500 characters, default empty, plus occurred_at, context, location, travel, adjust and operation_id. An empty note uses the habit name as the description.
Returns logged containing the habit name, signed points, normalized timestamp occurred_at, integer entry_id and integer times_logged after this entry.
delete_habitRetire an active habit while retaining its entries.
Inputs Required name. Optional operation_id.
Returns deleted containing the habit name. A missing or already retired habit fails.
set_indulgenceCreate or update a saved treat and its pricing rules.
Inputs Required name and numeric base_cost from 0 to 100. Optional rules up to 2000 characters, default empty, and operation_id.
Returns indulgence containing the name, base_cost and rules.
spend_creditRecord a treat as a nonpositive ledger entry, including when the user chooses to borrow.
Inputs Either a saved treat name as indulgence, or both description and points. Optional description has 1 to 500 characters. Optional numeric points from −100 to 100 overrides the saved cost and is converted to a negative absolute value. The combined saved name and description must fit 500 characters. Also accepts occurred_at, context, location, travel, adjust and operation_id.
Returns spent containing the stored description, signed points, normalized timestamp occurred_at and integer entry_id.
delete_indulgenceRemove a saved treat definition while retaining past spends.
Inputs Required name. Optional operation_id.
Returns deleted containing the treat name. A missing treat fails.
delete_entryRemove a mistaken habit or treat entry. Week charges and correction entries cannot be deleted.
Inputs Required positive safe integer entry_id. Optional adjust, default false, and operation_id. A closed week needs the correction agreement described above.
Returns deleted containing the numeric entry ID.
set_weekly_targetSchedule the goal and charge rate from next Monday. A zero target disables the goal from that week.
Inputs Required numeric points_per_week from 0 to 100. Optional numeric penalty_per_point from 0 to 100, default 1, mode as bonus or legacy obligation, default bonus, and operation_id.
Returns points_per_week, penalty_per_point, mode and the Monday date effective_from_week. The shared snapshot still describes the current week.
send_feedbackRecord a bug report, idea or confusing behavior for the developer.
Inputs Required text of 1 to 2000 characters. Optional source up to 200 characters, default chatgpt, and operation_id.
Returns recorded set to true, balance and operation_id. No shared snapshot or structured content.
These tools are available to the embedded app through MCP app visibility. Agents should use the corresponding read tools above. Each includes the shared structured snapshot and rows.
canvas_habitsLoad habits for the embedded canvas.
Inputs None.
Returns The same array fields and ordering as list_habits, in text JSON and structuredContent.rows.
canvas_treatsLoad treats for the embedded canvas.
Inputs None.
Returns The same array fields and ordering as list_indulgences, in text JSON and structuredContent.rows.
canvas_ledgerLoad recent entries for the embedded canvas.
Inputs Optional integer limit from 1 to 200, default 5.
Returns The same row fields and ordering as get_ledger, in text JSON and structuredContent.rows.