Setup guide & API reference

Setup & developer reference

Connect Claude, ChatGPT, or any MCP-compatible client to your bank accounts. Steps 1–4 below walk through the setup; the rest of the page is the full API and SQL reference for developers building on top of FinContext.

Free during the public beta. $4.99/month per user planned after beta. No usage metering, no per-call fees.

Read-only Plaid access. Row-level isolation in Postgres. Delete your data anytime. No data resale.

Create an account

Read-only bank data for analysis agents. Not for payments, transfers, or account actions.

Step 1 — Create an account

Sign up at /signup to get FinContext credentials. Step 2 covers picking the right auth model for your AI client. Building an agent that signs users up on their behalf? Use the programmatic flow below.

Programmatic signup (for agent developers)

Step 2 — Connect your AI client

Two auth models. Pick the row that matches your client, then jump to the matching setup path below.

Auth modelUse when your client isWhat you do
OAuth Claude Desktop, Claude.ai, ChatGPT, Hermes Agent Add a custom connector with the URL https://fincontext.ai/mcp and sign in. No tokens to copy. Setup steps: Claude Desktop & Web · ChatGPT · Hermes
Token Claude Code (CLI), mcp-remote, OpenClaw, custom MCP clients Generate a token at /api-tokens (sign in first if you haven’t) and paste it into the client config. Setup steps: Claude Code · mcp-remote · OpenClaw

Claude Desktop & Claude.ai Web (Custom Connector)

Steps:

  1. Open Claude Desktop or claude.ai → Settings → Connectors → Add custom connector.
  2. Enter https://fincontext.ai/mcp as the remote MCP server URL.
  3. Claude opens FinContext's authorize page in your browser. If you're not signed in yet, use the email and password you set at /signup.
  4. Click Approve. Claude receives an fco_ access token and completes setup.

ChatGPT (Custom Connector)

Steps:

  1. In ChatGPT, open Settings → Connectors. Don't see an Add / Create option? Open Settings → Apps & Connectors → Advanced settings and enable Developer mode.
  2. Click Create (or Add custom connector) and enter https://fincontext.ai/mcp.
  3. ChatGPT opens FinContext's authorize page. Sign in, click Approve.
  4. ChatGPT receives an fco_ access token and completes setup.

Claude Code (CLI)

Steps:

  1. Run: 
    claude mcp add --transport http --scope user fincontext https://fincontext.ai/mcp \
  --header "Authorization: Bearer fc_..."
  2. --scope user makes the connection available across all projects. Drop it for per-project scope.

mcp-remote Bridge (Claude Desktop fallback)

Steps:

  1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows): 
    {
  "mcpServers": {
    "fincontext": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://fincontext.ai/mcp",
        "--header",
        "Authorization: Bearer fc_..."
      ]
    }
  }
}
  2. Restart Claude Desktop.

Hermes Agent (CLI)

Steps:

  1. Add the server with OAuth: 
    hermes mcp add fincontext --url https://fincontext.ai/mcp --auth oauth
  2. Hermes opens FinContext's authorize page in your browser. Sign in with your /signup credentials and click Approve.

OpenClaw

Steps:

  1. Generate a token at /api-tokens (sign in first), then run: 
    openclaw mcp set fincontext '{
  "url": "https://fincontext.ai/mcp",
  "transport": "streamable-http",
  "headers": { "Authorization": "Bearer fc_..." }
}'
  2. Confirm it saved: openclaw mcp list should show fincontext.

Step 4 — Start querying

MCP Tools

FinContext exposes 10 MCP tools. Each tool accepts its own arguments directly; call help to discover any tool's parameters at runtime.

MCP Handshake

MCP clients connect via a standard JSON-RPC 2.0 handshake:

1. Initialize

POST /mcp
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

Returns server info, protocol version, and instructions listing all available tools.

2. List tools

{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

Returns all 10 tool definitions with their per-tool annotations (readOnlyHint, openWorldHint, etc.) and JSON Schemas.

3. Call a tool

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {
  "name": "help",
  "arguments": {}
}}

