Connect Your AI

Ask Claude, ChatGPT, Cursor, Windsurf, or any MCP client about your finances.

Checking MCP server…

Setup Instructions

Easiest way to connect

No config files, no API keys to paste. Just click, log in, and authorize. You'll be done in under a minute. Works on claude.ai in any browser, and on the Claude iOS / Android app.

  1. 1

    Open Claude on the web or mobile

    Go to claude.ai or open the Claude app on your phone. Start a new conversation or open any existing one.

  2. 2

    Click the plus icon in the chat input

    Or go to Settings → Integrations and click Add custom integration.

  3. 3

    Fill in the connector details

    NameFinlynq
    Server URL
    http://localhost:3000/api/mcp
    AdvancedLeave collapsed; OAuth handles auth
  4. 4

    Click Add, then Connect

    Claude will open a Finlynq authorization page. Log in if prompted, then click Allow to grant access.

  5. ✓

    You're connected!

    The Finlynq tools are now available in every Claude conversation. Try one of these:

Privacy note:Claude Web uses OAuth 2.1, so your Finlynq passphrase and financial data are never shared with Anthropic. Only the tool responses (query results) pass through Claude's servers.

Example Prompts

Click any prompt to copy it, then paste into your AI assistant.

Try a full flow

Paste any of these into Claude to watch a preview / confirm / execute flow run end-to-end. Claude always asks before it commits anything destructive.

What Claude can do

Capability groups below; for the exhaustive name-by-name list (with category, transport, and OAuth scope per tool) see the full MCP tool catalog. Or use /api-docs / /.well-known/mcp.json for the JSON-Schema view.

Import transactions (CSV / OFX)

Drop a CSV or OFX into Finlynq with the Upload button, then ask Claude to take it from there. Claude lists pending uploads, shows you a preview with duplicate detection, and only commits once you confirm.

list_pending_uploadspreview_importexecute_importcancel_import

Bulk cleanup

Recategorize, retag, or delete many transactions at once. Every bulk operation runs in two steps: a preview that returns a sample and a signed confirmation token, then an execute call that commits. Claude can't skip the confirmation, since the token is scoped to the exact payload.

preview_bulk_updateexecute_bulk_updatepreview_bulk_deleteexecute_bulk_deletepreview_bulk_categorizeexecute_bulk_categorize

Find and manage subscriptions

Detect recurring charges from your transaction history, then add, update (pause/resume/cancel via status), or delete subscriptions without leaving the chat.

list_subscriptionsdetect_subscriptionsbulk_add_subscriptionsadd_subscriptionupdate_subscriptiondelete_subscriptionget_subscription_summary

Manage loans and plan payoff

Track balances, generate amortization schedules, and compare avalanche vs. snowball payoff plans across all your loans.

list_loansadd_loanupdate_loandelete_loanget_loan_amortizationget_debt_payoff_plan

Currency conversion

Ask for live or historical FX rates, convert amounts between currencies, or pin your own rate overrides for bookkeeping.

get_fx_rateconvert_amountlist_fx_overridesset_fx_overridedelete_fx_override

Split transactions

Split a single transaction across multiple categories. Handy for $200 grocery runs that include household goods, or Costco trips that mix food and electronics.

list_splitsadd_splitupdate_splitdelete_splitreplace_splits

Rule management

Create, list, reorder, test, and delete auto-categorization rules. Dry-run any rule against your history before you apply it.

list_rulescreate_ruleupdate_ruledelete_ruletest_rulereorder_rulesapply_rules_to_uncategorized

Portfolio holdings

Manually create, rename, move, or delete portfolio positions (the import pipeline auto-creates them from CSV/ZIP, but for one-offs these are what you want). Plus the read tools for portfolio metrics, performance, a deep-dive on a single position, and rebalancing/benchmark insights. Renames cascade to all transactions automatically; deletes leave the transactions in place with the holding link cleared.

add_portfolio_holdingupdate_portfolio_holdingdelete_portfolio_holdingget_portfolio_analysisget_portfolio_performanceanalyze_holdingtrace_holding_quantityget_investment_insights

