What is the MCP endpoint?
https://worthbase.app/mcp
- Transport: Streamable HTTP. The server is stateless: each request is handled on its own and responses are JSON, with no session id to keep.
- Server name:
worthbase. The server sends instructions on initialise that tell the agent how to read, write and stay safe; well-behaved clients pass them to the model. - Clients: Claude (web, desktop, mobile), ChatGPT (developer mode), Cursor, Claude Code and any client that supports remote MCP servers with OAuth. Clients that only support local stdio servers can't connect directly. Per-app steps are in the setup guide.
claude mcp add --transport http worthbase https://worthbase.app/mcp
How does authentication work?
OAuth 2.1 (authorization code + PKCE), with Clerk as the authorization server. Clients identify themselves with a Client ID Metadata Document, so there's no client ID or secret to paste, and they discover everything else from the metadata at /.well-known/oauth-protected-resource.
- An unauthenticated request to
/mcpgets401with aWWW-Authenticate: Bearer resource_metadata="…"header. - The protected resource metadata (RFC 9728) is at
/.well-known/oauth-protected-resource(also/.well-known/oauth-protected-resource/mcp). It names the resourcehttps://worthbase.app/mcp, the authorization server, and the scopesopenid profile email offline_access. - For clients that look on the resource's origin,
/.well-known/oauth-authorization-serverserves the authorization server metadata. - The user signs in and approves. The client sends the access token as a bearer header. Every request checks issuer, audience (the
/mcpresource, so tokens minted for other resources are refused) and expiry.
A token acts as the signed-in user, with that user's role in each workspace. The workspace needs an active trial or subscription for the agent to read or change it.
Which tools does the server expose?
Twenty-eight tools. Most take an optional workspace (a ws_… id); without it, the user's default workspace is used. IDs are prefixed ULIDs (itm_, txn_, val_, bat_, pty_, acc_ and so on) and every result includes them. Tools carry MCP annotations (read-only, destructive, open-world) so clients can set approval rules.
Read tools (read-only)
| Tool | What it returns |
|---|---|
whoami | The signed-in user, their workspaces and roles, their default workspace, and invites waiting for them. |
get_overview | Parties, accounts, item counts, net worth headline, stale items, open reconciliation mismatches, price run status and recent batches. Call it first. |
get_net_worth | Assets, liabilities, net worth, investable and cash on a date, optionally for one party and broken down by class, kind, party, account or item. workspace: "all" gives the user's own share across every workspace. |
get_history | Net worth at each month, quarter or year end between two dates, with breakdowns and the change over the period. Points without values are marked partial. |
list_items | Assets and liabilities with owners, notes and current position: units, price, value, cost base, unrealised gain, staleness. |
get_item | One item in full: position, owners, links, transactions, valuations, open lots, reconciliations and the batches that wrote them. |
get_performance | Start and end value, money in and out, income, gain, simple return and money-weighted annual return (XIRR), per item and in total. |
get_debt_report | Every loan with balance, security, offsets and purpose, plus each property's value, secured debt, equity and LVR. |
get_goals | Goals with progress, the last 12 months' trend, the projected date and whether it's on pace. |
get_losses | Tracked losses carried forward (business, capital, rental), with the year each arose, the amount, what's been used and what's left per party. Not counted in net worth. |
simulate_sale | What selling some or all of a holding, or a whole property or business, would do: proceeds, lots consumed (FIFO or specific), gain or loss per party and the resulting position. No tax. Never writes. |
list_batches | Recent writes, newest first, with source document, client and status, for review or undo. |
search_instruments | Find a listed security (Yahoo Finance) or crypto coin (CoinGecko) by name or code, to get the symbol, exchange or CoinGecko id for an item. |
Write tools
| Tool | What it does |
|---|---|
record | The main write. Creates accounts and items and records transactions, transfers, valuations, prices and reconciliation checks together. Previews by default. |
commit | Saves a previewed batch by its preview_id. Fails with preview_stale if the ledger changed in a way that alters the result. |
undo | Reverses a whole committed batch. Previews by default; refuses if the result would leave the ledger inconsistent. |
reconcile | Checks a statement figure (units, value or cost base) against the calculated one on a date and records match or mismatch. |
update_item | Changes an item's name, class, subtype, account, currency (before any history), dates, flags, notes or attributes. Undoable. |
set_owners | Replaces an item's ownership split (must add to 100). Correcting history needs correction: true. |
link_items | Links a loan to the property it's secured by, an offset account to a loan, or a loan to what it funded; remove: true unlinks. |
archive_item | Removes one item from the balance sheet; gains it already realised stay on record. Undoable. |
void | Removes specific transactions, valuations or prices. Refuses if the ledger would no longer replay. Undoable. |
set_goal | Creates, changes or archives a net worth or debt goal. Undoable. |
set_loss | Records, changes or archives a tracked loss (owner, kind, year it arose, amount, amount used, note). Undoable. |
refresh_prices | Starts fetching the latest prices for a workspace in the background. Prices also refresh daily on their own. |
save_workspace | Creates a workspace, or renames one. |
save_party | Creates or updates a legal owner: an individual, company, trust, SMSF or partnership. |
save_account | Creates or updates an account at an institution: brokerage, bank, exchange, wallet, retirement fund or loan. |
members | Lists members and invites, invites by email, changes roles, removes members and revokes invites. |
accept_invite | Joins a workspace the user was invited to, by invite code or invite id. |
Roles apply to every call: viewers can read, editors can write data, and admins can also manage parties, accounts and members.
Which resource and prompts are there?
guide://recording(resource, Markdown): how to turn statements, spreadsheets and conversation into items and rows, with worked examples and known import header aliases. Agents should read it before their first import.import_document(prompt): import a statement, CSV or spreadsheet: map it, preview, and commit on confirmation. Optionaldescriptionargument.monthly_update(prompt): go through stale values and record new ones.
How do writes work: preview, commit, undo?
Every write is a batch. record runs the batch in a transaction that is rolled back and returns a preview: new items, rows, duplicates, conflicts, warnings and the net worth change, plus a preview_id valid for 30 minutes. The agent shows the preview to the user and calls commit only after they confirm; the batch is then saved in a single transaction. Items created in a batch commit together with their transactions, and ids in a preview's created don't exist until commit.
- Idempotent imports. Each row carries a stable
external_ref(an order id, or a file hash and row index). Re-importing the same file skips rows already recorded. - No hard deletes. The tools archive, void and undo; nothing is permanently deleted through MCP.
- Safe undo. Undo replays the ledger without the batch and refuses if the result would be invalid, for example if a later sale needs a buy being removed. There's no force option.
- Keep batches small. One per source document or group of related items, so undoing one mistake never touches unrelated data.
- Provenance. Every batch records its source, the user and the client that wrote it.
Why are numbers decimal strings?
Money, units, prices and exchange rates go in and come out as decimal strings, such as "1234.56" or "0.00350000", never JSON numbers, so nothing is lost to floating point. Amounts are the statement's figures, excluding fees, always positive; the transaction type sets the direction. Every amount is labelled with its currency. Rows in another currency can omit the exchange rate, and the ECB rate for that date is used and reported. The agent should never add up, convert or compute gains itself: every figure it quotes comes from the server, and every write result includes net worth before and after.
What do errors and limits look like?
Errors come back as a tool error with a JSON body: a machine-readable code, a message that says how to fix the problem and, where it applies, the field at fault. refresh_prices runs at most once per 15 minutes per workspace, and instrument search is rate-limited per user. Gains and losses are reported; the server doesn't calculate tax.
Is there a REST API?
Not publicly yet. A REST API with scoped workspace API keys, for apps that aren't MCP clients, is coming later. Today, programmatic access is through the MCP server with OAuth.
For a plain-text summary of the product and site written for language models, see /llms.txt, or /llms-full.txt for the full text of every page.
Questions
Can I build my own agent on the Worthbase MCP server?
Yes. Any MCP client that supports remote servers over Streamable HTTP with OAuth can connect, including agents built with an MCP SDK. The user signs in and approves access, and the agent acts with that user's role.
Does the server do any arithmetic in the model?
No. All arithmetic runs on the server with exact decimals. The server instructions tell the agent to quote figures from tools like get_net_worth and simulate_sale rather than compute them.
How does the server handle prompt injection in documents?
Text from documents and text stored in Worthbase is data, not instructions. The server instructions tell the agent to ignore instructions found in it and to confirm with the user before committing, undoing, archiving or voiding. MCP clients also ask for approval before tool calls.
Is there an OpenAPI spec or API key?
Not yet for public use. API keys and a public REST API are planned; until then, use the MCP server.
