Tally — a shared household ledger you talk to

An MCP server for Alexa+ that tracks who paid for what in a household, and works out the fewest payments that settle everyone up.

"Alexa, Sam paid 132 dollars for dinner, split with Chris and Maya."
   → Recorded 132 dollars for dinner, paid by Sam, split 3 ways.
     That's 44 dollars each.

"Alexa, who owes what?"
   → 2 payments settle Apartment 4B. The biggest: Maya owes Sam 44 dollars.

Why voice, and why a shared device

Splitting expenses is not an arithmetic problem — a calculator solved that decades ago. It is a capture problem. Nobody unlocks a phone and opens an app at a restaurant table, so the expense goes unrecorded, and a week later the evening is settled from memory and somebody quietly eats the difference.

Voice removes the capture cost: you say it while the bill is still in your hand.

And Alexa is not a personal device — it sits in the kitchen and belongs to everyone in the apartment. A shared ledger on a shared device is something a per-phone app structurally cannot be: any flatmate can record a purchase or ask where things stand without installing anything.

Being shared is also why the payer gets named out loud. "Sam paid for dinner" works from the kitchen counter whoever is standing at it; "I paid" only means something on an account linked to one person, which is what the invite code establishes.

Related MCP server: Expense Tracker MCP Server

What it does

Three decisions that shaped the build

The spoken answer is the product; the screen is a bonus. Every tool returns a sentence written to be heard once — it leads with what you should do, not with a table nobody can hold in their head. client_supports_apps() decides whether a screen exists at all: an Echo Show additionally gets the MCP Apps balance sheet, an Echo Dot loses nothing but the picture. Both paths are tested.

Never guess whose money it is. Speech recognition is lossy, so names get resolved exactly, then by unambiguous prefix. "An" with both Anna and Andrew in the apartment does not pick one — it asks, over MCP elicitation, and falls back to putting the question in the error text when the host has no back-channel. Misattributing an expense is worse than one extra question.

Money is integers, end to end. Every amount is a count of minor units, and floats never touch the arithmetic. A three-way split of 10.00 cannot be equal, so the odd cent is handed out on a rotation instead of always landing on the same person. Property-based tests assert the invariants that matter: balances always sum to zero, and the suggested transfers actually clear the ledger.

Architecture

tally/
  money.py    Minor-unit arithmetic; equal / weighted / exact splits
  ledger.py   Households, entries, balances, debt simplification
  store.py    SQLite persistence (WAL)
  server.py   MCP server: tools, Apps binding, elicitation
  ui.py       The ui:// app resource for screen devices
  auth.py     OAuth 2.1 authorization server (PKCE, rotation)
  login.py    Account linking — redeeming an invite code

The ledger domain has no MCP dependency and no I/O, which is why its invariants can be hammered with generated input in milliseconds.

Settling up uses the standard greedy max-debtor/max-creditor match. Each step zeroes at least one person, so it never needs more than n-1 transfers, against the n(n-1)/2 of paying everybody back individually. (Finding the true minimum is NP-hard; this is optimal unless a strict subset happens to balance among itself.)

Running it

uv sync
uv run pytest                        # 243 tests
uv run python -m tally --stdio       # for the MCP Inspector

Seeing it work without an Echo

Alexa+ add-on publishing is limited to partners in the US, so the two scripts in demo/ stand in for the device. Run all three in separate terminals:

uv run python -m tally --port 8000
uv run python demo/mock_host.py       # http://127.0.0.1:8977
uv run python demo/conversation.py --speak

conversation.py plays a scripted exchange against the running server: each line is an utterance, the tool call Alexa+ would route it to, and the server's own spoken answer — read aloud by the system voice, with per-call latency. Nothing is stubbed; every reply came over Streamable HTTP.

mock_host.py renders the ui:// app at Echo Show 15 and Echo Show 5 sizes, performing the same ui/initialize handshake a real host would and logging every message the app sends back. It follows the live server, so the balance sheet fills in as the conversation runs.

