People increasingly ask a general-purpose assistant about their money. "How much did we spend on groceries last month?", "which budgets are over?" — the questions are easy, but Claude or ChatGPT cannot answer them without the data, so until now a user of AI Budget had to export it or copy numbers into the chat by hand.

We closed that gap with an MCP connector. Any assistant that supports remote MCP servers can now connect to https://api.ai-budget.pl/mcp, ask the user for permission on our own consent page and then read their expenses, income, categories and budgets. This article explains why we built it, why it took only a few days, and what the reviews found before we switched it on on 13 November 2026.

Why MCP, and why now

MCP (Model Context Protocol) is an open standard for connecting AI assistants to outside tools and data. The assistant does not need an integration written for it: it reads a list of tools from the server and calls them when a question needs them. One server therefore works with Claude, ChatGPT and every other client that speaks the protocol.

For us it was cheap for a reason we set up earlier. AI Budget already had a public An API is the interface two systems use to exchange data automatically, with no Excel exports and no copying by hand. Full definition → with its own OAuth server, which we described in a previous article. Authorization, consent, per-account grants, field masking and rate limits all existed and were live. An MCP connector is a second front door onto the same data rather than a new system.

There were three reasons to do it:

Users. Asking an assistant about your own budget is a natural use, and copying numbers by hand is the opposite of what the app is for.

Reach. "Works with Claude and ChatGPT" is a short and honest story, and connector directories are a channel we did not have.

Proof. It is the first real end-to-end run of our OAuth flow in production — code, A token is a fragment of text, usually a piece of a word, and it is the unit AI models measure length and charge by — bills are counted in tokens, not in questions. Full definition →, call, refresh, revoke — driven by clients we did not write.

The owner's decisions fixed the scope early: any MCP client may connect, access is read-only, and the assistant sees exactly what the public API gives — no more. Writes, receipt images and a local (stdio) server package were explicitly left out.

How an assistant finds us without an API key

The user types one address. Everything else the assistant discovers on its own, through standards that already exist:

1. A 401 that explains itself. The first call to /mcp has no token, so the server answers 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource/mcp (RFC 9728).

2. Metadata. That document names our authorization server, and /.well-known/oauth-authorization-server (RFC 8414) lists the endpoints, the supported scopes and the only allowed PKCE method, S256.

3. Self-registration. The assistant registers itself at /oauth/register (Dynamic Client Registration, RFC 7591). It becomes a public client: no secret, PKCE required, tagged as registered by an assistant.

4. Consent. The browser opens app.ai-budget.pl/authorize — the same page every connected app uses. The user signs in, ticks the accounts the assistant may read and approves.

5. Token and calls. The assistant exchanges the code for a token and calls tools on /mcp. A refresh keeps the token bound to the same resource.

Nine read-only tools

The server exposes nine tools: list_accounts, list_expenses, get_expense, list_incomes, get_income, list_categories, list_budgets, get_budget and get_spending_summary. They cover what the public API reads — accounts, expenses and income with filters and details, expense and income categories, budgets with progress in the current period, and spending totals.

Results are bounded on purpose. A list takes a limit from 1 to 200 (50 by default) and a cursor, no result exceeds 200 rows, and an expense with more than 200 receipt lines says "Showing 200 of N" rather than pretending to be complete. Receipt images are not available through MCP at all: they are large and of little use to a chat model.

The endpoint runs inside our NestJS API on the official TypeScript MCP SDK, over the Streamable HTTP transport. It is stateless — one server instance per request — because read tools need no session.

One authorization core for REST and MCP

The most important design rule is negative: there is no separate authorization for MCP. Before writing the connector we extracted the public API's guard logic into one service, PublicApiAuthorizer, and pinned its behaviour with tests. The REST guard and /mcp both call it; a change to authorization changes both surfaces together.

It reads the database on every call and caches nothing: the token, whether its grant was revoked, whether the app was blocked, whether the user is active, whether the person who granted access is still an owner or editor of that account, and the account's encryption level. Disconnecting an assistant in the app, an admin blocking it, or a demotion to viewer stops it on its next tool call.

The data rules are the same as for any connected app. An account with full end-to-end encryption cannot be read at all, and on a text-encrypted account the encrypted fields stay hidden. Every tool reads through the same view functions as the REST controllers, never through a query of its own.

A token works on exactly one surface

An OAuth token says who may do what, but not where. We added that through resource indicators (RFC 8707): a token carries the resource it was issued for. A token for /mcp is refused by the REST API, and a REST token is refused by /mcp.

The consequence matters for self-registered clients: an assistant that registered itself must name the MCP resource, so it can only ever hold MCP tokens. An anonymous registration can never reach the REST API, whose write scopes it could otherwise request.