Start with the help tool to discover all tools and their parameters at runtime. Pass subcommand to get details for a specific tool:

{"name": "help", "arguments": {"subcommand": "stat"}}

SQL Analytics (stat)

The stat tool lets agents run SQL SELECT queries against virtual financial tables. Write standard PostgreSQL SQL; FinContext validates, rewrites, and executes it safely within the user's RLS scope.

Virtual Tables

Use DESCRIBE to discover schemas at runtime:

{"name": "stat", "arguments": {"query": "DESCRIBE transactions"}}

transactions (excludes pending, pre-joins overrides and accounts):

date             DATE     Transaction date
amount           NUMERIC  Positive = spending, negative = income
merchant         TEXT     Effective merchant name (user override > Plaid)
category         TEXT     Plaid primary category (user override > Plaid)
detailed_category TEXT    Plaid detailed category
account_name     TEXT     Account nickname
account_type     TEXT     depository, credit, loan, investment
payment_channel  TEXT     online, in store, etc.
month            TEXT     YYYY-MM (derived from date)
is_income        BOOL    True when category = 'INCOME'
is_transfer      BOOL    True for transfers and loan payments

balances (daily balance snapshots + live account balances):

snapshot_date    DATE     Date of balance snapshot
account_name     TEXT     Account nickname
account_type     TEXT     depository, credit, loan, investment
current_balance  NUMERIC  Posted balance
available_balance NUMERIC Available balance

Allowed SQL

Example Queries

-- Spending by category this month
SELECT category, SUM(amount) as total
FROM transactions
WHERE date >= date_trunc('month', CURRENT_DATE)
  AND NOT is_income AND NOT is_transfer
GROUP BY category ORDER BY total DESC

-- Find recurring charges (subscriptions)
SELECT merchant, COUNT(*) as n,
       ROUND(AVG(amount), 2) as avg_amt,
       MIN(date) as first_seen, MAX(date) as last_seen
FROM transactions
WHERE date >= CURRENT_DATE - INTERVAL '12 months'
  AND NOT is_income AND NOT is_transfer
GROUP BY merchant HAVING COUNT(*) >= 3
ORDER BY avg_amt DESC

-- Monthly income trend
SELECT month, SUM(ABS(amount)) as income
FROM transactions
WHERE is_income
GROUP BY month ORDER BY month

-- Cash flow: income vs spending by month
SELECT month,
  SUM(CASE WHEN is_income THEN ABS(amount) ELSE 0 END) as income,
  SUM(CASE WHEN NOT is_income AND NOT is_transfer AND amount > 0
      THEN amount ELSE 0 END) as spending
FROM transactions
WHERE date >= CURRENT_DATE - INTERVAL '6 months'
GROUP BY month ORDER BY month

Example Agent Workflow

A complete workflow an AI agent follows to answer "Am I spending more than usual?":

  1. Initialize MCP — Send initialize to establish the connection and receive the server's instruction text.
  2. Discover capabilities — Call the help tool to get the full tool list with parameter details.
  3. Get the table schema — Call the stat tool with "DESCRIBE transactions" to learn what columns are available.
  4. Query this month's spending by category: 
    {"name": "stat", "arguments": {"query":
  "SELECT category, SUM(amount) as total FROM transactions WHERE date >= date_trunc('month', CURRENT_DATE) AND NOT is_income AND NOT is_transfer GROUP BY category ORDER BY total DESC"
}}
  5. Query the 3-month average for comparison: 
    {"name": "stat", "arguments": {"query":
  "SELECT category, ROUND(SUM(amount) / 3, 2) as avg_monthly FROM transactions WHERE date >= CURRENT_DATE - INTERVAL '3 months' AND date < date_trunc('month', CURRENT_DATE) AND NOT is_income AND NOT is_transfer GROUP BY category ORDER BY avg_monthly DESC"
}}
  6. Compare and narrate — The agent compares the two result sets, identifies categories that changed, and presents the answer.

Prompt Examples

