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.

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.

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

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#

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

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:

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.

Entity Links#

When the assistant mentions one of your accounts, categories, payees, or transactions by name, that name is rendered as a clickable in-app link. Clicking it takes you straight to that item -- or to a transaction list filtered to it -- so you can jump from an answer to the underlying records in one click. The same links appear on insight cards.

Making Changes#

Beyond answering questions, the assistant can make changes on your behalf -- creating, updating, and deleting transactions, payees, securities, and investment transactions.

Nothing is saved until you approve it. Each proposed change is presented as an on-screen confirmation card that you accept or reject:

• 1-5 items -- each item gets its own confirmation card.
• 6 or more items -- the batch is grouped into a single bulk confirmation card that you approve or reject as a whole.

Attachments#

You can attach files to a chat message using the composer's attachment button. Supported types are images (PNG, JPEG, GIF, WebP), PDF, CSV, and plain text -- up to 5 files per message, each up to 5 MB. PDFs are text-extracted so the assistant can read their contents.

Moving the Chat Panel#

On desktop, the floating chat panel can be dragged by its header to reposition it anywhere on screen. Its position is remembered per device.

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#

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.

Forecast#

Monize can project your finances forward using AI. The forecast analyzes your historical income and spending -- at least 2 months of transaction history is required -- and produces a month-by-month projection for the months ahead.

Like insights, forecast prose is written in your chosen language. In MCP Relay mode the forecast is generated by your connected agent rather than a server-side provider, so your agent must be online to generate one.

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.

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:

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. Read tools require the read scope; write tools require the write scope and are additionally gated by an approval step and the daily write limit.

MCP Resources#

MCP clients can also read these resources for context:

MCP Prompts#

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

MCP Relay#

What is MCP Relay?#

MCP Relay -- "bring your own assistant" -- lets the in-app AI chat run on your own MCP agent and subscription instead of a server-side API key. The MCP Server lets an external client pull your Monize data; the relay flips that direction: the Monize web chat pushes each prompt out to your agent (Claude CLI, Codex, or any MCP client), the agent answers it using the Monize tools, and the answer streams back into the browser chat.

Use it when:

• You already pay for a Claude or Codex subscription and don't want to also configure a metered API key in Settings > AI.
• No central AI provider is configured and you'd rather not paste an API key into the server at all.
• You want the answer computed on your own machine with your own model choice.

How It Works#

The relay is a broker between two long-lived connections -- the browser waiting for an answer and your agent waiting for work:

1. You type a prompt in the Monize web chat. The browser opens a streaming request and the prompt is queued for your user.
2. Your agent, sitting in a poll loop, calls the get_next_prompt tool. It claims the queued prompt (with prior conversation history for context).
3. The agent does the work using the normal Monize MCP tools (get_net_worth, search_transactions, etc.), calling report_progress with short status lines as it goes.
4. Live tool activity and progress narration stream back into the web chat -- the same "Looking up ..." chips and running text the native AI Assistant shows.
5. The agent calls post_response with the final answer, which is delivered to the waiting browser and persisted as the assistant's chat message.
6. The agent loops back to get_next_prompt and waits for the next one.

Three relay control tools drive this loop:

Timeouts: the browser waits up to 5 minutes for an answer. Each get_next_prompt long-poll parks for ~25 seconds, then returns empty so the agent polls again. If your agent isn't connected and listening when you send a prompt, the chat reports that your assistant did not respond.

Connecting Your Assistant#

The exact commands (with your instance URL pre-filled) appear in the chat's How to connect panel and in the MCP Relay provider modal under Settings > AI.

Step 1 -- Create an access token. In Settings > AI > API access, generate a Personal Access Token (starts with pat_, shown once). The relay authenticates with the same PAT as any MCP client.

Step 2 -- Connect the agent.

With Claude CLI:

claude mcp add --transport http monize https://monize.example.com/api/v1/mcp --header "Authorization: Bearer <your-token>"

Restart Claude with auto-approval so it doesn't prompt for every Monize tool call:

claude --allowedTools "mcp__monize__*"

Or with Codex -- add this to ~/.codex/config.toml, set MONIZE_TOKEN to your token, then run codex:

[mcp_servers.monize]
url = "https://monize.example.com/api/v1/mcp"
bearer_token_env_var = "MONIZE_TOKEN"
default_tools_approval_mode = "auto"

Replace https://monize.example.com/api/v1/mcp with your own instance URL.

Step 3 -- Start the agent loop. Give the agent this instruction so it listens for prompts from Monize:

Loop forever: call `get_next_prompt`; if `hasPrompt` is false, call it again; otherwise handle the request with the Monize tools and call `post_response` with the answer; then repeat.

Once the loop is running, the chat's connection indicator turns to listening and anything you type in the web chat is answered by your agent.

Using the Chat#

Once connected, use the AI chat exactly as you would with a server-side provider -- ask questions in natural language, get charts and visualizations, and approve any writes via the in-chat confirmation card. The difference is purely behind the scenes: your subscription answers, and progress narration reflects your agent's real tool calls.

Connection Indicator#

The chat shows a tunnel status so you know whether your agent is reachable:

If you send a prompt while offline, it queues briefly and then times out with a message to make sure your MCP agent is connected and listening.

Limitations#

• Your agent must be running. The relay only works while your agent's poll loop is active. Close the terminal and the chat goes offline.
• Single backend instance. Relay state is held in memory per backend process. A multi-replica deployment needs a shared backplane (e.g. Redis) before the relay works across replicas.
• One agent per user. Prompts are queued FIFO per user and handed to whichever agent polls first.
• 5-minute answer budget. Long, multi-tool agent runs must finish within the browser wait window or the prompt times out.

Usage Tracking#

Since this method of invoking AI generally uses a fixed-cost monthly subscription, token costs aren't exposed and aren't available.

Privacy and Security#

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