Speech and screen are rendered differently, on purpose

Alexa reads a tool's text aloud verbatim, so the same amount is written twice: 42 dollars 50 cents in the spoken answer, $42.50 in the structured payload a screen renders. "42.50 USD" would be read out as "forty two point five zero U S D".

Over HTTP, the transport Alexa+ uses:

uv run python -m tally --port 8000

Connecting it to Alexa+

Alexa needs a public HTTPS origin and OAuth. Expose the local server and pass the public URL — that switch turns on discovery metadata, the authorization code flow with PKCE, and the account-linking page:

cloudflared tunnel --url http://localhost:8000
uv run python -m tally --port 8000 --public-url https://<your-tunnel>.trycloudflare.com

Alexa+ does not register itself, so it needs a client configured up front. Without TALLY_CLIENT_ID and TALLY_REDIRECT_URI (the values from the Alexa developer console) account linking cannot start at all:

export TALLY_CLIENT_ID=... TALLY_REDIRECT_URI=https://layla.amazon.com/api/skill/link/...

Then onboard the add-on:

alexa-ai configure
alexa-ai new mcp --name "Tally" --locale en-US \
  --mcp-server-url https://<your-tunnel>.trycloudflare.com/mcp
alexa-ai deploy

Without --public-url the server runs unauthenticated — fine for the Inspector and the test suite, never for a real device.

Joining a household

A name is not a secret. Adding someone creates a placeholder member and a single-use invite code, which the person who set the household up passes on; linking a device redeems that code. Matching on the name instead would let anyone who guessed a flatmate's first name attach their own Alexa to somebody else's ledger.

Protocol conformance

• MCP spec 2025-11-25+ over Streamable HTTP.

• MCP Apps (io.modelcontextprotocol/ui): a ui:// resource served as text/html;profile=mcp-app, bound to four tools via _meta.ui.resourceUri, with a ui/initialize handshake and no network access at all in its CSP.

• OAuth 2.1: /.well-known/oauth-authorization-server, authorization code

  • PKCE (S256), dynamic client registration, refresh-token rotation, and RFC 8707 resource validation so a token minted for another server is refused.

• Tool annotations: read-only and destructive hints, so a host knows what needs confirming before it runs.

• Resources and prompts: the ledger is readable at tally://household as JSON — reading where things stand is not a side effect and should not need a tool call — and three prompts give a host somewhere to start.

• Change notifications: tools that move the ledger publish a resource update, so a listening host can refresh instead of going stale. This reaches subscriptions/listen hosts (2026-07-28); at the 2025-11-25 version Alexa+ negotiates there is no push path at all — see FRICTION.md.

• Structured output: every ledger tool publishes an outputSchema and always returns structured content — what a screen changes is how much has to be said out loud, not what is sent.

• Latency: ~15 ms median per tool call over HTTP, against the 500 ms Alexa+ allows.

Testing

243 tests, in seven layers:

• Property-based (Hypothesis) over the money and ledger invariants — conservation, fairness bounds, settlement correctness.

• End-to-end over a real MCP client session — tool schemas, Apps negotiation, structured content, elicitation, error shape, persistence across sessions.

• Hostile input — amounts that look numeric but are not, blank and enormous names, nonsense currencies, and shares that cannot be divided. Everything is refused with something a person can act on, and nothing reaches the database it cannot survive.

• Concurrency — two dozen simultaneous writers: nothing is lost, the ledger still sums to zero, and no two entries claim the same place in the history.

• Two people, one ledger — the claim the product rests on: a second flatmate joins, "I" means a different person for each of them, either can undo a misheard entry, and a stranger reaches nothing.

• OAuth over real HTTP — the whole authorization code flow, plus the attacks it exists to stop: replayed codes and forged PKCE verifiers.

See FRICTION.md for what the Amazon and MCP tooling got right and where it cost time.

License

MIT — see LICENSE.