FinanceContext MCP

The open-source finance-context layer behind Lumi — a standalone remote MCP server that lets LLM agents reason over a user's real financial state without ever holding elevated credentials.

Extracted from the Lumi codebase; table names (lumi_*) reflect the production schema it runs against.

The security model (the interesting part)

The agent never gets more power than the user. The server validates Supabase-issued bearer JWTs against JWKS, then uses the user's own token for every Supabase read and write — so Postgres row-level security remains the single source of authority. There is no service-role key anywhere in this service. Misbehaving agent, compromised prompt, doesn't matter: the blast radius is exactly what the user themselves could do.

Layered on top:

• OAuth protected-resource metadata (/.well-known/oauth-protected-resource) for MCP client discovery
• Permission claims enforced when present (default read-capable when absent)
• DNS-rebinding protection via a host allowlist when binding publicly
• An activity log (list_recent_activity) so tool usage is auditable

Tool surface (19 tools)

Category	Tools
Read & analyze	list_accounts · get_balance_summary · search_transactions · summarize_spend · get_cashflow_summary · list_recurring_charges · get_sync_status
Classification	list_uncertain_transactions · explain_transaction_classification
Agent memory	remember_financial_preference · list_financial_memory · forget_financial_memory
Rule drafting	create_rule_draft · preview_rule_impact · list_rule_drafts
Human approval	submit_approval_request · approve_pending_change · reject_pending_change
Audit	list_recent_activity

The write path is deliberately indirect: agents draft rules and preview their impact, but changes land only through an explicit approval request a human accepts or rejects. Agents propose; people dispose.

Stack

TypeScript · Express 5 · @modelcontextprotocol/sdk (Streamable HTTP) · @supabase/supabase-js · jose (JWKS validation) · zod

Endpoints

GET /health · GET /.well-known/oauth-protected-resource · POST|GET|DELETE /mcp

Local development

cp .env.example .env    # Supabase URL + publishable key
npm install
npm run dev             # tsx watch
npm run check           # typecheck
npm run build && npm start