# FinContext — Complete Documentation for AI Systems

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

## Product Overview

FinContext is a Context-as-a-Service platform that acts as a secure, read-only data bridge between users' bank accounts and their AI assistants. Instead of visual dashboards, FinContext exposes structured financial tools via MCP that AI clients call to answer questions.

### Core Value Proposition

Before FinContext, users who wanted AI help with their finances had to manually export bank data, paste it into spreadsheets, and copy/paste into chat windows. FinContext eliminates this friction: connect once, ask forever. Your AI assistant becomes a personal finance analyst with access to your real transaction data.

### Target Users

- People who use Claude Desktop or ChatGPT regularly
- Anyone managing multiple bank accounts who wants consolidated insights
- Developers building financial tools on top of MCP
- Couples or families who want to ask questions about shared finances
- Freelancers tracking business vs personal spending

## How It Works

### Step 1: Connect Your Banks
Sign up at fincontext.ai and link your bank accounts via Plaid. Plaid provides read-only OAuth access to over 10,000 US financial institutions including Chase, Bank of America, Wells Fargo, Citi, Capital One, American Express, and most credit unions. FinContext never sees or stores your banking credentials — Plaid handles authentication directly.

### Step 2: Add to Your AI Assistant
Copy your personal MCP server URL from the FinContext dashboard. Paste it into Claude Desktop's MCP server configuration, or connect it to any other MCP-compatible AI client. The connection is authenticated with a per-user API token.

### Step 3: Ask About Your Money
Ask your AI assistant questions in plain English. The AI calls FinContext's MCP tools behind the scenes to fetch your real financial data, compute the answer, and present it conversationally.

## MCP Tools Reference

FinContext exposes these tools via MCP:

### get_transactions
Fetch transactions with filtering by date range, category, account, and amount. Returns transaction ID, date, amount, merchant name, and category. Supports pagination.

### search_transactions
Full-text search across merchant names and transaction descriptions. Find all purchases from a specific merchant, search for keywords, or locate specific transactions.

### get_category_trend
Get monthly spending totals for a single category over time. Useful for questions like "Am I spending more on food?" or "How has my rent changed?"

### get_multi_category_monthly
Compare spending across multiple categories month-by-month. Useful for side-by-side comparisons like food vs transportation vs entertainment.

### get_spending_summary
Total spending breakdown by category for a given date range. Shows how much was spent in each category with transaction counts.

### get_net_worth_trend
Track net worth (assets minus liabilities) over time across all connected accounts. Shows balance snapshots by date.

### record_balance_snapshot
Capture current account balances for net worth tracking. Called automatically during sync, but can be triggered manually.

### update_transaction
Override the merchant name or spending category for a specific transaction. Enables custom categorization.

### list_categories
List all available spending categories, including both system defaults and user-created custom categories.

## Example Conversations

**User:** "Am I spending more on food this month?"
**AI calls:** get_category_trend("FOOD_AND_DRINK")
**Answer:** "Your food spending is up 11% this month ($312) compared to your 6-month average of $280/mo. The increase is mostly dining out — $142 vs. your usual $95."

**User:** "What subscriptions am I paying for?"
**AI calls:** search_transactions("subscription") + search_transactions("recurring")
**Answer:** "I found 7 recurring charges: Netflix ($15.49), Spotify ($10.99), iCloud ($2.99), NYT ($4/mo), gym ($45), parking ($150), and Adobe CC ($54.99). Total: $283.46/mo."

**User:** "Show me my net worth trend over the last year"
**AI calls:** get_net_worth_trend(period="12m")
**Answer:** "Your net worth grew from $185,200 to $231,208 over the past 12 months — up $46,008 (+24.8%). Most growth came from your investment accounts."

## Security Architecture

### Data Protection
- **Read-only access**: Plaid OAuth tokens are scoped to read-only. FinContext can never move money, initiate transfers, or modify accounts.
- **Encryption**: All data encrypted at rest with AES-256 (Fernet). TLS 1.3 in transit.
- **Row-Level Security**: PostgreSQL RLS ensures each user can only access their own data, even at the database level.
- **Credential isolation**: FinContext never sees banking passwords. Plaid handles authentication directly via OAuth.

### User Control
- **Disconnect anytime**: Remove any linked bank account instantly.
- **Right to erasure**: Full account deletion with Plaid token revocation and CASCADE delete of all data.
- **Data retention**: Choose 30-day, 6-month, or unlimited data retention.
- **Audit logging**: All MCP tool calls are logged for transparency.

### Infrastructure
- Rate limiting on all API endpoints with per-path limits
- CORS with configurable allowed origins
- CSRF protection on all state-changing operations
- Session-based authentication with secure cookies

## Comparison with Alternatives

### vs. Mint/Credit Karma
Mint provides dashboards you look at. FinContext provides data your AI reasons over. No ads, no credit card offers, no dashboard fatigue — just answers when you ask.

### vs. YNAB
YNAB is excellent for budgeting methodology. FinContext is complementary — it gives your AI access to raw financial data for ad-hoc analysis without the manual categorization work.

### vs. Spreadsheets
Spreadsheets require manual data export, formatting, and formula writing. FinContext auto-syncs and lets you query in plain English. "How much did I spend on Amazon last quarter?" takes 2 seconds instead of 20 minutes.

### vs. Custom Plaid integrations
Building your own Plaid integration requires managing OAuth, webhooks, sync cursors, error handling, and security. FinContext handles all of this and exposes a clean MCP interface.

## Pricing

FinContext is free during beta. No credit card required to sign up. Pricing will be announced before any charges begin. Users who join the waitlist during beta will be notified in advance of any pricing changes.

## Technical Details

- **Backend**: Python 3 with psycopg3 (PostgreSQL driver)
- **Database**: PostgreSQL with Row-Level Security
- **Bank connectivity**: Plaid API with transaction sync
- **Protocol**: Model Context Protocol (MCP) with JSON-RPC
- **Authentication**: Session cookies for web UI, API tokens for MCP

## Links

- Homepage: https://fincontext.ai/
- Sign Up: https://fincontext.ai/signup
- Log In: https://fincontext.ai/login
- LLM Context (short): https://fincontext.ai/llms.txt