CTDS Cash Flow Positive

The arithmetic behind Cash Flow Positive, offered to AI assistants as 5 tools over the Model Context Protocol.

The Cash Flow Positive forecast engine: daily balance projections, low-balance and card near-limit alerts, the public overdraft check, recurrence dates, recurring-payment detection and bill templates. Money is integer cents, signed (positive in, negative out; a credit card balance owed is negative); dates are YYYY-MM-DD; a tool that takes today defaults to the current UTC date, so pass it to pin a run. Results are projections from the balances and rules given, not bank data or financial advice; say so. The server has none of the user's saved accounts or rules.

Connect

The server is at https://cashflow.chimneytopdigital.com/api/mcp. It is free, asks for no sign-in and keeps nothing between calls. Rate limits apply per address.

Client	How
Claude Code	One command in a terminal: `claude mcp add --transport http ctds-cashflow-planner https://cashflow.chimneytopdigital.com/api/mcp`
Claude (web and desktop apps)	Settings → Connectors → Add custom connector, with the URL https://cashflow.chimneytopdigital.com/api/mcp. No sign-in is asked for.
Codex CLI	One command in a terminal: `codex mcp add ctds-cashflow-planner --url https://cashflow.chimneytopdigital.com/api/mcp`
Any other MCP client	Use the Streamable HTTP transport with the URL https://cashflow.chimneytopdigital.com/api/mcp: one JSON-RPC message per POST, JSON answers, no session and no authentication.

To see the raw protocol, list the tools and call one from a terminal:

curl -s https://cashflow.chimneytopdigital.com/api/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://cashflow.chimneytopdigital.com/api/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_bill_templates","arguments":{}}}'

Tools

Every tool is read-only and idempotent, so a client may run it without asking you first. Arguments are checked before a tool runs; a wrong one comes back as a message naming the field.

forecast_cash_flow Project daily balances

Runs the planner's forecast: expands every rule over the window and projects the end-of-day balance of each account and of the combined position (cash minus card debt). Returns the lowest point, the first day below the threshold and below zero, the ending balance, the low-balance and near-limit alerts the app would raise, and, when asked, the day-by-day series with what is scheduled on each day.

accounts (array, required)
rules (array, default []): Scheduled money movements; empty for balances only
start (string): First day of the window; defaults to today
days (integer, default 90): Window length in days
threshold_cents (integer, default 0): Low-balance threshold for cash accounts, cents
alert_within_days (integer): Horizon for the alert lists; defaults to the whole window
include_days (boolean, default false): Also return every day of the window (long for 90 days)

overdraft_check Will I overdraft this month?

The public calculator: from one checking balance and a short list of bills and income with their next date and cadence, whether the balance goes below zero before the end of the month, on which day, the lowest point, the ending balance and the days something happens. Amounts are positive cents; the kind gives the direction.

today (string): The day the balance is for; defaults to today
balance_cents (integer, required): Checking balance now, cents
cushion_cents (integer, default 0): Warn when the balance drops below this, cents
items (array, required)

occurrence_dates Dates a rule falls on

Every calendar date in a window on which a rule occurs, computed from its anchor so month-end clamping never drifts (Jan 31, Feb 28, Mar 31), plus the next occurrence on or after the window start and the planner's wording for the cadence. Use it to check a schedule before building a forecast.

frequency (object, required): How often the item happens
start_date (string, required): First occurrence of the rule
end_date (string): Last possible occurrence, inclusive
anchor_date (string): Counts the cadence from an earlier date than start_date (a rule split by an edit)
from (string): First day of the window; defaults to today
days (integer, default 90): Window length in days

detect_recurring Find recurring transactions in bank history

Groups imported transactions by payee and direction and suggests the recurring rules the planner would propose: cadence (weekly to yearly, or twice a month), typical amount, the next projected date and a confidence from how regular the spacing was. Give at least three months of history. Suggestions only; the user confirms each one in the app.

transactions (array, required)
min_occurrences (integer, default 3): Fewest matching transactions for a suggestion
amount_tolerance (number, default 0.2): Relative amount tolerance (0.2 = plus or minus 20%)
amount_tolerance_cents (integer, default 200): Absolute amount tolerance, cents; the larger of the two applies

list_bill_templates Common bill and income templates

The planner's starter templates (paycheck, rent, mortgage, car payment, utilities, subscriptions, groceries, ...) with their cadence, typical US amount in cents and the start date the app would pick from today. Starting points the user edits, not estimates of anyone's bills.

today (string): The date to compute start dates from; defaults to today
direction (in | out): Only income (in) or only bills (out)

Resources

ctds://cashflow-planner/notice: What a projection is. The caveat to repeat with any projected balance.

Limits

The tools compute from the values the assistant passes in. They cannot read or change anything in your Cash Flow Positive account; for that, use the app.
Results carry the same notices the app shows. They are estimates and working aids, not professional advice; ask your assistant to show the notice with the figure.
Rate limits apply per address. A request over the limit gets a plain error the assistant can read.
The tool list may grow. This page is generated from the running server, so it shows the tools as they are today.

If something fails

"Couldn't reach the MCP server", or a 404: Check the address character by character: the server answers only at https://cashflow.chimneytopdigital.com/api/mcp, over HTTPS. Nothing else on this host speaks MCP.
405 Method Not Allowed: The client sent a GET. The server speaks the Streamable HTTP transport without an event stream: one JSON-RPC message per POST, a JSON answer, no session. A notification gets an empty 202.
429 Too Many Requests: Your address passed the fair-use limit. The Retry-After header says how many seconds to wait; the limit resets on its own.
413 Payload Too Large: One request may carry 256 KiB. Send fewer rows per call, or summarize before you send.
A tool answers with an error naming a field: The argument did not match the tool's schema above: money is integer cents (or plain dollars where the tool says so), dates are YYYY-MM-DD, and lists are JSON arrays. Fix the named field and call again; nothing was stored.
Still stuck: Write to support@chimneytopdigital.com with the tool name, the arguments you sent (with nothing personal in them), the time in UTC and the exact message. We keep no record of calls, so what you send us is all we can look at.

How we built the servers, and the rules every one follows: our guide. Questions: hello@chimneytopdigital.com.