# BankBridge — features

## The twelve tools

### Depository + credit

1. **list_accounts** — balances and types for all connected accounts.
2. **get_account** — detail lookup by ID.
3. **list_transactions** — filter by date, amount, category, or account with pagination.
4. **search_transactions** — substring match on name + merchant_name.
5. **get_spending_summary** — group spend by category, merchant, month, or week.
6. **get_recurring_charges** — pattern-detected subscriptions and utilities.
7. **get_monthly_cashflow** — income vs expenses with top sources + categories.
8. **get_merchant_history** — every charge for one merchant plus aggregate stats.
9. **list_categories** — categories present in the user's data.

### Investment

10. **list_holdings** — current positions with gain/loss.
11. **list_investment_transactions** — buys, sells, dividends, fees.

### Connection

12. **connect_bank** — returns a URL that auto-opens the bank-link flow, so the agent can initiate a new connection itself when the user asks.

## 29 host integrations

Pre-filled snippets + 1-click deeplinks wherever possible.

### Anthropic (4)

- Claude Code (CLI + plugin marketplace)
- Claude Desktop (Custom Connector)
- Claude.ai web (Custom Connector)
- Claude Cowork

### OpenAI (7)

- ChatGPT + Memory
- ChatGPT Apps SDK
- ChatGPT Enterprise (admin Connector Registry)
- Codex CLI
- Codex Cloud
- OpenAI Responses API (first-class MCP tool type)
- OpenAI AgentKit (Agents SDK + Agent Builder visual flow)

### Google (3)

- Gemini CLI
- Gemini Code Assist
- Vertex AI (native MCP in the Gemini SDK)

### IDEs & editors (8)

- Cursor (deeplink install)
- GitHub Copilot (VS Code deeplink install)
- Windsurf
- Continue.dev
- Cline / Roo
- Zed
- JetBrains Junie
- Kiro

### Other hosts (7)

- LM Studio (deeplink install)
- Warp
- Raycast
- Goose
- Perplexity
- opencode
- OpenClaw

### Direct

- Raw HTTP MCP endpoint (any MCP-compliant client)

## Authentication models

### Static bearer key

`Authorization: Bearer bbk_…`. Generate in `/dashboard/settings`. Revoke + rotate any time.

### OAuth 2.1

Full provider: Dynamic Client Registration (RFC 7591), PKCE, token refresh, and discovery metadata at `/.well-known/oauth-protected-resource` + `/.well-known/oauth-authorization-server`.

## Privacy architecture

### What BankBridge stores

- User auth rows (email, session tokens)
- Subscription state (Stripe customer + subscription IDs)
- Per-user API keys (SHA-256 hashed — raw key never persisted)
- Per-bank access tokens (AES-256-GCM encrypted at rest)

### What BankBridge does NOT store

- Account balances
- Transaction history
- Investment holdings
- Any bank-reported metadata beyond the institution name (used for dashboard display)

Every MCP tool call fans out in real time via the upstream aggregator. Retention of financial data is zero.

## Cancellation safety (six layers)

Every bank connection must be removed when a user's subscription ends, otherwise we keep getting billed by the upstream aggregator. Six independent defenses converge on a single cleanup helper:

1. Primary `customer.subscription.deleted` webhook
2. Sync-time guard for inactive users
3. MCP-time guard (fire-and-forget cleanup for inactive requests)
4. Nightly reconciliation cron (orphan + quantity-drift fixes)
5. `invoice.payment_failed` → Stripe retry → eventual layer-1 fire
6. Audit log of every removal for billing-dispute evidence

## Technical stack

- Next.js 16 + React 19 + TypeScript 5 on Bun runtime
- SQLite (better-sqlite3 via Knex) with WAL — auth, subscriptions, access tokens, API keys only
- NextAuth v5 magic-link
- Bank aggregator (Transactions + Investments products)
- Stripe subscription (quantity = bank count)
- Resend for transactional emails
- `@modelcontextprotocol/sdk` with `StreamableHTTPServerTransport`

Deployed on DigitalOcean via PM2. Let's Encrypt for TLS. nginx reverse proxy.