# Walletguide for AI agents

> Walletguide tracks one person's wealth: bank and brokerage accounts, property, crypto and anything else they own, with the transactions behind them, cash flow reports and plans. If a person asked you to set up Walletguide for them, follow "Set up Walletguide" below step by step, and ask them before you install anything or change data. The rest of this page lists the tools, what you may do and what stays with the person. Rendered version: https://walletguide.com/agents. People connecting their own assistant: https://walletguide.com/agents#connect

## Set up Walletguide

### 1. Connect the Walletguide MCP server

First check whether you already have Walletguide tools: `get_started`, `wallets_list` and so on (in Claude Code they're named `mcp__walletguide__…`). If you do, call `get_started` and go to step 3.

Address: https://mcp.walletguide.com (remote MCP over Streamable HTTP, OAuth 2.1). Clients discover the sign-in flow from the address itself, so no API key is needed. The person signs in, or creates a free account, when the server is added (step 2). Until then the server shows as needing sign-in and its tools don't show up.

Use the instructions for the client you are running in:

- Claude Code, in a terminal or in the Claude desktop app: run `claude mcp add --scope user --transport http walletguide https://mcp.walletguide.com`. The server shows as needing sign-in, and you get a `mcp__walletguide__authenticate` tool for it (search for it if your tools load on demand). Call it: it returns a sign-in link. Give the person that link to click. Once they've signed in, the Walletguide tools show up; if they don't, ask the person to start a new session. Only if that tool is missing, ask them to type `/mcp`, pick walletguide and authenticate. Don't run `claude mcp login` from your own shell tool: it needs an interactive terminal.
- Codex CLI: run `codex mcp add walletguide --url https://mcp.walletguide.com`, then `codex mcp login walletguide`. The tools show up in a new session.
- Gemini CLI: run `gemini mcp add --transport http walletguide https://mcp.walletguide.com`, restart, then `/mcp auth walletguide`.
- VS Code: run `code --add-mcp '{"name":"walletguide","type":"http","url":"https://mcp.walletguide.com"}'`.
- Cursor: ask the person to open cursor://anysphere.cursor-deeplink/mcp/install?name=walletguide&config=eyJ1cmwiOiJodHRwczovL21jcC53YWxsZXRndWlkZS5jb20ifQ%3D%3D, or add the `walletguide` entry to `mcpServers` in .cursor/mcp.json. If the file exists, merge it in and keep the other servers:

```json
{
  "mcpServers": {
    "walletguide": { "url": "https://mcp.walletguide.com" }
  }
}
```

- ChatGPT: you can't add apps yourself. Send the person to https://walletguide.com/agents#chatgpt, which walks them through it: in ChatGPT on the web they open Settings, then Apps, turn on Developer mode under Advanced settings (paid plans), click "Create app", name it Walletguide, paste https://mcp.walletguide.com and choose OAuth. Then they start a new chat with the app enabled.
- Claude (web, desktop, mobile): you can't add connectors yourself. Send the person to https://walletguide.com/agents#claude, which walks them through it: open https://claude.ai/customize/connectors, click "Add custom connector", name it Walletguide and paste https://mcp.walletguide.com. Then they start a new chat with the connector enabled.
- A client that only runs local (stdio) servers: bridge with `npx -y mcp-remote https://mcp.walletguide.com` (a third-party package).
- Scripts and CI: skip OAuth and send a wallet's API key (`wg_…`) as the bearer token on the same endpoint. A key reaches one wallet and can't create wallets or ask for access requests.
- No MCP support, or sign-in won't work in your client: use the CLI (below).

If the person has to start a new session before the tools appear, tell them to paste this there, so the new session picks up where you left off: "Continue setting up Walletguide. Instructions for AI agents: https://walletguide.com/agents.md"

#### No MCP: the walletguide CLI

The `walletguide` command-line client covers the same REST API and signs in from your own shell:

```sh
npx -y walletguide@latest login --scopes "openid profile email offline_access walletguide:read walletguide:write walletguide:admin walletguide:create_wallets"
```

It prints a sign-in link, opens the browser and waits until the person has signed in (they can sign up on that page). The browser then sends them back to a listener on 127.0.0.1, so this only works when the person's browser runs on the same machine as your shell. In a cloud sandbox, a container or over SSH, use the MCP connection instead. Leave out `walletguide:admin` or `walletguide:create_wallets` if the task doesn't need them (step 2). Then `npx -y walletguide wallets list`. The commands follow the routes (`walletguide assets list`), and `--help` on any of them shows the flags. Docs: https://docs.walletguide.com/developers/cli

### 2. Sign in or sign up

Sign-in starts when the server is added, or in Claude Code when you call its authenticate tool (step 1). Before that, tell the person what the page will ask (below). It opens in their browser, where they sign in, or create a free account and confirm their email address, and approve the connection. You can't do this step for them.

On that page, read access is always granted, and the last two options below appear only if your client asks for them. For an account created in the last day (someone who signed up to connect you) every option starts ticked; for an older account they start unticked. Tell the person what each one is for, so they can decide:

- "Add and change data in your wallets" (`walletguide:write`): the setup work in step 5 (adding assets and transactions, categorizing, merchants, tags, plans and scenarios). Without it you only read.
- "Change wallet settings and manage bank connections" (`walletguide:admin`): renaming a wallet, changing its currency or image, bank connect and reconnect links, and refreshing bank connections. It also lets you ask the person to approve invitations, member changes, API keys and deleting a wallet, which you never do yourself.
- "Create wallets for you" (`walletguide:create_wallets`): only needed if they have no wallet yet, or want a sample wallet. Their first wallet starts their 14-day free trial, as it would in the app.

You only get the tools of the options they allow, so help them choose for the whole task. If your client doesn't ask for an option, the steps that need it fall back to the person doing them in the app at https://app.walletguide.com. If you need an option later, `get_started` lists what's missing and the tools each option adds: tell the person which one and why. They disconnect Walletguide (in their client, or in the app under User settings, then Connected apps) and connect again with it ticked. A call that answers `insufficient_scope` means the same.

The person's role in the wallet still applies: a viewer can't make changes, whatever they tick. A 403 without `insufficient_scope` means the role doesn't allow the call, and signing in again won't help. Tell the person which permission is missing and that the wallet's owner can change their role in the app. Don't retry.

### 3. Find or create the wallet

Call `wallets_list`.

- One or more wallets: confirm with the person which one to use, and pass its id as `walletId` from then on.
- Empty list: the account has no wallet yet. If you have the `wallets_create` tool, ask the person for the wallet's name and the currency to report in, confirm them, then create it with an `idempotencyKey` you generate (a retry with the same key returns the same wallet). Don't guess the currency: every total is converted into it. If they want to try Walletguide first, create a sample wallet instead (`type` `sample`, with `addSampleData` for example data, which fills in the background: follow it in `backgroundTasks_list`). Tell them first that a sample wallet is deleted after 14 days with everything in it, so it is no place for their real data. Without the tool, send the person to https://app.walletguide.com to create the wallet (about a minute), then call `wallets_list` again.

Read the wallet's `baseCurrency` before you interpret any total.

### 4. Connect the banks

The person connects their banks in the app: they pick their bank and sign in with it there, through finAPI for banks in Europe or Plaid for the US and Canada. You never see their bank login, and you never ask for it in the chat. Call `integrations_connect_link` and give the person the link: it opens the bank dialog in the app and doesn't expire. Then poll `assets_list` for the new bank accounts.

A bank-connected asset whose `bankConnection.status` is `error` or `expired` needs the person again: call `integrations_connect_link` with its `assetId` for a reconnect link. `integrations_sync` fetches new transactions and balances now instead of at the next scheduled refresh; it lists assets that are already refreshing in `alreadyPending` and those that need a reconnect in `needsReconnect`. Follow the refresh in `backgroundTasks_list`.

Both tools need "Change wallet settings and manage bank connections". Without it, the person connects banks in the app themselves.

Assets a bank doesn't know about (property, a car, a private loan, an account at an unsupported bank) you can add with `assets_create`, and their transactions with `transactions_bulk`. Importing a bank's CSV export stays with the person, in the app.

### 5. Do the setup work

This is where you save the person the most time. With "Add and change data in your wallets" (and a role that allows changes):

- Categorize transactions. `transactions_search` finds them, `transactions_bulkEdit` applies a category or merchant to many at once, and `transactions_bulkAddTags` adds tags. Create missing categories and merchants with `categories_create` and `merchants_create`, and show the person what you plan to apply before you apply it.
- Add the assets and holdings the banks don't cover (step 4), and value updates for assets without a bank (`totalValueUpdates_create`).
- Plan ahead with `planItems_create` and scenarios (`scenarios_create`) when the person asks for it.
- Then answer their questions. Take every figure (net worth, cash flow, profit and loss, category averages, asset performance) from a `data_*` tool. Never add up transactions yourself: pagination and transfers between two of their own accounts make that wrong.

The server sends its own conventions when you connect (signed amounts, transfers are two transactions, calendar dates). Follow them.

### What stays with the person

- Signing in with their bank (step 4), and importing a bank's CSV export in the app.
- Inviting someone, changing a member's role or permissions, removing a member, creating an API key and deleting a wallet. With "Change wallet settings and manage bank connections" you can ask for these with the `access_requests_*` tools. Each one returns an `approvalUrl` where the person, signed in, approves or declines the exact change; `access_requests_get` tells you the outcome. Never say the change is done before it reads `succeeded`. A request expires after an hour unanswered, and at most 10 wait per person and wallet. A new API key's secret is shown to the person only, never to you. Deleting a wallet needs the owner, who types the wallet's name.
- Anything their role doesn't allow: the wallet's owner changes roles in the app.

Walletguide never moves money.

### Pricing

14-day free trial, no credit card. Plans: https://walletguide.com/pricing

## Tools

`get_started` says how you are connected, which consent options the person didn't tick, and which tools each would add. Call it whenever a tool you need is missing.

Read tools for wallets, assets, asset groups, transactions (including security and crypto transactions), categories, merchants, tags, transfers, files, comments, plans and scenarios, and one `data_<slice>` tool per report (`data_netWorthTimeSeries`, `data_networthAtDate`, `data_profitLoss`, `data_cashFlowByCategory`, `data_categoryAverages`, `data_assetPerformance`, `data_planVsActual`, ...), plus `data_batch` for several slices in one round trip.

Write tools (create, update, delete on those resources) need "Add and change data in your wallets" (`walletguide:write`) or an API key that allows them. Wallet settings and bank connections (`wallets_patch`, `integrations_connect_link`, `integrations_sync`) and the `access_requests_*` tools need `walletguide:admin`; `wallets_create` needs `walletguide:create_wallets`. Everything stays bounded by the person's role in the wallet. A connection lists only the tools its grant allows.

Full reference, with the tool counts per connection: https://docs.walletguide.com/developers/mcp/tools

## Build your own

- REST API: base URL https://api.walletguide.com, JSON, resources under /wallets/{walletId}/..., one data endpoint per report slice. Overview: https://docs.walletguide.com/developers/api/overview
- OpenAPI 3.1 document: https://api.walletguide.com/openapi.json (each operation lists the permission an API key needs and the OAuth scope an app must hold)
- CLI: npm package `walletguide`. `walletguide login` (OAuth) or WALLETGUIDE_API_KEY, then e.g. `walletguide data netWorthTimeSeries --period ytd`. Docs: https://docs.walletguide.com/developers/cli
- API keys: https://docs.walletguide.com/developers/api/api-keys
- Authentication and scopes: https://docs.walletguide.com/developers/api/authentication

## Discovery

- https://walletguide.com/llms.txt: site overview and page index
- https://docs.walletguide.com/llms.txt: page-by-page docs index
- https://api.walletguide.com/openapi.json: OpenAPI document
- https://mcp.walletguide.com/server-card: MCP server card, found from https://walletguide.com/.well-known/ai-catalog.json
- https://api.walletguide.com/.well-known/mcp: MCP server card in the MCP Registry's server.json shape
- https://api.walletguide.com/.well-known/api-catalog: RFC 9727 API catalog

## Permissions

- API keys belong to one wallet and carry a role (viewer, editor) or an explicit permission list. Wallet settings and bank connections only when the list names `wallet:manage` or `integrations:manage`; a key never manages members or API keys, never creates wallets and never asks for access requests. Created and revoked in the app under the wallet's settings, API keys.
- OAuth grants carry `walletguide:read` and, if ticked, `walletguide:write`, `walletguide:admin` and `walletguide:create_wallets`, always intersected with the person's role in each wallet.
- Members, API keys and deleting a wallet are never changed by an agent: it can ask (`access_requests_*`), and the person approves the exact change in the app.
- Disconnecting the app under User settings, Connected apps takes effect on the next request.
- Walletguide is hosted in Frankfurt and reads from banks through licensed providers. It cannot move money. More: https://walletguide.com/security

## Other clients

- Connectors set up with the earlier address, https://api.walletguide.com/mcp, keep working.
- Connect guide for developers: https://docs.walletguide.com/developers/mcp/install-remote

## Contact

support@walletguide.com