Connecting an AI assistant (MCP)
Connect ChatGPT, Claude, Gemini, Codex or Claude Code to Simple Balance at app.smpl.money/mcp: setup for each, what it can change, and what to do when it fails.
You can connect an AI assistant to Simple Balance through MCP, the Model Context Protocol, which is a standard way for an assistant to use another app. Once it’s connected, it can do almost everything the web app does, such as importing a statement, tidying categories, chasing duplicates and answering questions about your money. Four account-management tasks are kept from it, and they’re listed below.
What keeps it from doing damage
Two things, and neither is a promise. Both are enforced.
Staging. An agent can propose as much as it likes. A staged row has no
postings, appears in no balance and is in no report until somebody commits it.
An agent holding ledger:stage can propose and can’t commit; committing takes
ledger:write.
Scopes. Every connection carries scopes, fixed when you approve it.
ledger:read can’t write. ledger:stage can propose and can’t decide:
creating a category, restoring an archived one or widening what kind of entry
it may carry all need ledger:write, wherever they’re reached from, including
a CSV import. So does adding or moving a Simple Balance file: adding one
creates its accounts, categories and other records at once, and moving one
writes its transactions straight into your books.
Connecting one
The server speaks MCP over HTTP at /mcp, and it’s protected by OAuth. Give
your client the address and nothing else: no token, no header. On
app.smpl.money the address is https://app.smpl.money/mcp. On a copy you run
yourself, it’s your own address followed by /mcp.
{
"mcpServers": {
"simple-balance": {
"url": "https://app.smpl.money/mcp"
}
}
}That’s the shape for a client that takes a server’s URL in an mcpServers
block in its settings file. A client that adds servers in its own settings
screen instead takes the same address there.
Claude Code needs one more line in that entry, "type": "http", and skips it
without. Connect your assistant has the steps for
each client.
The client learns the rest from what Simple Balance publishes about its sign-in, registers itself, and opens a browser. You sign in there the way you sign in to the web app, unless that browser is signed in already, and an Allow this MCP client? screen names the client, the email address of the Simple Balance account that browser is signed in to, and where approving sends you back to. It lists the scopes the client asked for, each with a plain description:
| Scope | What the screen says |
|---|---|
ledger:read | Read your accounts, transactions, and reports |
ledger:stage | Propose transactions for you to review, without recording them |
ledger:write | Create, edit, and delete transactions and accounts |
offline_access | Keep working without asking you again |
openid | Confirm who you are |
profile | See your name |
email | See your email address |
Choose Allow access or Deny access. The screen grants what was asked or nothing; it doesn’t narrow the request.
So the scopes are decided by the client. One that asks for every scope the
server advertises gets ledger:write along with the rest. Simple Balance’s
first answer to a client that hasn’t signed in yet names every scope in the
table, so a client that takes its scopes from that answer asks for all of them
too. If yours lets you set what it requests, ask for ledger:stage, or
ledger:read for an assistant that only answers questions.
Two more things on the screen are worth checking before you choose. The client’s name is whatever the client calls itself, so the site it sends you back to is the one to check, and the screen says “Allow access only if you recognize it.” When that site is your own computer, it says instead “That address is this computer, so the client is a program running on your own machine.” The email is the account whose books you’re granting, which matters when the browser is still signed in to a different Simple Balance account from the one you meant.
An assistant sees your name only with profile and your email address only
with email. Without them, whoami gives it neither.
Connect your assistant
Each of these registers itself, so none needs a client ID or a secret. When it connects, a browser opens at Simple Balance: sign in if you aren’t already, and approve the connection on Allow this MCP client?
ChatGPT
- Open Plugins in ChatGPT, at chatgpt.com/plugins. Choose +, then Add custom MCP server.
- Name it
Simple Balance. Under Connection, enterhttps://app.smpl.money/mcp. - For authentication, choose OAuth, and leave any client ID and secret empty.
- Read the warning, tick I understand and want to continue, and choose Create as a plugin.
- Install it from your plugins, and sign in to Simple Balance when ChatGPT asks.
- In a new chat, type
@and pick Simple Balance.
OpenAI says custom MCP servers are for ChatGPT Business, Enterprise and Edu, on the web. On Business only an admin or owner can add one, and on Enterprise and Edu an admin decides who can. On Pro, ChatGPT can connect one for reading only. By default ChatGPT asks you to confirm a change before it makes it, and you can tell it to stop asking for one tool in a chat.
Claude
On claude.ai and in Claude Desktop, Simple Balance is a custom connector. Claude’s free plan allows one custom connector.
- In Claude, open Customize, then Connectors.
- Choose + Add, then Add custom connector.
- Name it
Simple Balanceand enterhttps://app.smpl.money/mcp. If Claude then shows the sign-in settings it found, leave them as they are. - Choose Add.
- When Claude opens Simple Balance, sign in, read what’s listed on Allow this MCP client?, and choose Allow access.
To use it in a chat, press + at the bottom left of the message box, choose Connectors, and switch Simple Balance on.
On a Team or Enterprise plan, an owner adds it under Organization settings and then Connectors. Each person then connects their own Simple Balance account from Customize and Connectors.
Gemini
In the Gemini app, Simple Balance is a custom app. You add it on the web, at gemini.google.com, and then it’s in Gemini’s phone app too. Google offers custom apps to people in the US who are 18 or older, signed in with a personal Google account, with Gemini in English and Keep Activity on.
- Open Settings, then Connected Apps. If it isn’t there, it’s under Personal Intelligence.
- Under Custom apps, choose Add a custom app.
- Enter
https://app.smpl.money/mcp, and choose Next. - Sign in to Simple Balance, and choose Allow access.
To use it in a chat, type @ and pick Simple Balance. Gemini asks you to
confirm each change before it makes it.
Gemini CLI is for organizations with Gemini Code Assist Standard or Enterprise. In it, run:
gemini mcp add --transport http --scope user simple-balance https://app.smpl.money/mcpStart gemini in a folder you trust, because in one you haven’t it connects
no servers. /permissions trust trusts the folder you’re in. Then run
/mcp auth simple-balance to sign in. Gemini CLI doesn’t start the sign-in by
itself.
Codex
Codex, OpenAI’s coding assistant, keeps one list of servers for its command line, its editor extension and the ChatGPT desktop app. Add Simple Balance from a terminal:
codex mcp add simple-balance --url https://app.smpl.money/mcpCodex notices that Simple Balance needs a sign-in and opens it, asking for
every scope Simple Balance offers, ledger:write included. To choose instead,
don’t run that command. Put the server in Codex’s settings file,
~/.codex/config.toml, with the scopes written out:
[mcp_servers.simple-balance]
url = "https://app.smpl.money/mcp"
scopes = ["openid", "profile", "email", "offline_access", "ledger:read", "ledger:stage"]Then sign in with codex mcp login simple-balance. That’s the staging access
this page suggests. Add "ledger:write" to the
list to let it commit too.
In the ChatGPT desktop app or the editor extension, you can add it from
Settings instead, which is the gear menu in the extension. Choose
MCP servers, then Add server. Name it simple-balance, pick
Streamable HTTP, enter the address, save it, and choose Restart. Then
choose Authenticate.
Claude Code
Run this in a terminal:
claude mcp add --transport http --scope user simple-balance https://app.smpl.money/mcpThen type /mcp in Claude Code, choose simple-balance, and sign in. Here,
--scope user is Claude Code’s own setting, for which of your projects can
use the server. It has nothing to do with what Simple Balance lets it do.
Unless you set them, Claude Code leaves the scopes to Simple Balance, and it
may ask for every one, ledger:write included. To choose, add it with the
scopes written out instead:
claude mcp add-json --scope user simple-balance '{"type":"http","url":"https://app.smpl.money/mcp","oauth":{"scopes":"openid profile email offline_access ledger:read ledger:stage"}}'That’s the staging access this page suggests.
Add ledger:write to the list to let it commit too.
To write the entry yourself, in a project’s .mcp.json file, give it
"type": "http" beside the address:
{
"mcpServers": {
"simple-balance": {
"type": "http",
"url": "https://app.smpl.money/mcp"
}
}
}If you’ve added Simple Balance on claude.ai and you sign in to Claude Code with the same Claude subscription, the connector is already in Claude Code, and you don’t need the command. If you add it with the command too, Claude Code uses that one and hides the connector.
Things to ask it
Once it’s connected, try one of these:
- “Where did my money go last month?”
- “What day did I pay the electric bill last month?”
- “Add a $42.18 grocery purchase on checking for me to approve.”
The first two only read. The third needs ledger:stage. It puts a row on
Staged, which changes no balance until you commit it.
See and revoke connected agents
Every client you’ve approved is listed under Connected agents in Settings, with what it may do:
- Read only for
ledger:read. - Read and queue for review for
ledger:stage. - Read, stage, and commit for
ledger:write.
Beside it, Active means it holds a token that still works, and No live token means its tokens have run out but your approval still stands. The line under its name also says when you approved it, when it last took a token, when the approval runs out, and how many tokens it holds.
To cut one off:
- Press Revoke beside it.
- Press Revoke access to confirm.
It loses access at once, including any token it’s already holding, and it can’t renew. Your ledger isn’t changed, and anything it already recorded stays. To let it back in, authorize it again from the agent itself. Changing your password disconnects every client too.
What it can do
It reaches the whole ledger, through the same services the web app uses. The application’s own tests compare the two, route by route and field by field, and name each difference with its reason. Leaving aside the four things above, the differences are these. The web app downloads a Simple Balance file of up to 100,000 rows, where an assistant takes 10,000 at a time, so more than 10,000 staged rows or budget amounts, which have no date to split them by, leave only through Export file. An assistant can move a budget’s start, or retune a saving goal’s target or date, an average’s months, or a step’s or a share’s percentage, where the web app has you delete the budget and set it again. It can set a date, a split, a category typed by name or the amount received across many templates at once, which Edit selected on Templates doesn’t offer, and it can narrow transactions or a CSV export to one currency. And it reads the money guides from a copy inside Simple Balance, where you read the same guides here on smpl.money, under Learn. So you can ask it to:
- Add, edit, archive and delete accounts, read their balances and register, and choose which accounts stay usable on the free plan.
- Add, edit, delete and restore transactions, split them across categories, and change or delete many at once.
- Add, rename, group, archive and merge categories, and merge payees.
- Stage transactions, bring a CSV file in to Staged, review possible duplicates, and commit what’s ready.
- Set up and change recurring transactions and templates.
- Set budgets, and read the budget report, the six reports and the forecast.
- Export your transactions as a CSV file, or your whole ledger or some of its accounts as a Simple Balance file, and preview a Simple Balance file and add or move one into your books.
- Read your activity history, change your preferences, and list or disconnect connected agents.
- Read the money guides, so it can explain how to make a budget or balance a checking account. Reading one touches nothing in your books, and the copy comes with each release of Simple Balance, so a guide changed here since then reads to an assistant as it was.
Each of those still needs the scope for it. An agent with ledger:read can
look at everything on that list and change none of it, and that includes
exporting either kind of file, previewing a Simple Balance file and reading
the guides. One with ledger:stage can also add, fix and delete rows on
Staged, including a CSV file’s, and change nothing else. Everything else
takes ledger:write.
The same limits apply as well. On app.smpl.money’s free plan, an account that’s frozen refuses an agent’s changes just as it refuses yours.
Checking what it did
Everything an agent changes is listed on Activity, marked with an Agent badge, beside what you did on the web (Web) and what the schedule did (Scheduled). Activity history explains how to read it.
When it doesn’t work
- No browser window opens. In Gemini CLI, that’s expected: run
/mcp auth simple-balance. In Codex, runcodex mcp login simple-balance, and on a computer with no browser add--no-browser, open the address it shows somewhere else, and paste the address you end on back into Codex. When Claude Code can’t open your browser, it shows the sign-in address instead. Copy it into a browser and sign in there. If the browser then shows a connection error, copy the whole address from its address bar and paste it into Claude Code when it asks. - A tool it needs isn’t there. Simple Balance leaves a tool out of the
assistant’s list when its scopes don’t reach it. So an assistant with only
ledger:readsees no tool that stages, and may say it can’t find one. Ask it to runwhoami, which lists the scopes it holds, or look under Connected agents in Settings. - It needs a wider scope. Connect it again, asking for more. In Codex,
widen the
scopeslist in~/.codex/config.tomland runcodex mcp login simple-balance. In Claude Code, runclaude mcp remove simple-balance, add it again with the wider list of scopes, then type/mcpand sign in. If an assistant calls a tool by name that its scopes don’t reach, Simple Balance refuses and names the scope it needs. Claude on claude.ai then asks you to sign in again and approve it. Each time, the approval screen lists what’s asked for, and nothing widens until you choose Allow access. - It has to sign in again after a while. Each time an assistant renews its access, Simple Balance hands it a new refresh token, which is what it renews with, and the old one stops working in the same answer. An assistant that keeps using an old one is turned away until it signs in again. Connecting it again gets it going. If it keeps happening, the assistant isn’t keeping the new token, and that’s for whoever makes the assistant to fix.
- It says a date range is too long. One request from an assistant lists at most 200 of an account’s postings, exports at most 100 transactions and 60,000 characters of CSV, and carries at most 10,000 rows of a Simple Balance file. Past that, Simple Balance turns the whole request down, rather than handing back part of it, and says what to narrow, usually the dates. The web app’s own register and downloads go further, and Limits lists each.
- You want to cut it off. Revoke it under Connected agents. It loses access at once, whatever the assistant still holds.
- It says an account is frozen. On the free plan, an account over the limit is frozen. Simple Balance refuses an assistant’s changes to what it holds, just as it refuses yours, and trying again won’t get past it. Use an account that’s still in use, or choose which accounts stay usable. Subscribing again unfreezes them all, and only you can do that, from the web app.
A sensible way to use it
Connect the assistant with ledger:stage. Let it do the filing. Read what it
staged on Staged, and commit the part you agree
with.