Connect an AI agent

Point Claude, or any MCP client, at your finances, or work with your ledger from the command line.

Ember can open your finances to Claude, or any app that speaks the Model Context Protocol. Ask about accounts, spending, and net worth in plain language instead of building a report. Access is off until you turn it on, and you can end it whenever you like.

AI agent access is part of Ember Pro, which is on the roadmap and not part of the private beta.

There are three ways to connect, and the first two are read-only. Most apps only need Ember's address: they send you to a page in your browser where you approve the connection with your password, and no secret is ever copied by hand. Some apps want a token you paste into a configuration file instead. The third is the ember command line tool, which is the only route that can also change your ledger, and only if you give it a token you created for that purpose.

What your agent can see

Four lookups:

Your spending totals. Inflow, outflow, and net over any period, grouped by category, payee, account, or month. Every matching entry is counted, so a period figure is exact. This is the call to start with: it usually answers the question on its own, and it says which account or category to read in detail.
Your accounts. Every active account with its balance, institution, and type. Debts show as negative, and a joint account shows your share.
Your net worth. The current figure, split into assets and debts, and into cash, investments, and liabilities. The same number the Net Worth report shows.
Your transactions. Cash-ledger activity, newest first, with payee, category, account, amount, memo, and cleared status. Your assistant can narrow to one account or a date range.

A connection reads your data and nobody else's.

What you can do with it

Over an MCP connection, your agent reads and never writes. The command line tool can write, but only with a token you created for that and marked as such; a read-only token refuses every write.

Either way it reaches nothing beyond your ledger, so login details, bank credentials, and institution connections are never in scope.

Analysis. Patterns rather than figures, with the arithmetic done across months, categories, and accounts.

"What did I spend on restaurants last month, and how does that compare to the three months before?"
"Which subscriptions am I paying that I haven't touched this year?"
"Find every transaction over $500 since January and tell me which ones look unusual."

Reporting. The finished artifact rather than raw numbers: a monthly summary, a category table, a note for your accountant or your partner.

"Write me a one-page summary of July: what came in, what went out, and where it went."
"Build a table of every category over $200 this quarter, sorted by total."

Reconciliation. Paste a statement in and have it cross-checked against what Ember shows cleared for that account and period: missing rows, disagreeing amounts, likely duplicates. You apply the fixes in Ember, so the audit trail stays yours.

"Here's my July card statement. Compare it against my Ember card ledger and list anything that doesn't match."

Planning. Questions that need cash and investments at once.

"What's my net worth, and how much of it is actually liquid?"
"Which account is my grocery spending coming out of, and is that deliberate?"

Because your assistant reads the real ledger rather than a summary, it can follow up on its own answers instead of stopping at the first number.

What to weigh before you connect

Connecting an agent means your financial data leaves Ember. You will be asked to accept these before the connection is made, either on the approval page or when you create a token.

Your data goes to your AI provider. Every question sends the relevant accounts and transactions to whichever provider you connected. What they retain, and whether they train on it, is governed by their terms rather than Ember's. Transaction history is more revealing than most people expect: it shows your employer, your income, your medical providers, and where you were on a given day. Ember cannot see, control, or retract that data once a client has read it.

A token is a credential. If you connect with a token rather than the browser approval, it grants read access to your entire financial picture, and most clients store it in a plain configuration file on your computer. Anyone who obtains that file can read what you can read, until the token expires or you revoke it. Do not paste it into a shared config, a chat message, or anything that reaches a repository. Approving in the browser avoids this: the app receives a credential that renews itself and expires on its own, and you never handle it.

An agent reads text other people wrote. Payee names and memos arrive from your bank and from merchants. An assistant with other tools, such as web access or email, can in principle be steered by text hidden in that data.

A read-only connection limits what that can do: your records cannot be changed this way, though read-only protects your records rather than your privacy, and what an assistant has already read it can still repeat elsewhere.

A write-enabled token removes that limit. An assistant holding one could be steered into changing entries. This is the reason the write scope is a separate choice with its own confirmation rather than something a token has by default. Every change it makes lands on your undo history, so you can see it and reverse it, but nothing asks you first. Give an assistant a read-only token unless you specifically want it making changes.

None of this makes connecting an agent a bad idea. It makes it a decision worth taking deliberately, which is why tokens expire and why revoking one is immediate.

Connecting with browser approval

This is the shorter path, and the one most apps expect. You need Ember's connection URL and nothing else.

Find it under Settings → AI agent access. It is your Ember address followed by /mcp.

Claude desktop and web

Open Settings → Connectors → Add custom connector.
Put the connection URL in Remote MCP server URL, and give it any name you like.
Leave OAuth Client ID and OAuth Client Secret empty. Those are for servers that require an app to be registered by hand in advance. Ember does not, so filling them in is not needed.
Click Add, then Connect. A page opens asking whether to allow the app.
Read what it lists, then approve. If you have a passkey, click Approve with a passkey. If you would rather type your password, choose Use your password instead.

Ember asks you to confirm even though you are already signed in. What you are granting keeps working long after this browser session ends, so being signed in is not on its own enough to hand it out. A passkey is the better choice where you have one: it cannot be phished, and this page is one you arrived at because an app sent you here.

Any other MCP client

