Connect your AI agent to your expenses with MCP

Quick answer

You need three things: the server URL, https://controlargastos.es/api/mcp; an agent token created from your profile; and an MCP client that speaks HTTP and lets you set an Authorization header. In Claude Code you add it with claude mcp add --transport http. The token carries granular permissions that you choose: without gastos:create, the agent cannot create an expense no matter how nicely you ask.

Talking about your money versus actually touching it

There is an awkward moment when you ask an AI assistant to help with the household accounts. You paste a summary, it says something sensible, and that is the end of it. Tomorrow you paste the summary again. Nothing was remembered, nothing was recorded, nothing changed: it was an expensive commentator on your own data.

The Model Context Protocol exists to break that wall. It is an open standard that lets a language model call real tools in a service — read, write, compute. When a service publishes an MCP server, it stops being a website you open and becomes something your agent can operate.

ControlarGastos publishes one. It is not a demo or a wrapper around a chat window: the tools it exposes are the product's own operations — create an expense, list this month's, check balances, confirm a debt, review a budget — and each one runs through the same domain services the web interface uses. An expense created by an agent inherits the same validation, the same split logic and the same plan limits as one created by hand. There is no back door with looser rules.

What you need before you start

An account, and a client that speaks MCP over HTTP. That second point causes the most confusion, so let us be precise: the server runs in stateless Streamable HTTP mode. No SSE, no server-side session. Every request carries its own token and resolves on its own.

The practical consequence is a good one: any client that can POST with an Authorization header will work. Claude Code works. Cursor works. An agent you wrote yourself works. What does not fit are the one-click connectors in some desktop applications, which expect a full OAuth flow with automatic discovery; our token is a static Bearer, and that is a different mechanism. We would rather say so here than let you find out by trial and error.

Step 1: create the token and decide what it may touch

Go to your profile, to the agent tokens section. When you create one you give it a name — make it describe who will use it, because you can have several — and tick the permissions you are granting.

This is where the security of the whole arrangement is actually decided, and it is worth thirty seconds of thought. Permissions are granular and split between reading and writing: gastos:read is not gastos:create, and neither implies deudas:write. If what you want is an agent that summarises your month, give it read access only. A read-only token cannot break anything, whether the agent gets confused, the model hallucinates, or somebody copies the string.

The token is shown once. Only its hash is stored, so no screen will ever show it to you again: lose it and you revoke it and mint another. The inconvenience is deliberate.

Step 2: add the server to your client

In Claude Code, with the URL and the token in hand:

claude mcp add --transport http controlargastos https://controlargastos.es/api/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

The name controlargastos is what you will see later in the server list; call it whatever you like. By default the server is added at local scope, meaning it loads only in the project where you added it and stays private to you. If you would rather have it everywhere, there is a user scope for that.

One warning that saves a puzzled afternoon: if you configure an Authorization header and the server rejects it, the client reports the connection as failed and does not fall back to an OAuth flow. A connection failure here is almost always an expired, revoked or mistyped token rather than a problem with the server.

Step 3: check who your agent is actually talking to

Do not accept the connection just because nothing went red. Check two things.

First, that the client can see the tools: in Claude Code, the /mcp panel lists connected servers and how many tools each one exposes.

Second, and this is the one that matters, that the token is the token you think it is. The server publishes an identity endpoint, GET /api/mcp/whoami, which returns the user who owns the token and that token's effective permissions. It answers the right question, which is not "am I connected?" but "what exactly can the thing I just connected do?". If a permission you did not mean to grant shows up there, you have found it before anything used it.

Read that list carefully, because it has a detail that surprises people: it can return fewer permissions than you ticked. That is not a bug. Some permissions also require a separate usage declaration, and until that is accepted the permission is stored but grants nothing. Your profile panel explains it for that specific token.

What this server does not do

Just as important as what it does. It does not connect to your bank: there is no bank aggregation here, so the question "can I plug in my current account?" has a short answer, and it is no. It does not expose other people's data: a token always acts on behalf of its owner and can never see more than that owner would see on the web. And it does not serve requests launched from a browser on another site: the server verifies the request origin, which is the mitigation the specification itself recommends against DNS rebinding.

Frequently asked questions

What is the remote MCP server URL?

https://controlargastos.es/api/mcp, over POST. A GET to that address answers 405 by design — that is the endpoint being alive, not an error. Authentication is an Authorization: Bearer <token> header.

Can I connect it from ChatGPT or Claude desktop?

That depends on whether the application lets you add an HTTP server with a custom header. One-click connectors currently expect an OAuth flow with automatic discovery, and this server authenticates with a static Bearer, so that particular path does not fit. With clients that accept custom headers — Claude Code, Cursor, or your own agent — it works today.

Does the agent see all of my expenses?

Only if you grant a read permission that allows it, and never beyond what you can see yourself in the application. A token without gastos:read cannot list expenses. The way to be sure is not to trust this sentence but to call GET /api/mcp/whoami and read the permission list it returns.

Can I have more than one token?

Yes, and you should. One token per agent, named after that agent, with only the permissions it needs. Revoking one then does not break the others, and the list shows you when each was last used.

What do I do if a token leaks?

Revoke it from your profile. It stops working immediately and you mint a new one. Because only the hash is stored, revoke-and-regenerate is the only possible path: nobody, including us, can recover the original string.

What happens if my agent calls too fast?

There is a rate limit per token. Exceed it and the server answers 429, and the agent has to space its calls out. The limit is per token, so one runaway agent does not take the others down with it.