Skip to content

AI

Jump to bottom
Ken Lasko edited this page May 23, 2026 · 11 revisions

AI

Monize includes an AI assistant that can answer natural language questions about your finances, generate insights about your spending habits, and integrate with external AI clients via the Model Context Protocol (MCP). You bring your own API key -- Monize supports Anthropic Claude, OpenAI, Ollama (local), and any OpenAI-compatible provider.

Table of Contents

Setting Up AI

Before using AI features, you need at least one configured AI provider -- either a central provider set up by the administrator, or a personal provider you configure yourself.

Central AI Provider

An administrator can configure a shared AI provider at the server level so that all users have access to AI features without needing their own API keys. This is done by setting environment variables on the server.

Variable Description
AI_DEFAULT_PROVIDER Provider type: anthropic, openai, ollama, or openai-compatible
AI_DEFAULT_API_KEY API key for the provider
AI_DEFAULT_MODEL Optional -- specific model to use (falls back to the provider's default)
AI_DEFAULT_BASE_URL Optional -- custom base URL for OpenAI-compatible or Ollama providers

For example, in your .env file:

AI_DEFAULT_PROVIDER=anthropic
AI_DEFAULT_API_KEY=sk-ant-...

When a central provider is configured, all users can use the AI assistant and financial insights immediately. Users who configure their own provider will use their personal provider instead of the central one.

Adding a Provider

  1. Navigate to Settings > AI
  2. Click Add Provider
  3. Select a provider type
  4. Enter your API key
  5. Optionally choose a specific model (or use the default)
  6. Click Save

AI Settings

You can configure multiple providers and assign priority levels. Monize will fall back to the next provider if the primary one is unavailable.

Supported Providers

Provider Default Model Description
Anthropic claude-sonnet-4-20250514 Claude models via the Anthropic API
OpenAI gpt-4o GPT models via the OpenAI API
Ollama (user-configured) Local, self-hosted models -- your data never leaves your machine. Supports private and local network URLs (e.g., http://localhost:11434 or http://192.168.1.100:11434)
OpenAI-Compatible (user-configured) Any API that follows the OpenAI format (Groq, Together, LM Studio, etc.)

For OpenAI-compatible providers, you can set a custom Base URL to point at your preferred endpoint.

Testing Your Connection

After adding a provider, click Test Connection to verify that your API key and configuration are working. The test sends a minimal request to the provider and reports success or failure.

AI Assistant

The AI Assistant lets you ask questions about your finances in plain language. It uses tool calling to query your actual financial data and return accurate, sourced answers.

Asking Questions

  1. Navigate to AI - AI Assistant
  2. Type a question in the chat input
  3. The assistant streams its response in real time

AI Chat

Example questions:

  • "How much did I spend on groceries last month?"
  • "What are my top 5 expense categories this year?"
  • "Compare my spending this month vs last month"
  • "What's my net worth trend over the past 6 months?"
  • "How much can I still spend this month within my budget?"
  • "What's my income breakdown by category?"

The assistant has access to the following financial tools:

Tool Description
Query Transactions Search and aggregate transaction data with filters
Get Account Balances Retrieve account balances and net worth
Get Spending by Category Break down spending by category for a date range
Get Income Summary Income breakdown by source, category, or month
Get Net Worth History Historical net worth trends over time
Get Budget Status Current budget vs actual spending
Compare Periods Side-by-side comparison of two time periods

Suggested Queries

The AI page displays suggested query buttons to help you get started quickly. These are common financial questions tailored to typical use cases.

Charts and Visualizations

When the assistant returns data that lends itself to visualization, an inline chart is rendered directly in the chat. For example, a spending-by-category query may display a bar or pie chart alongside the text response.

Financial Insights

Monize's AI automatically analyzes your financial data daily and generates actionable insights. Insights appear on the AI page and highlight patterns, anomalies, and opportunities you might otherwise miss.

Insight Types

Type Description Severity
Anomaly Unusual spending -- significantly higher than your historical average for a category Warning / Alert
Trend A sustained increase or decrease in spending over 3+ months Info / Warning
Subscription A recurring charge that has changed in price or a consolidation opportunity Info
Budget Pace You're on track to exceed your budget for the current period Warning
Seasonal Seasonal spending patterns detected (e.g., holiday months, annual renewals) Info
New Recurring A newly detected recurring charge that wasn't previously flagged Info

AI Insights

Insights are regenerated daily. A maximum of 50 insights are retained per user, and each insight expires after 7 days.

Dismissing Insights

Click the dismiss button on any insight card to remove it. Dismissed insights will not reappear.

MCP Server

What is MCP?

The Model Context Protocol (MCP) allows external AI clients -- such as Claude Desktop -- to connect to Monize and access your financial data directly. This means you can ask Claude Desktop questions about your finances without opening Monize in a browser.

Choosing an Authentication Method

Monize supports two ways to authenticate an MCP client. Pick based on whether your Monize instance is reachable from the public internet.

Method Best for Requires public HTTPS URL? Setup effort
OAuth ("Add Connector") Public deployments Yes Click-through
Personal Access Token + local bridge Self-hosted / LAN-only / VPN-only No Manual config file

Important

Claude Desktop's built-in Add Connector flow only works when your Monize instance is exposed on the public internet behind HTTPS. The connector handshake requires Claude Desktop to reach your Monize URL directly, and self-signed certificates or non-routable hostnames (e.g., http://localhost:3001, http://192.168.x.x, or *.local mDNS names) are rejected. If your instance is private, use the Personal Access Token + Local Bridge method instead.

Option 1: OAuth (Claude Desktop "Add Connector")

This is the easiest method when your Monize instance is publicly reachable. Tokens are issued through a browser-based consent flow and managed automatically by Claude Desktop -- you never copy or paste a token, and revocation is per-app rather than per-token.

What you'll need:

  • Monize running behind a public HTTPS URL (e.g., https://monize.example.com).
  • The PUBLIC_APP_URL environment variable on the backend set to that same URL. The OAuth issuer, MCP resource URL, and consent redirects are all derived from PUBLIC_APP_URL, so it must match exactly what Claude Desktop will see in the browser.
  • Claude Desktop signed in to your Monize account in a browser tab on the same machine. The consent flow piggybacks on your existing web session.

Steps:

  1. In Claude Desktop, open Settings > Connectors.
  2. Click Add custom connector (or Add Connector).
  3. Enter your Monize URL: https://monize.example.com (no trailing path -- the connector resolves the MCP and OAuth metadata endpoints automatically via /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server).
  4. Claude Desktop opens your browser to Monize's consent screen.
  5. Review the requested scopes (monize:read, monize:write) and click Allow.
  6. The browser redirects back to Claude Desktop, which stores the access + refresh tokens internally.

After consent, Claude Desktop automatically refreshes tokens (default access-token lifetime is 1 hour, refresh-token lifetime is 14 days). You can revoke access from either side:

  • From Claude Desktop: remove the connector in Settings > Connectors.
  • From Monize: an admin can deactivate the user account or trigger a password reset -- both flows now revoke every active OIDC token, refresh token, and authorization grant for that user immediately. Individual users can also use the Settings > AI > MCP / Connected Apps page (when available) to revoke per-client.

Security notes:

  • All grants are PKCE-protected (S256). The OAuth flow rejects the legacy implicit and password grant types entirely.
  • Tokens are audience-bound to your Monize MCP URL. A token issued for https://monize.example.com/api/v1/mcp cannot be replayed against a different Monize instance.
  • Deactivating a user in Settings > Admin > Users immediately invalidates every existing OAuth access token, refresh token, and grant for that user, in addition to refresh tokens and PATs.

Option 2: Personal Access Token + Local Bridge

Use this method when your Monize instance is private (LAN-only, behind a VPN, accessed via Tailscale/Cloudflare Tunnel, etc.) and Claude Desktop's connector flow can't reach it.

This method works because Claude Desktop spawns a local subprocess (the "bridge") on your machine, and that subprocess connects to your private Monize URL using whatever network access your machine has. Nothing has to be publicly exposed.

Step 1: Generate a Personal Access Token

  1. In Monize, navigate to Settings > AI.
  2. Scroll to the MCP / Personal Access Tokens section.
  3. Click Generate Token.
  4. Give the token a name (e.g., Claude Desktop) and select scopes (read, write).
  5. Copy the token -- it begins with pat_ and is shown only once.

Tokens are stored as SHA-256 hashes in the database. You can revoke a token at any time from the settings page.

Step 2: Configure Claude Desktop

Edit your claude_desktop_config.json file. The location depends on your operating system:

OS Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json

Add the following entry under mcpServers. The mcp-remote package (from @modelcontextprotocol) acts as a stdio-to-HTTP bridge, accepting your PAT as an Authorization: Bearer header:

{
  "mcpServers": {
    "monize": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://monize.lan/api/v1/mcp",
        "--header",
        "Authorization: Bearer pat_your_token_here"
      ]
    }
  }
}

Replace https://monize.lan/api/v1/mcp with your Monize URL (LAN, VPN, tunnel -- whatever your machine can reach) and pat_your_token_here with the token you generated.

Step 3: Restart Claude Desktop

Fully quit and relaunch Claude Desktop. The Monize tools should appear in the tool picker once the bridge connects.

Notes for self-hosted users:

  • If you use a self-signed TLS certificate, you may need to add NODE_EXTRA_CA_CERTS to the entry's env block pointing at your CA bundle.
  • PATs do not auto-rotate. Set a reasonable expiry when you generate the token, or rotate manually on a schedule.
  • You can revoke a PAT instantly from Settings > AI without restarting Claude Desktop -- the next request from the bridge fails authentication and Claude Desktop surfaces the error.

Available MCP Tools

External AI clients can use the following tools through MCP:

Tool Description
Accounts List, query, and manage accounts
Transactions Search transactions and create new ones
Categories Browse the category tree
Payees Query and manage payees
Investments View portfolio holdings and performance
Scheduled Transactions Manage recurring bills and deposits
Net Worth Calculate current and historical net worth
Reports Generate financial reports

MCP Resources

MCP clients can also read these resources for context:

Resource Description
Account List All accounts with current balances
Category Tree Full category hierarchy
Recent Transactions Summarized transactions from the last 30 days
Financial Summary High-level financial snapshot

MCP Prompts

Pre-built prompt templates are available for common analysis tasks:

Prompt Description
Financial Review Comprehensive financial health review
Spending Analysis Detailed spending pattern analysis
Transaction Lookup Guided transaction search
Budget Check Budget status and recommendations

Usage Tracking

Monize tracks AI token usage so you can monitor costs. Navigate to Settings > AI and check the Usage section to see:

  • Total tokens used (input and output) per provider
  • Request counts by feature type (query, insight)
  • Token usage over time

Privacy and Security

Monize takes several measures to protect your financial data when using AI features:

Measure Description
Aggregated Data Only The AI receives aggregated summaries, never individual transaction details
Encrypted API Keys Provider API keys are encrypted at rest using AES-256-GCM with per-key random salts
Local Provider Option Use Ollama to run models locally -- your data never leaves your machine
Rate Limiting AI endpoints are rate-limited (10 queries/min, 5 test connections/min)
SSRF Protection Custom base URLs are validated to prevent server-side request forgery
Prompt Injection Prevention Financial data is delimited to prevent prompt injection attacks
Scoped MCP Tokens Personal access tokens have configurable scopes (read, write, reports) and can be revoked at any time
Masked Keys API keys are masked in all API responses, showing only the last 4 characters

Clone this wiki locally