The scopes are limited for the same reason. A self-registered assistant may hold only expenses:read, categories:read, incomes:read, budgets:read and analytics:read. receipts:read and every write scope are refused at authorize, token and refresh.

There is one subtlety we wrote down as a rule: /mcp is read-only because of its tool set, not because of a scope check — a developer-registered app could hold write scopes and an MCP-bound token. Adding a write tool therefore cannot be "just register the tool"; it forces a decision about scopes, client types and confirmation.

What the reviews found

The code went through several review waves before launch. Most findings were about the self-registration endpoint and the consent page, because that is where an unknown party gets to put something in front of our users.

Registration abuse. The first limit was per IP address. A review pointed out that with IPv6 one machine can rotate through a whole /64 prefix, so the limit is now counted per /64, with a global ceiling of 300 registrations an hour on top. If Redis is unavailable, registration fails with 429 rather than becoming unlimited, and the request body is capped at 16 KB.

Impersonation on our own consent page. An assistant names itself, so a registration could call itself after our product. A name containing the product's name is refused — case-, diacritic- and whitespace-insensitive, with a small map of look-alike characters, and also our company name and the Polish and Russian words for budget.

Trusting self-declared metadata. Everything in a registration is written by whoever registered. The consent page therefore shows the name as plain text with bidi, zero-width and control characters stripped, the self-declared homepage only as a host in punycode and without a link, and never the logo — loading it would also send the viewer's IP address to whoever registered. Instead it shows, in a warning frame, the one fact that is not self-declared: "Access will be sent to <host>", taken from the validated redirect address, so a look-alike domain reads as xn--….

Cost per request. Rate limiting counts one unit per tool call, in the same buckets as the REST API. The connection check before a call does not count; that was a deliberate correction, since counting it would charge every call twice. The /mcp body is capped at 128 KB before authentication — the global parser would have accepted 50 MB — and JSON-RPC batches are refused: the 2025-06-18 version of the protocol removed batching, and a batch would multiply the cost per unit.

A dark route must stay dark. Everything ships behind two flags, and with them off /mcp, the registration endpoint and the discovery documents answer 404. A review noticed that the route-specific body parsers run before any guard and would answer 400 or 413 — revealing a route that was supposed to be invisible. They now check the flag on every request.

Not breaking existing clients. A spec-following client of the public API may name its resource too. Those identifiers are accepted as meaning the REST API, so binding tokens to resources did not break anyone already connected.

Housekeeping and logs. Self-registered clients nobody used are soft-deleted 30 days after their last grant. MCP logs carry the tool name, the outcome and the duration — never a token, a code or a financial row; on an internal error they add only the error's class name.

Switching it on

On 13 November 2026 we added two blocks to the shared nginx — /mcp and the discovery documents on the public API's rate-limit zone, with a small body cap — reloaded it gracefully and turned the flag on. Before the flag, we checked that the new paths reached the API and answered 404 from it rather than from nginx; after it, that the discovery documents answer and /mcp returns 401 with the right challenge.

The first real client then found what no review had. Claude Code registers under the name "Claude Code (<what the user called the server>)", and we had named the server ai-budget — so it registered as "Claude Code (ai-budget)", and our impersonation check refused it. Every user who named the connector after us would have been locked out with an error they could not understand. We fixed it the same day: a trailing label in brackets is no longer checked when something precedes it, while "AI Budget (official)" and a bare "(AI Budget)" are still refused. After that the whole path worked — discovery, registration, consent, token, connection and the tool list.

One question we keep open: the registration limit is per IP, and if a platform registers from shared servers rather than from the user's browser, all its users would share one bucket. Before announcing the connector in directories we record the registration addresses of real clients and raise the limit for that platform if needed.

How to connect

In Claude, open Settings → Connectors, add a custom connector and enter https://api.ai-budget.pl/mcp. On a Team or Enterprise plan only the organization's owner can add custom connectors — we ran into this ourselves. Other assistants that support remote MCP connectors take the same address.

The assistant opens an AI Budget page where you sign in as usual. It shows the assistant's name with the note that it registered itself, and the host access will be sent to. Tick the accounts it may read and allow. To cut it off, open Settings → Connected apps in AI Budget and disconnect it; it loses access on its next call.

Frequently asked questions

Can an assistant change my data in AI Budget?
No. The connector has read-only tools: accounts, expenses, income, categories, budgets and spending totals. It cannot add, change or delete anything and it does not download receipt photos.
Do I need an API key?
No. You enter https://api.ai-budget.pl/mcp in the assistant, it registers itself, and you approve access on the AI Budget consent page and pick the accounts.
How do I take access away from an assistant?
In AI Budget open Settings → Connected apps and disconnect the assistant. Permissions are checked on every call, so it loses access on its next request.
Does it work with encrypted accounts?
An account with full end-to-end encryption cannot be read. On a text-encrypted account the encrypted fields stay hidden — the same as for any connected app.