Connect your AI assistant to your budget data
Add the Frum Finance MCP server to Claude, ChatGPT, or Cursor and ask things like "How did we do against budget last month?" or "Split this receipt in YNAB." The assistant uses your live numbers instead of guessing. You approve each permission, and you can revoke access at any time.
The short version
Add
https://api.frum.finance/mcp as a remote MCP connector in your AI
app, sign in with your Frum Finance email and password (plus 2FA if you use it),
approve the permissions, and start asking questions.
YNAB permission change
Editing an imported transaction now needs
ynab:transactions:edit, and creating a
new transaction needs ynab:transactions:write. Apps approved before this change
must reconnect for fresh approval. Old approvals do not gain creation access. Approval
screens opened before the change must restart. Read-only connections are unaffected.
Before you start
- You need an active Frum Finance account with a verified email address. The approval screen requires a fully signed-in session (password plus 2FA), so have your authenticator app handy if you use one.
- For YNAB tools, link YNAB in Frum Finance first (Settings, then YNAB).
-
Alpha members: use
https://api.alpha.frum.finance/mcpinstead of the production URL everywhere below.
Connect your app
Every app follows the same pattern: add the server URL, a browser window opens, you sign in and approve, and the app is connected.
Claude (Desktop or web)
- Settings, then Connectors, then Add custom connector.
-
Enter
https://api.frum.finance/mcpas the remote MCP server URL. - Sign in on the Frum Finance page that opens, review the permissions (see below), and choose Allow.
- Enable the connector in your conversation and ask "What are my budget categories for this month?"
ChatGPT
- Settings, then Apps & Connectors (under Connectors in developer mode), then Create / Add connector.
-
Choose MCP, enter
https://api.frum.finance/mcp, and pick "No authentication" at the connector level (sign-in happens on Frum Finance's own login page in the next step). - Start a chat that uses the connector, sign in on the Frum Finance page, review the permissions, and choose Allow.
- Ask "Show my budget for this month" to confirm it works.
Cursor
- Cursor Settings, then Tools & MCP, then Add Custom MCP (or "New MCP Server").
-
Add a remote server of type HTTP with the URL
https://api.frum.finance/mcp. - Sign in on the browser page Cursor opens, and choose Allow on the permission screen.
- Refresh the MCP panel in Cursor: the server should show connected tools.
Other MCP clients
Any MCP-capable app works the same way: point it at
https://api.frum.finance/mcp over Streamable HTTP. The app opens the
sign-in and approval page in your browser; there is nothing to paste into the app
itself.
What you are approving
The approval screen lists exactly what the assistant may access. Each permission (called a "scope") unlocks a specific set of tools:
| Permission | What the assistant can do with it |
|---|---|
| profile:read | See your basic profile: name, email, household setup. Also unlocks the shared Kesef Compass category list. |
| budgets:read | Read your monthly and annual budget rows and your budget history. |
| insights:read | Read your insights reports: how your numbers compare with similar families in the community. |
| ynab:read | Read your linked YNAB data: categories, plan months, balances, and transactions. This permission never changes YNAB. |
| budgets:write | Save budget drafts with the same confirmation step as saving in the app. Every save is logged with which app made the change. |
| category-map:write | Change how your spending labels are grouped in Kesef Compass reports. This does not change anything in YNAB. You do not need this to list Compass categories. |
| ynab:transactions:edit | Split or recategorize one imported YNAB transaction (for example, matching a receipt). It cannot create transactions, change the total, or rewrite transfers and already-split rows. Every change is logged. |
| ynab:transactions:write | Create one new YNAB transaction (for example, manual entry of a cash purchase). It does not touch transactions your bank already imported. Every change is logged. |
Approve only what you need
Reading and planning only needs the three read permissions plus, if you use YNAB,
ynab:read. Only approve budgets:write if you actually want the
assistant to save budgets for you. Only approve category-map:write if you want
the assistant to change how your spending is grouped in Kesef Compass. Listing Compass
categories does not need a YNAB or mapping permission. Only approve
ynab:transactions:edit if you want it to split or recategorize existing YNAB
transactions (receipt matching), and only approve ynab:transactions:write if
you want it to create new ones. Each is approved separately; neither grants
the other. ynab:read alone never allows edits or creation.
The tools your assistant gets
These are the MCP actions. If a tool fails with a permission error, reconnect and approve the matching scope.
| Tool | Needs | What it returns |
|---|---|---|
get_my_profile |
profile:read | Your profile, same as the app's account page, including YNAB refresh status when a budget is linked. |
list_compass_categories |
profile:read | The shared Kesef Compass category list (id and label). Use these ids when grouping spending labels. |
get_my_budgets |
budgets:read | One month's budget rows: goal and spend per category. |
get_my_budget_history |
budgets:read | Up to 12 months of budgets in one call. |
get_my_annual_budgets |
budgets:read | A year's budget rows. Never blocked by missing monthly data. |
get_my_insights |
insights:read | Monthly insights against your community cohort. |
get_my_annual_insights |
insights:read | The annual report. |
get_my_ynab_categories |
ynab:read | Your YNAB categories and how they map in Frum Finance. |
get_my_ynab_months |
ynab:read | A YNAB plan month: budgeted, activity, balances, income. |
get_my_ynab_accounts |
ynab:read | Your open YNAB accounts and balances. |
get_my_ynab_transactions |
ynab:read | A month of YNAB transactions, newest first, 500 per page maximum. Amounts are in YNAB "milliunits": 1000 means $1.00. Includes category and split details so a receipt can be matched to an imported bank row. |
save_my_monthly_budgets |
budgets:write | Save monthly budget rows, with the app's monthly confirmation step. |
save_my_annual_budgets |
budgets:write | Save annual budget rows. |
map_my_categories |
category-map:write | Replace the full set of YNAB category ids grouped into one Kesef Compass category. Send every id that should stay on that Compass category; omitted ids move off it. Use YNAB category ids, not names. Does not write to YNAB. |
update_my_ynab_transaction |
ynab:transactions:edit | Split or recategorize one imported YNAB transaction. Split amounts must add up to the existing total (milliunits; outflows are negative). Does not create new transactions. |
create_my_ynab_transaction |
ynab:transactions:write | Create one new YNAB transaction (milliunits; outflows are negative). Review the account, date, amount, and details with your assistant first. It does not change transactions your bank already imported. |
What the server will never do
The assistant can only reach your data: never another family's rows, and never
advisor or RightCapital balances. YNAB changes use two separately
approved permissions:
ynab:transactions:edit for splitting or recategorizing an
existing imported transaction, and ynab:transactions:write for creating one new
transaction. One never grants the other. The server never rewrites transfers or
already-split rows. Grouping spending labels in Kesef Compass is a Frum Finance change, not
a YNAB change.
How your connection stays safe
- You are the only one who can approve. Approval requires a full sign-in (email, password, 2FA), so an AI app can never connect silently.
- Approval is per app, and tokens are random values stored only as hashes on our side. They expire, and sign-in codes work once.
- Writes are guarded and logged. Saving budgets through the assistant runs the exact same checks as saving in the app, including the YNAB monthly confirmation. Changing a YNAB transaction is logged separately and only touches one existing row you already imported; creating a transaction saves one new row and is logged the same way.
Manage or remove access
Remove the Frum Finance connector in your AI app (Claude: Settings, Connectors; ChatGPT: Settings, Apps & Connectors; Cursor: Settings, Tools & MCP). Revoking is immediate: every token for that connection stops working at that moment. To change permissions, reconnect and approve a different set of scopes.
Troubleshooting
| What you see | What to do |
|---|---|
| The sign-in page keeps asking me to log in again | Complete the password step and the 2FA step in the same browser window, then retry the connector. |
| A tool says it needs a permission (for example, "budgets:read") | Remove the connector, add it again, and approve the listed permission this time. Permissions are locked in at approval and cannot be added later without reconnecting. |
| YNAB tools fail with a "disconnected" error | Link YNAB in Frum Finance first (Settings, then YNAB), then retry. |
| Nothing happens when the assistant calls a tool |
Make sure the connector is enabled for the conversation, and check that the
server URL matches your account: production members use
https://api.frum.finance/mcp, alpha members use
https://api.alpha.frum.finance/mcp. Mixing the two is the most
common cause.
|
| Errors right after a password change | Remove and re-add the connector. This forces a fresh sign-in and replaces any expired tokens. |
Still stuck?
Post in the Frum Finance community Slack or reply to a product email. Include your
AI app, the server URL you used, and the exact error text.