Accounts and aliases

Add or update accounts, including a short alias (e.g. last 4 digits of a card, or a receipt label) so Claude can match a transaction even when the source document doesn't use the canonical name. The account parameter on every write tool fuzzy-matches your account names and exact-matches aliases, so pass either one.

add_accountupdate_accountdelete_accountget_account_balances

Suggest payee / category

Before recording a transaction, ask Claude to guess the right category and tags based on your rules and history.

suggest_transaction_details

Reads & dashboards

Balances, net worth, budgets, goals, spending trends, income statements, health score, spotlight alerts, weekly recap, cash flow forecast, anomalies. Every dashboard, queryable in natural language. Portfolio metrics live in the Portfolio holdings card above.

get_account_balancesget_net_worthsearch_transactionsget_budget_summaryget_spending_trendsget_income_statementget_goalsget_cash_flow_forecastget_recurring_transactionsget_spotlight_itemsget_weekly_recapget_spending_anomaliesget_financial_health_scoreget_categoriesfinlynq_help

How destructive ops stay safe:bulk updates, deletes, imports, and subscription-detection all use a preview → confirm → execute pattern. The preview returns a signed token scoped to the exact payload; the execute step rejects unless the token matches. Claude can't skip the preview, and it can't mutate the payload between steps without invalidating the token.

Troubleshooting

Common issues and fixes when connecting an AI assistant to Finlynq. Click any item to expand.

“Failed to connect” or OAuth flow stuck▾
Sign out of the integration (Settings → Integrations → Finlynq → Sign out), then restart the OAuth flow from the Claude side. Most common cause: your session expired after a Finlynq deploy. We rotate DEPLOY_GENERATION on every release, which force-logs out in-flight tokens for security. Re-OAuth and you're back in within seconds.
HTTP 401 Unauthorized from /api/mcp▾
Bearer token expired or missing. For Claude.ai web, re-add the integration from Settings → Integrations. For Claude Desktop / Cursor / Windsurf using API-key auth, generate a fresh key at finlynq.com/settings/account and replace the old one in your client config.
HTTP 403 Forbidden▾
The request Originheader isn't on our allowlist. Custom MCP clients should send Origin as one of: claude.ai, claude.com, chatgpt.com, cursor.com, windsurf.dev, or codeium.com. CLI clients that send no Origin header at all are allowed through.
HTTP 423 Locked▾
Your encryption key (DEK) isn't loaded for the current session. This happens after a long idle (>2h) or a Finlynq deploy. Sign out of finlynq.com and sign back in to reload the DEK, then retry the tool call.
“No holdings tracked” when running portfolio analysis▾
If you're on the public demo account, portfolio data is reseeded nightly, so querying right after a deploy may return a stale cache. Open a fresh chat and re-query. On your own account, make sure every transaction in an investment account is bound to a holding: Finlynq requires portfolio_holding_id on every row in an is_investment=true account. Cash legs are auto-bound to a per-account Cash sleeve.
Tool call returns “stale data” after a write▾
Per-user transaction-aggregation caches are invalidated automatically on every MCP write. If you ever see truly stale data in Claude.ai, sign out and back in to clear the per-user cache. Long-running conversations don't hold cached results; every tool call hits the live database.
Self-hosted: stdio MCP exits at startup▾
Set BOTH DATABASE_URL and PF_USER_ID (a UUID matching a row in users.id). The stdio transport has no HTTP auth layer, so it binds to one user at process startup. Without PF_USER_ID the process exits 1 immediately.
Self-hosted: stdio refuses create / update on accounts, categories, goals, loans, subscriptions, or holdings▾
As of the Stream D Phase 4 rollout (2026-05-03), plaintext name columns are physically dropped from those six tables, and names are stored encrypted under your DEK. The stdio transport has no DEK, so it can't compute the encrypted-name siblings on write. Use the HTTP MCP transport or the Finlynq web UI for create/update on those tables. Read tools across all six tables still work on stdio (names render as a blank dash without a DEK).

Issue not listed? Open a GitHub issue at github.com/finlynq/finlynq/issues. We triage daily.