Point the client at the connection URL. A client that supports OAuth for remote MCP servers will discover the rest on its own: Ember publishes its authorization details at the standard location, registers your app automatically, and sends you to the same approval page.

Connecting with a token

Use this when the app has no browser step, which is common for command-line tools.

Step 1: create a token

Go to Settings → AI agent access.
Under Create a token, name it for the assistant it belongs to, like "Claude Desktop" or "work laptop". You'll be glad of the name when you're deciding which one to revoke.
Choose how long it lasts: 30 days, 90 days, or a year. Every token expires, and 90 days is the default. A shorter life means a token you forget about stops working on its own.
Click Create token, read the summary of what you're granting, and accept it.

Copy the token now. It is shown once. Ember stores a fingerprint rather than the token itself, so it cannot show it to you again. If you lose it, revoke it and create another.

Copy the connection URL while you're there. Your assistant needs both.

If AI agent access is not in Settings, the feature is not switched on for your account.

Step 2: give it to your assistant

Your token goes in an Authorization header, as Bearer followed by the token.

Claude Code. One command, with your connection URL and token:

claude mcp add --transport http ember https://your-ember-host/mcp --header "Authorization: Bearer emb_mcp_your_token_here"

Any other client. Ember's endpoint is a standard remote MCP server over streamable HTTP. Point your client at the connection URL and have it send:

Authorization: Bearer emb_mcp_your_token_here

Clients vary in where that goes: a config file, a settings dialog, an environment variable. Any client that can attach a bearer token to a remote MCP server will work.

Command line

ember is a command line tool that works with your ledger from a terminal. It suits two situations: fixing a handful of entries without opening the app, and giving an AI assistant that can run commands a way to answer questions about your money without loading thousands of transactions into a conversation.

It is the one route that can change your ledger, and only with a token you deliberately created for that. A read-only token refuses every write and tells you so.

Step 1: download it

Go to Settings → AI agent access and click Download ember under Command line access. It is a single file that carries everything it needs, so your machine does not need Python installed.

You will see a button for each platform Ember has a build for. macOS on Apple silicon and Linux today; Intel Macs and Windows are not built yet.

Move it onto your PATH:

install -m 0755 ~/Downloads/ember ~/.local/bin/ember
ember --version

On macOS, also clear the quarantine flag that macOS puts on anything downloaded from a browser:

xattr -d com.apple.quarantine ~/.local/bin/ember

Skip that and macOS refuses to run it, reporting that the developer cannot be verified. That is the quarantine flag, not a problem with the file.

Keeping it up to date

The tool tells you. When your Ember deployment has a newer build than the copy you are running, the next command you run prints a one line note saying so. Download the new one the same way and install it over the old one.

The note goes to the error stream, not the output stream, so it never interferes with a command whose output you are feeding into something else. Nothing stops working when you are a version behind.

Create a token in Settings → AI agent access, choosing Read and write if you want the tool to be able to change entries. Then:

ember auth login --host https://your-ember-host

Paste the token when it asks. It is not echoed, so it stays out of your shell history. The token is stored in ~/.config/ember/credentials.json, readable only by you.

ember auth status shows which deployment and account you are signed in to. ember auth logout deletes the local copy, which does not revoke the token; revoke it in Settings to make it stop working.

Step 3: use it

ember account list                       # accounts and balances
ember txn list --limit 20                # recent entries
ember txn list --account "Checking"      # one account
ember txn set <id> category "Groceries"  # change one field

Add --dry-run to any command that writes and it prints what it would do without doing it. Add --format json or --format csv to get output a script can read; on a terminal you get a table by default.

Changes made here appear in the app immediately and sit on your undo history, so you can reverse one with Cmd+Z in the browser like any other edit.

Removing it

ember auth logout
rm ~/.local/bin/ember

ember auth logout deletes the token from your machine and tells you which file it removed. It does not revoke the token, and that difference is worth holding on to: the token keeps working until you revoke it in Settings → AI agent access or it expires. Deleting your copy is not the same as taking the access away.

So the order is: revoke the token in Ember first, then remove the files. If you are removing the tool because a machine was lost or you think the token was seen by someone else, revoke it now and deal with the files whenever.

Giving it to an assistant

Ember publishes a skill that teaches Claude how to use the tool: the commands, when to pipe rather than read, and the rules it should follow, including asking you before it changes anything.

Download the skill, then unzip it into your skills directory:

unzip ~/Downloads/ember-ledger-skill.zip -d ~/.claude/skills/

No account needed for this one. It is a description of the commands, not your data.

That leaves ~/.claude/skills/ember-ledger/SKILL.md. Claude picks it up on the next session.

Give an assistant a read-only token unless you specifically want it to make changes. You can create a second, write-enabled token later, and revoke either one on its own.

Managing what is connected

Settings → AI agent access lists everything with access, whether you approved it in the browser or gave it a token: what it is called, when it was connected, and when it was last used. The last-used date is worth a glance. Something that has never been used is safe to disconnect, and something being used when you are not working is worth asking about.

Disconnecting takes effect on that app's next request and cannot be undone. An app you approved in the browser can be reconnected by approving it again. A token can never be made to work again, so reconnecting that assistant means creating a new one. Give each assistant its own connection, so ending one does not disconnect the rest.