# FinContext

> FinContext is an MCP (Model Context Protocol) server for personal finance. It connects your bank accounts to Claude, ChatGPT, and any MCP-compatible AI assistant via Plaid. Ask questions about your money in plain English and get real-time answers from your actual financial data.

## What FinContext Does

FinContext acts as a secure, read-only data bridge between your bank accounts and AI assistants. It exposes 10 MCP tools (`balances`, `transactions`, `categories`, `update`, `stat`, `sync`, `link_bank`, `status`, `feedback`, `help`) that AI clients can call via MCP to answer your financial questions using real data.

## How It Works

1. Sign up and link your bank accounts via Plaid (read-only, 10,000+ US banks supported)
2. Connect your AI assistant using your MCP server URL
3. Ask questions in plain English — the AI calls FinContext tools to get real answers

## Agent Authentication

New users: `POST /api/agent-signup` with `{"email", "password", "us_resident": true, "display_name"?, "agent_name"?}` — returns `api_token` and `mcp_endpoint`. `us_resident` must be literal boolean `true`; FinContext is US-only and this field is a required residency attestation. `agent_name` is an optional self-declared label for the agent (e.g. "Claude Desktop"); it becomes the API token's name so users can audit and revoke individual agent sessions.

Existing users: `POST /api/agent-login` with `{"email", "password", "agent_name"?}` — returns a new `api_token` and `mcp_endpoint`. Each login mints a new token; `agent_name` labels it.

Both endpoints return Bearer tokens for MCP authentication. Store the token securely — it is shown only once.

Security notification: each successful sign-in — whether via `POST /api/agent-login` (API token flow) or `POST /oauth/token` with `grant_type=authorization_code` (OAuth Connector flow) — sends a security notification email to the account owner including the agent/client name, timestamp, IP, device, and a link to revoke the connection. Token refreshes do not trigger a notification.

## Key Features

- MCP server for personal finance data
- Plaid bank connectivity (read-only OAuth, never stores credentials)
- Works with Claude Desktop, Claude.ai, ChatGPT, and any MCP client
- Real-time transaction search, spending trends, net worth tracking
- Encrypted at rest (Fernet), TLS in transit
- Full user data control: disconnect banks or delete all data anytime
- Custom category management and transaction overrides

## Security

- Read-only Plaid connections — can never move money or initiate transfers
- Encrypted at rest (Fernet), TLS 1.3 in transit
- Row-level security (PostgreSQL RLS) isolates each user's data
- Right-to-delete: full account deletion with Plaid token revocation
- Data retention controls: choose 30 days, 6 months, or unlimited

## MCP Tools

FinContext exposes 10 MCP tools. Each tool accepts its own arguments directly; MCP 2024-11-05 annotations (`readOnlyHint`, `openWorldHint`, etc.) are set per tool so clients can auto-approve reads and prompt only on writes.

- `balances` — Get current account balances
- `transactions` — Search and filter transactions by date, category, account, amount
- `categories` — List all available spending categories
- `update` — Override merchant name or category for a transaction
- `link_bank` — Generate a Plaid Hosted Link URL to connect a bank account
- `status` — Check if bank accounts are linked
- `stat` — Run SQL SELECT queries against virtual `transactions` and `balances` tables. Supports GROUP BY, HAVING, aggregates (SUM, AVG, COUNT, STDDEV), date functions (date_trunc, EXTRACT), and more. Use `DESCRIBE transactions` to see the schema. Max 1000 rows, 5s timeout.
- `feedback` — Send bug reports, feature requests, or praise directly to the FinContext team. Takes `message` (required, up to 4000 chars) and optional `type` (bug / feature / praise / question / general). Rate limited to 5 per hour per user. Reach support directly: support@fincontext.ai.
- `sync` — Pull latest transactions and balances from Plaid's cache into FinContext. Runs asynchronously and returns immediately with status='started'. Wait ~30 seconds then check balances or transactions for refreshed data. Rate limited to 5 per 5 minutes per user. Note: this catches FinContext up to what Plaid already has — it does not force Plaid to re-poll the bank.
- `help` — Show available tools and detailed usage. Pass `subcommand` to get details for a specific tool.

## Pricing

- Free during the public beta — no credit card required, all features unlocked
- $4.99/month for the General tier is planned after beta (via Stripe Checkout)
- During beta nothing expires; full access for everyone
- Manage billing via Stripe Customer Portal at /account

## Links

- [Homepage](https://fincontext.ai/)
- [Sign Up](https://fincontext.ai/signup)
- [Log In](https://fincontext.ai/login)
- [Extended documentation for AI](https://fincontext.ai/llms-full.txt): Complete product docs with examples, comparisons, and technical details