AI assistants

Your Budvo server can talk to AI assistants like Claude, ChatGPT, Cursor and Gemini. Connect one and it answers money questions with your real numbers instead of guesses, and, if you allow it, makes changes for you. Budvo speaks the Model Context Protocol (MCP), the open standard these apps use to reach outside tools, so any assistant that supports MCP can connect.

You decide what each assistant can see and do. By default it can only read.

What you can ask

Is a Costco membership worth it with my left over money?
Can I afford a $1,200 couch this month?
Make a goal for a new laptop by March.
Log $42 at Target.
Import this statement. (with a PDF or CSV attached)
When will I be debt free if I pay an extra $200 a month?
Which card should I use for groceries?

The assistant calls the same parts of your server the dashboard uses, so every number it quotes matches what you see in Budvo.

How it connects

Your server's MCP address is https://<your-server>/mcp, the address you open Budvo at with /mcp on the end. There are two ways in.

Sign in with Budvo (OAuth). Apps that connect from the internet, like claude.ai, the Claude mobile and desktop apps and ChatGPT, open a Budvo sign-in page where you choose a household and what the assistant may do. These apps reach your server from their own computers, so your server needs a public https address, for example through a Cloudflare Tunnel.

A personal access token. Tools that run on your own computer, like Claude Code, Claude Desktop, Cursor, VS Code and Gemini CLI, can use a token you make in Settings, AI assistants. This also works on localhost or an address on your home network, with no public address needed.

Make a token

Open Settings, AI assistants and choose to make a token.
Give it a name (for example Claude Code on my laptop), choose its permissions and when it expires (or never).
Copy the token. It starts with budvo_pat_ and is shown once; Budvo keeps only a hash of it.

The same screen shows your server's MCP address, ready to copy.

Claude

Claude is the best tested client. Pick the setup that matches where you use it.

claude.ai and the Claude apps

This needs a public https address.

On claude.ai, open Settings, Connectors and choose Add custom connector.
Name it Budvo, paste https://<your-server>/mcp as the URL and continue to step 2.
Authentication: keep Sign in now. Claude marks it Detected because Budvo announces its sign-in.
OAuth client: keep Use Claude's published identity, also marked Detected. Budvo reads Claude's client details from the address Anthropic publishes, so there's nothing to register. If connecting fails, come back and choose Register automatically instead. Only use Use your own OAuth client if you made a client in Settings, AI assistants for it.
Request headers: leave them empty. Sign-in replaces a token here.
Choose Add, then Connect. A Budvo page opens: sign in as usual (with two-factor or a passkey if you use them).
Pick the household and the permissions, then approve.

That's it. The connector also works in the Claude mobile and desktop apps on the same account. Turn it on in a chat and ask away.

Claude Code

Make a token, then run:

terminal

claude mcp add --transport http budvo https://<your-server>/mcp --header "Authorization: Bearer <token>"

A local address like http://192.168.1.20:8484/mcp works too. Type /mcp inside Claude Code to check that Budvo is connected.

Claude Desktop

Two options:

As a connector. If your server has a public https address, add it under Settings, Connectors exactly like claude.ai above.
With a token. For a server on your home network, edit Claude Desktop's config file (Settings, Developer, Edit Config) and add Budvo through the mcp-remote bridge, which needs Node.js:

json

{  "mcpServers": {    "budvo": {      "command": "npx",      "args": ["-y", "mcp-remote", "https://<your-server>/mcp", "--header", "Authorization:${BUDVO_AUTH}"],      "env": { "BUDVO_AUTH": "Bearer <token>" }    }  }}

If the address is plain http:// (a LAN address like http://192.168.1.20:8484/mcp), add "--allow-http" to the end of args. Restart Claude Desktop afterwards.

ChatGPT

ChatGPT connects with OAuth, so it needs a public https address. Custom connectors live behind developer mode, and the menus move around between versions, so the steps are general:

In ChatGPT's settings, turn on developer mode (under the connectors or apps settings).
Create a connector, name it Budvo, and paste https://<your-server>/mcp as the server URL.
Choose OAuth for authentication and save. ChatGPT sends you to Budvo to sign in, pick a household and set permissions.
Turn the connector on in a chat.

Cursor

Make a token and add Budvo to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

json

{  "mcpServers": {    "budvo": {      "url": "https://<your-server>/mcp",      "headers": { "Authorization": "Bearer <token>" }    }  }}

VS Code

Make a token and add Budvo to .vscode/mcp.json in your workspace:

json

{  "servers": {    "budvo": {      "type": "http",      "url": "https://<your-server>/mcp",      "headers": { "Authorization": "Bearer <token>" }    }  }}

Gemini CLI

Make a token and add Budvo to ~/.gemini/settings.json:

json

{  "mcpServers": {    "budvo": {      "httpUrl": "https://<your-server>/mcp",      "headers": { "Authorization": "Bearer <token>" }    }  }}

Other MCP clients

Anything that speaks MCP over Streamable HTTP can connect:

URL: https://<your-server>/mcp
With a token: send Authorization: Bearer <token> on every request.
With OAuth: the client finds everything from https://<your-server>/.well-known/oauth-protected-resource/mcp. Budvo supports dynamic client registration and client ID metadata documents, and requires PKCE.
Clients that can't register themselves: make an app by hand in Settings, AI assistants with its redirect addresses. You get a client ID (and a secret, shown once, if you ask for one) to paste into the client.

Permissions

You set permissions when you connect, and you can change them any time in Settings, AI assistants. Changes apply from the assistant's next request.

What it can do

Level	What happens
Read only (the default)	It can look but not change anything.
Read and suggest	Every change it wants to make waits in Budvo as a request. You'll find them under Requests from AI assistants on Today and in Settings, where you approve or decline each one. The assistant is told the change is waiting.
Read and write	It makes changes right away, within the limits below.

If you're a viewer in the household, your connections are always read only.

Areas

Choose which parts of Budvo it can use: accounts, transactions, bills, debts, goals, budget, the jar, subscriptions, statements and add-ons. Everything except add-ons is on by default. Anything outside the chosen areas isn't offered to the assistant at all.

Accounts it can see

All accounts is the default, and includes accounts you add later. Pick specific accounts and the others are hidden everywhere: their transactions, and the bills, plans, findings, subscriptions and statements tied to them, are left out, and a transfer to a hidden account shows as an account this connection can't see.

Some numbers only make sense for the whole household: safe to spend, projected balances, the payoff plan and debt-free date, afford and what-if answers, and budget totals. Those are still worked out over everything, and Budvo tells the assistant so. Money in hidden accounts shows up only as one combined figure, never account by account.

Limits

Hide memos and notes. Leaves them out of everything it reads.
Round amounts. Every amount is rounded to whole dollars.
History limit. Only the last so many months of transactions, spending, statements and findings.
Max amount per transaction. Caps any transaction, payment or jar pledge it logs.
Max changes per day. Caps changes and requests.
Always ask. Even with read and write, changes to things that already exist (marking a bill paid, skipping or moving one, editing a bill or goal, jar settings, a planned refinance, confirming an import) become requests you approve.

Never available

No assistant can reach sign-in, people, permissions, server admin, backups, exports or keys, whatever its permissions. And nothing can be deleted: there's no tool for it.

Watching and revoking

Each connection shows when it was last used and an activity log with every call it made, what it read and anything it was refused, kept for 90 days. Revoke ends one connection on the spot, and its waiting requests expire. Revoke all ends them all at once. Owners see everyone's connections in the household and can revoke them.

Owners can turn AI assistants off for a household in Settings. To turn the feature off for the whole server, set BUDVO_MCP=false.

What the assistant can use

Tools

