goldberry
MCP server (for AI tools)
Goldberry can speak the Model Context Protocol, so tools like Claude can look at balances and, if you allow it, post money. It is off by default. See ADR 0016.
Turn it on
- Set
GOLDBERRY_MCP_ENABLED=true(Compose:environment; Helm:--set mcp.enabled=true) and restart. - Make an API token. Give an AI tool
readfirst. - Point the tool at
https://your-goldberry/mcp(streamable HTTP) with the headerAuthorization: Bearer gb_….
For Claude Code: claude mcp add --transport http goldberry https://goldberry.example.com/mcp --header "Authorization: Bearer gb_…".
The server is stateless and every call is checked against the token, so revoking a token cuts a tool off at once. It shares the API's limits.
What tools a token sees
Tools above a token's scopes are not listed, and can't be called.
| Scope | Tools |
|---|---|
read |
get_household, list_kids, get_kid, get_ledger, list_goals, list_requests |
write |
add_jar, rename_jar, set_split, create_goal, archive_goal |
money |
post_entry, post_entries, reverse_entry, decide_request |
Kids are named by username (ava). Amounts are minor units (cents for USD).
Money tools look before they leap
- They default to a dry run.
post_entry,post_entries,reverse_entryanddecide_requestshow what would happen and change nothing until the tool is called again withdry_run: false. A good prompt is "show me what you'd post, and wait for my OK." - Postings can be backdated. Give
post_entryor an item ofpost_entriesaneffective_at(YYYY-MM-DDor RFC 3339) to load money tracked elsewhere, like "ava's opening balance is $125 as of 2026-01-01." It can't be in the future. See backdating. - Postings need an
idempotency_key. Reusing a key retries safely: nothing posts twice. The tool descriptions tell the model to pick stable keys that name the payment. - Batches are all-or-nothing (up to 100 entries); an error names the item to fix.
- Everything is audited with the token's label, under Account history on the kid's page (People → the kid):
api.entry · Mom via “Claude”.
Moving money between jars isn't offered over MCP; use the API for that.
Safety notes
- Treat a
moneytoken like the parent's PIN: anyone holding it can post as that parent. Revoke it when a tool is retired. - MCP exposes the same data as the API, including parents' private notes on entries.
- Put Goldberry behind TLS, as for the rest of the app.