# Rise MCP — Agent Playbook

Drop this file into your agent's context (Claude Code skill reference, `AGENTS.md`
include, Cursor rules, OpenClaw workspace docs) to teach it how to work with Rise.

## What Rise MCP is

Rise is a personal-finance manager. The Rise MCP server exposes a user's accounts,
transactions, budgets, receipts (with line items, SKUs, and barcodes), spending
insights, and manually tracked assets/debts over the open Model Context Protocol.

- **Endpoint:** `https://mcp.rise.cirqul.com/mcp`
- **Transport:** streamable HTTP
- **Auth:** OAuth 2.1 (PKCE) with dynamic client registration — no API keys. Each
  connection is scoped to one Rise user; row-level security enforces that you only
  ever see that user's data.
- **No money movement:** there are no payment or transfer tools. Reads and
  bookkeeping writes (categories, budgets, receipts, manual accounts) only.

Quick setup per surface:

| Surface | How |
| --- | --- |
| Claude Code | `claude mcp add -s user --transport http rise https://mcp.rise.cirqul.com/mcp` — run as ONE line, then in a session: `/mcp` → rise → Authenticate (browser opens once) |
| Codex | `~/.codex/config.toml` → `[mcp_servers.rise]` with `url = "https://mcp.rise.cirqul.com/mcp"` |
| Cursor | `.cursor/mcp.json` → `{ "mcpServers": { "rise": { "url": "https://mcp.rise.cirqul.com/mcp" } } }` |
| OpenClaw | `openclaw.json` → same `mcpServers` shape as Cursor |
| ChatGPT | Settings → Apps & Connectors → developer mode → new connector with the endpoint URL |

Start every new connection with `whoami` to confirm the right Rise account.

## The six skills (server prompts)

These ship as MCP prompts on the server. In Claude Code they appear automatically as
`/mcp__rise__<name>` slash commands; other surfaces list them in their prompt picker.

| Skill | What it does | When to use |
| --- | --- | --- |
| `import-amazon-history` | Walks through exporting (or browsing) the user's Amazon order history and logging every order as a Rise receipt with line items. | Coding agents with browse/file access; first-time backfill or periodic catch-up. |
| `import-receipts-from-email` | Guided sweep of receipt emails into Rise receipts — totals, tax, line items, barcodes/SKUs when present. | After shopping trips, or as a recurring catch-up loop. |
| `categorization-review` | Question-driven cleanup of uncategorized transactions, grouped by merchant/description so one answer covers repeat purchases. Biggest dollar groups first. | Monthly sweep, or whenever the weekly check-in flags a backlog. |
| `weekly-checkin` | Budgets vs. actuals, spending insights, notable/unusual transactions, and what needs attention this week. | Weekly, any surface — great in chat assistants. |
| `net-worth-onboarding` | Sets up manually tracked assets and debts (home, vehicles, mortgages or loans held elsewhere) for a complete net-worth picture. | Once at setup; revisit when the user acquires or sells an asset. |
| `price-check` | What the user usually pays for a product, from receipt line-item history. | Ad-hoc, while shopping; works well in chat. |

## The four recurring loops

Each loop is a self-contained one-liner. Schedule them (Claude Code scheduled
agents, ChatGPT tasks, or plain cron invoking a CLI agent) or run on demand.

**Weekly money check-in** (weekly)

```text
Run my Rise weekly check-in (weekly-checkin): budgets vs. actuals,
spending insights, anything unusual this week, and what still needs
categorizing.
```

**Monthly categorization sweep** (monthly)

```text
Run a Rise categorization sweep (categorization-review) for last month:
walk me through uncategorized transactions grouped by merchant, then
apply my answers with set_transaction_category.
```

**Receipt catch-up** (after shopping trips, or weekly)

```text
Receipt catch-up: I have new receipts since last time. Run
import-receipts-from-email (and ask me for photos of paper receipts),
then log each with log_receipt including line items.
```

**Quarterly asset value refresh** (quarterly)

```text
Quarterly asset refresh: list my Rise manual accounts, ask me for
current values on my home and vehicles, and update each with
update_manual_account.
```

## Capability notes per surface

- **Coding agents (Claude Code, Codex, Cursor, OpenClaw):** can browse the web, run
  code, and read local files. Best for heavy data work — `import-amazon-history`,
  parsing CSV/OFX exports, bulk receipt sweeps, anything that starts from a file or
  a website.
- **Chat assistants (ChatGPT, Claude web/desktop):** conversational money work —
  `weekly-checkin`, quick categorization, logging a receipt the user dictates or
  photographs, `price-check`. They cannot browse the user's other accounts or read
  local files; when a job needs that, tell the user to hand off to a coding agent.
- **ChatGPT specifically:** Rise renders an inline PFM dashboard widget for
  overview/accounts/transactions/budgets/insights tools.

## Rules

1. **Always confirm before bulk writes.** Summarize what you are about to create or
   change (N receipts, N category updates) and get an explicit yes before applying.
2. **`user_category` wins.** `set_transaction_category` writes the user's own
   category, which overrides the bank-feed category everywhere. Never "fix" a
   user-set category back to the feed's value.
3. **Tag property transactions.** When a transaction or manual entry relates to a
   tracked asset, attach its property/asset tag (e.g. `1218-pine-harbor`) so
   per-property cost tracking stays accurate. Link debts to their assets
   (`linked_account_id`, e.g. a mortgage pointing at its property).
4. Start sessions with `whoami`; if it is not the expected account, stop and ask.
5. Prefer the built-in skills over improvising multi-step flows — they encode the
   grouping, ordering, and confirmation behavior Rise expects.