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 or Ollama Cloud), and any OpenAI-compatible provider -- or your own AI subscription through the MCP Relay.

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, and AI Settings says "System Default AI Provider Available". Users who configure their own provider use their personal provider instead of the central one.

How much work the central provider may do to answer one question is set with AI_QUERY_MAX_ITERATIONS (default 5), AI_QUERY_MAX_TOOL_CALLS (15), AI_QUERY_TIMEOUT_MINUTES (20), AI_QUERY_MAX_INPUT_TOKENS (200,000) and AI_QUERY_MAX_TOOL_RESULT_CHARS (50,000). A personal provider sets its own limits in its form (see Query Limits).

Adding a Provider#

1. Navigate to Settings > AI Settings
2. Click Add Provider
3. Select a Provider type, and optionally give it a Display Name
4. Enter your API Key (not needed for Ollama or the MCP Relay)
5. Optionally choose a specific Model (or leave it blank for the default), and enter a Base URL for Ollama or an OpenAI-compatible provider
6. Set its Priority
7. Click Add Provider

You can configure multiple providers (up to 10 by default; AI_MAX_PROVIDERS_PER_USER changes it) and assign priority levels: a lower number is a higher priority. Monize will fall back to the next provider if the primary one is unavailable.

Each provider card shows its status (Active or Inactive), priority, model, a masked key and any cost rates, with Disable / Enable, Edit and Delete. Deleting a provider removes its saved API key with it. When ENCRYPTION_KEY is not configured on the server, cloud providers cannot be added, because their API keys could not be stored securely; Ollama still works.

Supported Providers#

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

Testing Your Connection#

Click Test beside the Model field while adding or editing a provider, or Test on a saved provider's card, to verify that your API key and configuration are working. The test sends a minimal request to the provider and reports "Connection successful. Model ... is ready.", that the model is not available on this provider, or the error the provider returned.

Cost Rates#

Under Cost rates (optional), enter your provider's published Input cost / 1M tokens and Output cost / 1M tokens, and the Rate Currency they are quoted in. They are used only to show an estimated cost on the Usage dashboard; leave them blank to skip cost estimates. When the rate currency differs from your default currency, the estimate is converted with your saved exchange rates.

Query Limits#

Under Query limits (optional) you decide how much work this provider may do to answer one question. Leave a field blank to use the default shown.

Floating Chat Bubble#

Floating chat bubble at the top of AI Settings puts a chat button on every page, so you can ask the assistant from anywhere. It opens as a panel (a bottom sheet on a phone) that you can expand to full screen. It is off until you turn it on, and is offered once an AI provider is available.

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 (or open the floating chat bubble)
2. Type a question in the chat input. Press Enter to send, Shift+Enter for a new line.
3. The assistant streams its response in real time, showing each lookup it makes as it goes

The conversation is saved in your browser, so it is still there when you come back; Clear conversation starts a new one. Without any configured provider the page says "AI Not Configured" and links to the settings.

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: Monthly spending, Top categories, Account balances, Compare months, Net worth trend and Savings rate.

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. A chart can be downloaded as a PNG and a table as a CSV.

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, transfers, payees, securities, investment transactions and transaction rules (Tools > Rules), changing a transaction's category, and running a rule on existing transactions.

Nothing is saved until you approve it. Each proposed change is presented as an on-screen confirmation card showing exactly what would be written, which you Approve or Cancel:

• 1-5 items -- each item gets its own confirmation card.
• 6 or more items (up to 25) -- the batch is grouped into a single bulk confirmation card that you approve or reject as a whole (Approve all). Ask for "individual" review to get one card per item at any size.

A card also says what your rules would do to a new transaction, warns when a change touches a reconciled transaction, and expires if left too long (ask again to retry).

Attachments#

You can attach files to a chat message with the Add attachment button, or by dropping them on the chat. Supported types are images (PNG, JPEG, GIF, WebP), PDF, CSV, and plain text -- up to 5 files per message, each up to 5 MB and 20 MB in total. PDFs are text-extracted so the assistant can read their contents. On a phone, a file shared to an installed Monize can be sent straight to the assistant.

Moving the Chat Panel#

On desktop, the floating chat panel can be moved by its header: drag it, nudge it with the arrow keys, or click to snap it to the next corner. Its position is remembered per device. Expand to full screen and Collapse to panel switch between the two sizes.

Financial Insights#

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

The page shows how many insights are active and how many are alerts and warnings, and lets you narrow the list by Type and Severity. Show dismissed brings back the ones you dismissed, and Refresh Insights analyzes your data again on demand.

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 Dismiss on any insight card to remove it. Dismissed insights will not reappear unless you turn on Show dismissed.

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 up to 12 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 disable the user account or reset their password in Admin > User Management -- both revoke every active OAuth token, refresh token, and authorization grant for that user immediately.

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.
• Disabling a user in Admin > User Management 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 > API Access.
2. Click Create Token.
3. Give the token a name (e.g., Claude Desktop), select scopes (Read, Write) and an expiration, and click Create Token. Monize asks you to confirm it is you first.
4. 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. The same section shows the instance's MCP Server URL with a Copy button. See Personal Access Tokens for the details.

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 > API Access 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 Settings.
• 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 (list_accounts, list_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: a prompt waits up to 5 minutes for an agent to pick it up. Once your agent has claimed it, the browser keeps waiting as long as the agent shows signs of life (polls, progress, tool calls), giving up after 3 minutes of silence or 20 minutes in all. Each get_next_prompt long-poll parks for about 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#

Step 1 -- Add the relay as a provider. In Settings > AI Settings, click Add Provider, choose MCP Relay and click Add Provider. The relay needs no key, model or URL. It is the active provider while it has the highest priority (the lowest number) of your providers.

The exact commands (with your instance URL pre-filled, and Copy buttons) appear in that form and in the chat's How to connect panel.

Step 2 -- Create an access token. In Settings > API Access, create a Personal Access Token (starts with pat_, shown once). The relay authenticates with the same PAT as any MCP client. Give the agent a token of its own: a token shared with another MCP client sends that client's confirmations to the chat too.

Step 3 -- 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 4 -- 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 MCP Agent 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.
• The loop stops when you are idle. After 10 minutes with no new prompt, the agent is told to stop polling, so an idle agent does not fill its own context with empty polls. Restart the loop when you want to continue.
• One agent per user. Prompts are queued in order per user and handed to whichever agent polls first.
• Answer budget. Long, multi-tool agent runs must keep reporting progress, and finish within 20 minutes, or the prompt times out.

Usage Tracking#

The Usage card on Settings > AI Settings shows how much you have used your AI providers over the last 7 days, 30 days, 90 days or All time: the total requests, input tokens and output tokens, and an Est. Cost once you have entered cost rates on a provider. By Provider breaks the totals down per provider, and Recent Activity lists each request with its date, provider, feature, tokens, duration and estimated cost.

The relay is the exception: it generally runs on a fixed-cost monthly subscription, so token counts and costs for relayed answers aren't exposed and aren't available.

Privacy and Security#

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