Area	Reads	Changes
Overview	`get_overview` (always available)
Accounts	`list_accounts`, `get_account`, `best_card`
Transactions	`search_transactions`, `list_categories`, `spending_summary`, `membership_value`	`log_transaction`
Bills	`list_upcoming`, `get_calendar_month`	`mark_bill_paid`, `skip_or_move_occurrence`, `create_or_update_bill`
Budget	`get_paycheck_plan`, `get_budget`, `can_i_afford`
Debts	`get_debts_and_payoff`, `simulate_payoff`, `what_if`, `windfall_options`	`save_planned_refinance`
Goals	`list_goals`	`create_goal`, `update_goal`
Jar	`get_jar`	`set_jar`, `drop_in_jar`, `create_no_spend_challenge`
Subscriptions	`list_subscriptions`, `list_findings`	`mark_subscription`
Statements	`list_statements`	`import_statement`, `confirm_statement_import`
Add-ons	`list_addons`

Statements come in two steps, like Activity, Import: import_statement reads the file (up to 15 MB) into a waiting import with the same preview you'd see, and confirm_statement_import imports it. Both need read and suggest or read and write.

Resources and prompts

Some apps let you attach Budvo data or start from a ready-made prompt.

Resources: budvo://accounts, budvo://plan, budvo://budget/current and budvo://calendar/{month} (a month like 2026-03).
Prompts: monthly-check-in, can-i-afford, plan-a-goal and membership-worth-it.

Is a membership worth it?

membership_value is behind questions like the Costco one. It doesn't guess from averages; it uses your own spending:

It finds what you spent at the stores the membership would replace, by payee or category, in the accounts it can see, over the last 12 months (or the history there is), and scales that to a year.
It takes the share of that spending you'd move to the membership, times a savings rate. You give the savings rate, or the assistant estimates one (or works it out from a price list), and either way it's listed in the answer.
It adds any rewards you'd earn there and subtracts the yearly fee.

You get the yearly net, how much you'd need to spend there to break even, the savings rate you'd need, and a verdict: worth it, not worth it, or about even when it's within 10% of the fee. With under four weeks of history it says there isn't enough data. Every assumption comes back with the answer, so you can push back on any of them.

Security and privacy

Your data stays on your server, except what an assistant reads. When an assistant calls a tool, the result goes to the assistant and so to its AI provider (Anthropic for Claude, OpenAI for ChatGPT, and so on), under that provider's terms. To share less, use read only, limit the accounts it can see, hide memos and notes, round amounts and set a history limit.
Tokens are stored as hashes and shown once. You can set them to expire.
OAuth uses PKCE. Access tokens last an hour and only work on your server's /mcp. Refresh tokens last 30 days and change on every use; if an old one is ever used again, the whole connection is revoked.
Bank data is treated as data. Payee names and memos come from outside, so Budvo strips hidden characters from them and tells the assistant they're data, not instructions.
Rate limits. Each connection can make 120 requests a minute, and failed tokens count toward the same limit as failed sign-ins.
The server must be unlocked. After a restart, assistants get nothing until someone unlocks Budvo. See the security model.
Everything is logged. Connecting, new tokens, permission changes, revoking and approved requests go into the audit log, and every call is in the connection's activity.

Troubleshooting

"The server is locked." Budvo restarted and hasn't been unlocked yet. Open the dashboard, unlock it with your database password, and ask again.

401 or "invalid token". The token was revoked or has expired, or was copied incompletely. Make a new one in Settings, AI assistants. For OAuth apps, disconnect and connect again.

claude.ai or ChatGPT can't reach the server. These apps connect from the internet, so an address like http://192.168.1.20:8484 or a Tailscale address won't work for them. Give the server a public https address with a Cloudflare Tunnel, or use a local tool like Claude Code or Claude Desktop with a token.

Sign-in fails or the app complains about http. Behind a tunnel or proxy, Budvo needs BUDVO_PUBLIC_URL or BUDVO_TRUST_PROXY=true to know it's reached over https. Without them it advertises http:// addresses that OAuth apps refuse. For mcp-remote on a plain http LAN address, add --allow-http.

"AI assistants are turned off for this household." An owner turned them off. They can turn them back on in Settings, AI assistants.

Nothing at /mcp at all. The server was started with BUDVO_MCP=false. Remove it and restart.