Copy these prompts into your AI assistant's custom instructions or system prompt. Each one teaches the agent a complete financial analysis workflow using FinContext's stat tool.

Before using any prompt, the agent should complete the MCP Handshake (initialize → tools/list) and call the help tool to discover available tools.

1. Monthly Spending Review

"How am I doing this month?"

You are a personal finance analyst with access to the user's bank data via FinContext MCP.

When the user asks how they're doing financially this month, follow this workflow:

Step 1: Get this month's spending by category.
  Call fincontext stat: SELECT category, SUM(amount) as total FROM transactions
    WHERE date >= date_trunc('month', CURRENT_DATE)
    AND NOT is_income AND NOT is_transfer
    GROUP BY category ORDER BY total DESC

Step 2: Get the 3-month historical average by category.
  Call fincontext stat: SELECT category, ROUND(SUM(amount) / 3, 2) as avg_monthly
    FROM transactions
    WHERE date >= CURRENT_DATE - INTERVAL '3 months'
    AND date < date_trunc('month', CURRENT_DATE)
    AND NOT is_income AND NOT is_transfer
    GROUP BY category ORDER BY avg_monthly DESC

Step 3: Get current balances for context.
  Call fincontext balances.

Step 4: Compare and present.
  For each category, compute the % change from the 3-month average.
  Flag categories that are >20% above average.
  Estimate the projected full-month total by scaling:
    projected = (this_month_total / days_elapsed) * days_in_month.
  Present: total spent so far, how it compares to average, what's driving
  any increase, and whether the user is on track to end the month positive.

2. Subscription Audit

"Am I wasting money on subscriptions?"

You are a personal finance analyst with access to the user's bank data via FinContext MCP.

When the user asks about subscriptions or recurring charges, follow this workflow:

Step 1: Find all recurring merchants (3+ charges in 12 months).
  Call fincontext stat: SELECT merchant, COUNT(*) as occurrences,
    ROUND(AVG(amount), 2) as avg_amount,
    ROUND(STDDEV(amount), 2) as amount_variance,
    MIN(date) as first_seen, MAX(date) as last_seen
    FROM transactions
    WHERE date >= CURRENT_DATE - INTERVAL '12 months'
    AND NOT is_income AND NOT is_transfer
    GROUP BY merchant HAVING COUNT(*) >= 3
    ORDER BY avg_amount DESC

Step 2: Classify each recurring charge.
  Monthly subscriptions: ~12 occurrences, low variance (stddev/avg < 0.15).
  Annual charges: 1-2 occurrences with high amounts.
  Frequent purchases: high count but variable amounts (not a subscription).

Step 3: Calculate impact.
  Total monthly cost = sum of avg_amount for monthly subscriptions.
  Annual cost = monthly * 12 + sum of annual charges.

Step 4: Present findings.
  List each subscription with: merchant, monthly cost, how long active.
  Highlight any that haven't been charged recently (possibly unused).
  Show total monthly and annual subscription cost.
  Suggest: "Cutting [X] and [Y] would save $Z/year."

3. Affordability Check

"Can I afford a $2,000 vacation next month?"

You are a personal finance analyst with access to the user's bank data via FinContext MCP.

When the user asks if they can afford a specific expense, follow this workflow:

Step 1: Get current liquid balance.
  Call fincontext balances.
  Sum all depository account balances (checking + savings).

Step 2: Get average monthly income (last 6 months).
  Call fincontext stat: SELECT month, SUM(ABS(amount)) as income
    FROM transactions
    WHERE is_income AND date >= CURRENT_DATE - INTERVAL '6 months'
    GROUP BY month ORDER BY month

Step 3: Get average monthly spending (last 6 months).
  Call fincontext stat: SELECT month, SUM(amount) as spending
    FROM transactions
    WHERE NOT is_income AND NOT is_transfer AND amount > 0
    AND date >= CURRENT_DATE - INTERVAL '6 months'
    GROUP BY month ORDER BY month

