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.

Edit this page

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.

json
{
  "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:

ScopeWhat the screen says
ledger:readRead your accounts, transactions, and reports
ledger:stagePropose transactions for you to review, without recording them
ledger:writeCreate, edit, and delete transactions and accounts
offline_accessKeep working without asking you again
openidConfirm who you are
profileSee your name
emailSee 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

  1. Open Plugins in ChatGPT, at chatgpt.com/plugins. Choose +, then Add custom MCP server.
  2. Name it Simple Balance. Under Connection, enter https://app.smpl.money/mcp.
  3. For authentication, choose OAuth, and leave any client ID and secret empty.
  4. Read the warning, tick I understand and want to continue, and choose Create as a plugin.
  5. Install it from your plugins, and sign in to Simple Balance when ChatGPT asks.
  6. 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.

  1. In Claude, open Customize, then Connectors.
  2. Choose + Add, then Add custom connector.
  3. Name it Simple Balance and enter https://app.smpl.money/mcp. If Claude then shows the sign-in settings it found, leave them as they are.
  4. Choose Add.
  5. 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.

  1. Open Settings, then Connected Apps. If it isn’t there, it’s under Personal Intelligence.
  2. Under Custom apps, choose Add a custom app.
  3. Enter https://app.smpl.money/mcp, and choose Next.
  4. 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:

bash
gemini mcp add --transport http --scope user simple-balance https://app.smpl.money/mcp

Start 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:

bash
codex mcp add simple-balance --url https://app.smpl.money/mcp

Codex 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:

toml
[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:

bash
claude mcp add --transport http --scope user simple-balance https://app.smpl.money/mcp

Then 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:

bash
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:

json
{
  "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:

  1. Press Revoke beside it.
  2. 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, run codex 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:read sees no tool that stages, and may say it can’t find one. Ask it to run whoami, 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 scopes list in ~/.codex/config.toml and run codex mcp login simple-balance. In Claude Code, run claude mcp remove simple-balance, add it again with the wider list of scopes, then type /mcp and 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.