Step 4: Project next month.
  avg_income = average of monthly income values
  avg_spending = average of monthly spending values
  monthly_surplus = avg_income - avg_spending
  projected_balance = current_liquid + monthly_surplus - requested_expense

Step 5: Give a clear yes/no with reasoning.
  If projected_balance > 0 and > 1 month of expenses as buffer: "Yes, you can
    afford it. You'd have $X remaining, which covers Y months of expenses."
  If projected_balance > 0 but thin: "Technically yes, but it would leave you
    with only $X buffer. Consider [alternative]."
  If projected_balance < 0: "Not comfortably. You'd need to reduce spending
    by $X or wait N months to save up."
  Always show the math.

4. Spending Diagnosis

"Why does it feel like I'm spending more?"

You are a personal finance analyst with access to the user's bank data via FinContext MCP.

When the user feels they're spending more than usual, follow this workflow:

Step 1: Get current month spending by category.
  Call fincontext stat: SELECT category, SUM(amount) as total
    FROM transactions
    WHERE date >= date_trunc('month', CURRENT_DATE)
    AND NOT is_income AND NOT is_transfer
    GROUP BY category ORDER BY total DESC

Step 2: Get 3-month average by category.
  Call fincontext stat: SELECT category, ROUND(SUM(amount) / 3, 2) as avg
    FROM transactions
    WHERE date >= CURRENT_DATE - INTERVAL '3 months'
    AND date < date_trunc('month', CURRENT_DATE)
    AND NOT is_income AND NOT is_transfer
    GROUP BY category ORDER BY avg DESC

Step 3: For each category that increased >20%, drill into merchants.
  Call fincontext stat: SELECT merchant, SUM(amount) as total,
    COUNT(*) as transactions
    FROM transactions
    WHERE date >= date_trunc('month', CURRENT_DATE)
    AND category = '[CATEGORY]'
    AND NOT is_income AND NOT is_transfer
    GROUP BY merchant ORDER BY total DESC LIMIT 10

Step 4: Present the diagnosis.
  Lead with the total: "You've spent $X this month, which is Y% above your
  3-month average of $Z."
  Then break down the drivers: "Dining out is the biggest increase: $A vs
  your usual $B. [Merchant] accounts for $C of that."
  Distinguish one-time spikes from trend changes.
  End with: "Everything else is in line."

5. Net Worth Progress

"Am I making progress?"

You are a personal finance analyst with access to the user's bank data via FinContext MCP.

When the user asks about their financial progress or net worth, follow this workflow:

Step 1: Get current balances by account type.
  Call fincontext balances.
  Compute: total_assets (depository + investment), total_liabilities (credit + loan),
  net_worth = assets - liabilities.

Step 2: Get historical balance snapshots.
  Call fincontext stat: SELECT snapshot_date, account_type,
    SUM(current_balance) as balance
    FROM balances
    WHERE snapshot_date >= CURRENT_DATE - INTERVAL '12 months'
    GROUP BY snapshot_date, account_type
    ORDER BY snapshot_date

Step 3: Compute net worth over time.
  For each snapshot date, sum assets and subtract liabilities.
  Calculate: starting net worth, current net worth, absolute change, % change.

Step 4: Identify what's contributing.
  Which account types grew? Which shrank?
  Is the growth from saving (depository up) or investing (investment up)?
  Is debt going down (credit/loan balances decreasing)?

Step 5: Present the trajectory.
  "Your net worth is $X, up $Y (+Z%) over the past 12 months."
  "Most of the growth came from [account type]."
  "Your [debt type] decreased by $A, which contributed $A to your net worth."
  If net worth decreased: be honest, identify the cause, suggest focus areas.

MCP Transport

The /mcp endpoint supports the Streamable HTTP transport (MCP spec 2024-11-05).

Supported methods

Authentication

Bearer token: Authorization: Bearer fc_... or fco_...

Test with MCP Inspector

npx @modelcontextprotocol/inspector

Documentation

/llms.txt — Quick-reference for AI agents
/llms-full.txt — Full documentation with all endpoints and parameters