MCP
EuGasto MCP server
A public guide for people and for AI agents. English only. Agents should fetch the same text as Markdown at https://app.eugasto.pt/docs/mcp.md. This page works with JavaScript turned off.
On this page
EuGasto (https://app.eugasto.pt) is a personal expense ledger. The MCP server lets an assistant read one space, and record expenses in it when the connection was granted write access. A space is one ledger. The app calls it a space; the consent page and the tool results call it a workspace.
What it is
https://app.eugasto.pt/mcp
https://app.eugasto.pt/sse
The protocol is
MCP streamable HTTP. Use https://app.eugasto.pt. https://eugasto.pt is
the marketing site; its /mcp, /sse, OAuth, and API
paths answer with a 308 redirect to the same path on
https://app.eugasto.pt, but some clients do not follow redirects,
so always configure https://app.eugasto.pt/mcp. Each session is
one Durable Object. The server reports its name as EuGasto.
You do not send an API key to /mcp. API keys belong to the REST
API, documented at
https://app.eugasto.pt/api/docs.
Authentication
MCP uses OAuth 2.1 with PKCE and dynamic client registration. The client discovers the server, registers itself, and sends you to a consent page. No client id is issued in advance.
https://app.eugasto.pt/.well-known/oauth-protected-resource
https://app.eugasto.pt/.well-known/oauth-authorization-server
Endpoints on the same origin: /register (dynamic client
registration), /authorize (consent, PKCE), /token.
-
If you are signed out,
/authorizeshows a small sign-in form at/authorize/sign-in. That form does not create accounts. A new user must create an account at https://app.eugasto.pt/sign-up first, then start the connection again. - The consent page names the connecting app and where it will send the browser afterwards. You pick one space and one access level: read only, or read and write.
- Read only covers expenses, categories, tags, accounts, reports, and budgets. Read and write can also add, edit, and delete expenses, and create tags.
-
Write is offered only when the client asked for the
writescope, or asked for no scopes. A client that asked only forreadcannot be upgraded to write on the consent page. Scopes arereadandwrite. Write always includes read. - The grant is stored as that user, that one space, and those scopes. No tool takes a space id. A tool cannot be pointed at another space.
Removing your membership in that space stops the token on the next call. There is no screen in EuGasto to revoke an MCP connection yet. Starting a new connection does not delete the previous grant.
Set up a client
The production URL is https://app.eugasto.pt/mcp. Deployed
servers must be HTTPS. A local server has to be
http://127.0.0.1:43123/mcp or
http://localhost:43123/mcp (plain http is accepted
only on a loopback host). Claude and ChatGPT connect from their own clouds, so
they cannot reach a server on your laptop.
Prefer read only unless you want the assistant to add, change, or delete expenses.
Claude
claude.ai, Claude Desktop, and Cowork (custom connector)
- Open Customize → Connectors. In Claude Desktop the same list is under Settings → Connectors.
- Add a custom connector (Add, then Add custom connector, or Custom → Web). Labels move; the URL does not.
- Name it
EuGasto. - Remote MCP server URL:
https://app.eugasto.pt/mcp. - Choose sign-in with OAuth. Do not add an API key or a request header.
- If asked how the client is identified, choose automatic registration (dynamic client registration). You do not create a client id.
- Add the connector, then Connect. Sign in, pick one space, and choose read only or read and write.
On Team and Enterprise plans an owner may have to add the connector under Organization settings → Connectors before a member can connect it.
Claude Code
claude mcp add --transport http eugasto https://app.eugasto.pt/mcp
Then run /mcp inside Claude Code, choose eugasto,
and authenticate. A browser opens on the consent page.
ChatGPT
ChatGPT supports streamable HTTP and SSE. Use
https://app.eugasto.pt/mcp. The menu labels have moved during
2026; search settings for “developer” or “MCP” if the path below does not
match.
- Turn on developer mode if you cannot add a custom server. On a personal account it has lived under Settings → Security and login. In a workspace it has lived under Settings → Apps → Advanced settings.
- Open Plugins (or Apps) and choose Add custom MCP server.
-
Name:
EuGasto. Server URL:https://app.eugasto.pt/mcp. Authentication: OAuth. Do not choose “no authentication” and do not paste an API key. - Accept the warning, create the connector, install it, and sign in. Pick one space and an access level.
Cursor
Add this to ~/.cursor/mcp.json (every project) or
.cursor/mcp.json in one project. Do not add an
Authorization header.
{
"mcpServers": {
"eugasto": { "url": "https://app.eugasto.pt/mcp" }
}
}
Reload Cursor if the server does not appear, then approve the sign-in when Cursor prompts. Pick one space on the consent page.
Any other MCP client
Point the client at https://app.eugasto.pt/mcp with the
streamable HTTP transport. If it only implements the older SSE transport, use
https://app.eugasto.pt/sse. It should discover OAuth from the
/.well-known URLs above, register with PKCE, and send you to
/authorize. You do not paste an API key.
Clients that need a stdio bridge
For a client that can only launch a local process, bridge with
mcp-remote:
npx mcp-remote https://app.eugasto.pt/mcp
{
"mcpServers": {
"eugasto": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://app.eugasto.pt/mcp"]
}
}
}
The bridge performs the same OAuth sign-in. A browser still opens for consent.
Tools
These are the only tools. create_tag is the only tool that
creates something other than an expense. There is no MCP tool to create
spaces, categories, accounts, or budgets, and none to change space settings.
Create those in the app.
A call looks like this (the client usually builds the JSON-RPC envelope for you):
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": { "name": "whoami", "arguments": {} }
}
Each example below is the tool name plus arguments.
The result is returned as a text content block: pretty-printed JSON
(content[0].text). Parse that text. On failure the result is an
error whose text is a plain English message, not JSON. The one exception is a
possible duplicate from add_expense: that error also carries
structuredContent (see
possible duplicates).
Read-only connections do not see add_expense,
update_expense, delete_expense, or
create_tag in tools/list. Calling one anyway fails
with:
This connection is read-only. Reconnect and choose read and write access
to add, change, or delete expenses.
Example ids below are illustrations. Real ids are different. Amounts in the examples assume a euro space, where minor units are cents.
whoami read
No parameters. The signed-in user, the one space in scope (role and currency),
and whether the connection can write. access is
read_only or read_write. role is
owner, admin, or member.
Example call:
{ "name": "whoami", "arguments": {} }
Example result:
{
"user": {
"id": "8f3c1a2e-7b64-4d11-9c0a-2e6b5d4a1f70",
"name": "Ada Lovelace",
"email": "ada@example.com"
},
"workspace": {
"id": "1c0b9a88-6e24-4f5a-8d33-0a7e2b1c4d90",
"name": "Personal",
"role": "owner",
"currency": "EUR"
},
"access": "read_write"
}
list_workspaces read
No parameters. The granted space. Always exactly one entry, even if the person belongs to other spaces.
Example call:
{ "name": "list_workspaces", "arguments": {} }
Example result:
{
"workspaces": [
{
"id": "1c0b9a88-6e24-4f5a-8d33-0a7e2b1c4d90",
"name": "Personal",
"slug": "personal",
"role": "owner",
"plan": "free",
"currency": "EUR"
}
]
}
list_categories read
No parameters. Active categories only. Archived categories are omitted.
parentId is null when the category has no parent.
Example call:
{ "name": "list_categories", "arguments": {} }
Example result:
{
"categories": [
{
"id": "5b1e0c44-2a77-4e18-9f60-3d8c7a6b5e12",
"name": "Groceries",
"parentId": null,
"icon": "shopping-basket",
"color": "#12b76a"
}
]
}
list_tags read
No parameters.
Example call:
{ "name": "list_tags", "arguments": {} }
Example result:
{
"tags": [
{ "id": "2d6e8a90-1b45-4c7d-8e12-6f0a3b5c7d21", "name": "weekly" }
]
}
create_tag write
Creates one tag in the granted space. add_expense and
update_expense only accept tags that already exist, so call
list_tags first and create_tag only when the tag is
missing.
| Parameter | Type | Required | Notes |
|---|---|---|---|
name |
string | Yes | 1–40 characters after trimming. Unique per space, compared without regard to case. |
Example call:
{ "name": "create_tag", "arguments": { "name": "Personal" } }
Example result:
{
"tag": { "id": "7f3c2b10-4a8e-4d21-9b6f-1e0d5c8a2f43", "name": "Personal" }
}
Errors:
-
A tag with the same name in any case already exists (
personalwhenPersonalexists):A tag with that name already exists.The existing tag is not returned and nothing changes. Calllist_tagsto get it. -
An empty name, or one longer than 40 characters: the call is rejected as
invalid input, or with
Tag name must be 1 to 40 characters.
list_accounts read
Payment accounts (cash, cards, bank). type is one of
cash, checking, savings,
credit, wallet, other.
| Parameter | Type | Required | Notes |
|---|---|---|---|
include_archived |
boolean | No, default false |
true includes archived accounts. |
Example call:
{ "name": "list_accounts", "arguments": { "include_archived": false } }
Example result:
{
"accounts": [
{
"id": "9a4d2f10-8c33-4b6e-a1d5-7e0f3c2b8a64",
"name": "Checking",
"type": "checking",
"currency": "EUR",
"archived": false
}
]
}
search_expenses read
Filters combine. Newest first by default. Paginated. from must
not be after to. min_amount_minor must not be above
max_amount_minor.
| Parameter | Type | Required | Notes |
|---|---|---|---|
query |
string | No | 1–100 characters. Partial text over payee and note. |
from |
string | No | Earliest date, inclusive, YYYY-MM-DD. |
to |
string | No | Latest date, inclusive, YYYY-MM-DD. |
category |
string | No | Category name or id, 1–100 characters. Archived categories can be searched. |
tag |
string | No | Tag name or id, 1–40 characters. |
account |
string | No | Account name or id, 1–100 characters. Archived accounts can be searched. |
payee |
string | No |
Exact payee, up to 200 characters. "" matches expenses with
no payee. Use query for partial text.
|
min_amount_minor |
integer | No | Minimum amount in minor units, >= 0. |
max_amount_minor |
integer | No | Maximum amount in minor units, >= 0. |
sort |
string | No, default date |
date, amount, payee, or
created.
|
direction |
string | No, default desc |
asc or desc. |
page |
integer | No, default 1 |
1–10000. |
page_size |
integer | No, default 25 |
1–100. |
Example call:
{
"name": "search_expenses",
"arguments": {
"query": "Mercado",
"from": "2026-11-01",
"to": "2026-11-30",
"category": "Groceries",
"page": 1,
"page_size": 25
}
}
Example result:
{
"total": 1,
"page": 1,
"pageSize": 25,
"hasMore": false,
"expenses": [
{
"id": "4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45",
"date": "2026-11-02",
"amountMinor": 1250,
"amount": "12.50",
"currency": "EUR",
"category": "Groceries",
"categoryId": "5b1e0c44-2a77-4e18-9f60-3d8c7a6b5e12",
"account": "Checking",
"accountId": "9a4d2f10-8c33-4b6e-a1d5-7e0f3c2b8a64",
"tags": ["weekly"],
"payee": "Mercado",
"note": null,
"receipts": 0
}
]
}
hasMore is true when page * pageSize < total.
amount is the minor units formatted with a dot (and the
currency's decimal places). receipts is how many receipt files
are attached. category, account, payee,
and note are null when absent.
find_duplicates read
Read-only: it never deletes or changes anything. Groups existing expenses in
the space that look like duplicates of each other, using the same rule as
add_expense (same amount, currency and date, and a similar payee
or the same HH:MM in both notes). Matches are joined: if A
matches B and B matches C, all three are one group.
| Parameter | Type | Required | Notes |
|---|---|---|---|
from |
string | No |
Earliest date, inclusive, YYYY-MM-DD. Default: 89 days
before to.
|
to |
string | No |
Latest date, inclusive, YYYY-MM-DD. Default: today (UTC).
|
With neither, the window is the last 90 days ending today.
from must not be after to.
Example call:
{
"name": "find_duplicates",
"arguments": { "from": "2026-11-01", "to": "2026-11-30" }
}
Example result:
{
"from": "2026-11-01",
"to": "2026-11-30",
"groups": [
{
"reason": "similar_payee",
"expenses": [
{
"id": "b71c9e02-3f4a-4d8e-9c15-6a2e0f7d3b81",
"date": "2026-11-16",
"amount_minor": 310,
"amount": "3.10",
"currency": "EUR",
"payee": "A Praça Lx Factory",
"note": null
},
{
"id": "4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45",
"date": "2026-11-16",
"amount_minor": 310,
"amount": "3.10",
"currency": "EUR",
"payee": "A Praca",
"note": null
}
]
},
{
"reason": "same_time",
"expenses": [
{
"id": "0c5d8e14-7b2a-4f39-a6e1-9d3c2b7f5a08",
"date": "2026-11-15",
"amount_minor": 14240,
"amount": "142.40",
"currency": "EUR",
"payee": "Restaurante Pinóquio",
"note": "Compra cartão 21:47"
},
{
"id": "e9f2a7c3-1d6b-4e58-8b0a-5c4f3e2d1a97",
"date": "2026-11-15",
"amount_minor": 14240,
"amount": "142.40",
"currency": "EUR",
"payee": "Cervejaria",
"note": "Jantar 21:47"
}
]
}
]
}
reason is similar_payee, same_time, or
similar_payee,same_time when both apply within the group. Groups
are newest date first; expenses in a group are newest recorded first. To
remove one, ask the person which, then call delete_expense
(write access).
get_report read
Totals for a date range, plus the previous period of equal length. Totals
include only expenses in the space's current base currency. Expenses kept in
an earlier currency are listed in otherCurrencies and are not
part of totalMinor. Month rows are ordered by calendar label.
Category rows stay in the server's order (largest first). A category row with
no category uses the label Uncategorized and
key null.
| Parameter | Type | Required | Notes |
|---|---|---|---|
group_by |
string | No, default category |
category or month. |
from |
string | No |
Inclusive YYYY-MM-DD. Default: the first day of the month
of to.
|
to |
string | No | Inclusive YYYY-MM-DD. Default: today (UTC). |
from must not be after to. For from
2026-11-01 and to 2026-11-30, the
previous window is 2026-10-02 through
2026-10-31 (the same number of days, ending the day before
from).
Example call:
{
"name": "get_report",
"arguments": {
"group_by": "category",
"from": "2026-11-01",
"to": "2026-11-30"
}
}
Example result:
{
"currency": "EUR",
"groupBy": "category",
"from": "2026-11-01",
"to": "2026-11-30",
"totalMinor": 1250,
"total": "12.50",
"previousPeriod": {
"from": "2026-10-02",
"to": "2026-10-31",
"totalMinor": 0,
"total": "0.00"
},
"rows": [
{
"key": "5b1e0c44-2a77-4e18-9f60-3d8c7a6b5e12",
"label": "Groceries",
"count": 1,
"totalMinor": 1250,
"total": "12.50",
"previousTotalMinor": 0,
"previousTotal": "0.00"
}
],
"otherCurrencies": []
}
otherCurrencies items, when present, look like
{ "currency": "USD", "count": 2, "totalMinor": 1999, "total": "19.99"
}.
budget_status read
Each budget for the month that contains as_of.
| Parameter | Type | Required | Notes |
|---|---|---|---|
as_of |
string | No | YYYY-MM-DD. Default: today (UTC). |
Every budget includes id, name,
category (null if the budget covers the whole space),
categoryId, period, currency,
budgetMinor, budget (formatted), and
status.
under— spent is within the budget and under 80%.-
near— at least 80% used, and spent is not over the budget. Exactly 100% isnear, notover. over— spent is greater than the budget.-
inactive—as_ofis outside the budget's start and end dates. unsupported_period— the budget is not monthly.-
currency_mismatch— the budget's currency is not the space currency, so it cannot be compared. No exchange rates exist.
Only under, near, and over include
periodStart, periodEnd, spentMinor,
spent, remainingMinor, remaining, and
percentUsed. percentUsed is one decimal place, or
null when the budget amount is 0. A budget with no category
counts all spending in the space currency. The top-level
currency is the space currency.
Example call:
{ "name": "budget_status", "arguments": { "as_of": "2026-11-16" } }
Example result:
{
"asOf": "2026-11-16",
"currency": "EUR",
"budgets": [
{
"id": "c3a91e20-4f55-4a8b-9d16-2b7e0c5a8f33",
"name": "Groceries",
"category": "Groceries",
"categoryId": "5b1e0c44-2a77-4e18-9f60-3d8c7a6b5e12",
"period": "monthly",
"currency": "EUR",
"budgetMinor": 20000,
"budget": "200.00",
"periodStart": "2026-11-01",
"periodEnd": "2026-11-30",
"spentMinor": 16000,
"spent": "160.00",
"remainingMinor": 4000,
"remaining": "40.00",
"percentUsed": 80,
"status": "near"
},
{
"id": "d7012ab4-6c88-4e21-8f90-3a5c1d7e9b02",
"name": "Travel",
"category": "Travel",
"categoryId": "aa12bb34-cc56-4dd7-8ee9-001122334455",
"period": "monthly",
"currency": "EUR",
"budgetMinor": 50000,
"budget": "500.00",
"status": "inactive"
}
]
}
add_expense write
Records one expense in the space currency.
| Parameter | Type | Required | Notes |
|---|---|---|---|
amount_minor |
integer | Yes |
Minor units, positive, at most 100000000000. For EUR,
1250 is 12.50.
|
date |
string | Yes | YYYY-MM-DD. Must be a real calendar day. |
category |
string | Yes | Category name or id, 1–100 characters. Must be an active category. |
account |
string | No | Account name or id, 1–100 characters. Must be active. |
tags |
array of strings | No | Up to 20 names or ids, each 1–40 characters. |
payee |
string | No | Who was paid, 1–200 characters. |
note |
string | No | 1–2000 characters. |
currency |
string | No | Three-letter ISO code. Must equal the space currency. Omit it to use the space currency. |
allow_duplicate |
boolean | No, default false |
Save even when the expense looks like a duplicate (see below). Set
true only after the person confirms it is a separate
expense.
|
Example call:
{
"name": "add_expense",
"arguments": {
"amount_minor": 1250,
"date": "2026-11-02",
"category": "Groceries",
"account": "Checking",
"tags": ["weekly"],
"payee": "Mercado",
"note": "Fruit"
}
}
Example result:
{
"expense": {
"id": "4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45",
"date": "2026-11-02",
"amountMinor": 1250,
"amount": "12.50",
"currency": "EUR",
"category": "Groceries",
"categoryId": "5b1e0c44-2a77-4e18-9f60-3d8c7a6b5e12",
"account": "Checking",
"accountId": "9a4d2f10-8c33-4b6e-a1d5-7e0f3c2b8a64",
"tags": ["weekly"],
"payee": "Mercado",
"note": "Fruit",
"receipts": 0
}
}
Possible duplicates
Before saving, add_expense checks the space for an expense that
looks like the same one. Two expenses match when they have the same
amount_minor, the same currency and the same date,
and at least one of:
- a similar payee. Both names are lowercased, accents are stripped, punctuation is dropped and whitespace is collapsed. They match when they are equal, one contains the other, their words overlap by at least half (Jaccard >= 0.5), or they are at least 80% alike by edit distance (Levenshtein). A missing payee never matches.
-
the same time of day,
HH:MM, written in both notes (e.g.Jantar 21:47andCartão 21:47).
When there is a match and allow_duplicate is not
true, nothing is saved. The result is an error (isError: true) whose text says it looks like a duplicate and lists the matches, plus
structured content with up to 5 matches, newest first:
{
"possible_duplicate": true,
"duplicate_ids": ["4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45"],
"duplicates": [
{
"id": "4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45",
"date": "2026-11-16",
"amount_minor": 310,
"amount": "3.10",
"currency": "EUR",
"payee": "A Praca",
"note": null,
"created_at": "2026-11-16T10:12:03.000Z"
}
]
}
Show the matches to the person. If it really is a separate expense, call
add_expense again with the same arguments and
"allow_duplicate": true. Otherwise do nothing. This check is
separate from duplicate_invoice, which refuses an invoice QR
already recorded in the space.
update_expense write
Changes one expense by id. Omitted fields stay as they are. Pass at least one
field besides id. There is no currency field; an
expense keeps the currency it was stored with.
| Parameter | Type | Required | Notes |
|---|---|---|---|
id |
string | Yes | Expense id, 1–64 characters. |
amount_minor |
integer | No |
New amount in minor units. Same limits as add_expense.
|
date |
string | No | New date, YYYY-MM-DD. |
category |
string | No | New active category, name or id. |
account |
string or null | No | New active account, name or id. null clears it. |
tags |
array of strings | No | Replaces the whole set. [] removes every tag. |
payee |
string or null | No | New payee, or null to clear it. |
note |
string or null | No | New note, or null to clear it. |
Example call:
{
"name": "update_expense",
"arguments": {
"id": "4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45",
"amount_minor": 1490,
"note": null
}
}
Example result: the same shape as add_expense, an object
{ "expense": { ... } } with the updated fields.
delete_expense write
Permanently deletes one expense and its receipts. Cannot be undone.
| Parameter | Type | Required | Notes |
|---|---|---|---|
id |
string | Yes | Expense id, 1–64 characters. |
Example call:
{
"name": "delete_expense",
"arguments": { "id": "4e8a1c60-5d22-4b9f-a7e3-1c0d6b8a2f45" }
}
Example result: { "deleted": { ... } } where
deleted is the expense as it was just before removal (same fields
as an expense in search_expenses).
Rules
-
amount_minoris an integer number of minor units, not a decimal string. For EUR, USD, and every currency except JPY, KRW, BHD, and KWD, those units are cents:1250means 12.50. JPY and KRW have no fraction (1250means 1250). BHD and KWD use three decimal places (1250means 1.250). The formattedamountalways uses a dot. -
Dates are
YYYY-MM-DD.2026-02-30is rejected. “Today” for defaults is the current UTC date. -
One base currency per space. New expenses are stored in
that currency. Any other ISO code is rejected. The English error looks like
This workspace uses EUR until currency conversion is available.If an owner changes the base currency later, older expenses keep theirs.get_reporttotals the current base currency and lists the rest inotherCurrencies.budget_statusreportscurrency_mismatchfor a budget in another currency. -
Names or ids. Category, tag, and account arguments accept a
name (trimmed, case-insensitive) or an id, resolved only inside the granted
space. A missing category returns
No category "…" in this workspace. Call list_categories for valid names.Tags and accounts use the same pattern withlist_tagsandlist_accounts. Adding or updating cannot use an archived category or account. Search can. -
Rate limit. 120 requests per minute per grant (the same
user and the same space), shared by
/mcpand/sse. Over the limit the response is HTTP429withRetry-After: 60and a JSON-RPC error:Too many requests. Wait a minute and try again.The window is approximate. -
Read-only connections do not see write tools in
tools/list, and the handlers refuse them anyway. - Revoking access. There is no screen in EuGasto to revoke an MCP connection yet. A grant stays until the membership it was issued for is gone. Losing that membership takes effect on the next tool call.
What an agent should do
-
Call
whoamifirst. Say which space you are in, its currency, and whether you can write. -
Call
list_categories,list_tags, andlist_accountsbeforeadd_expense. Use those names. If the right category does not exist, ask the person to create it in the app. Do not invent one. If the right tag does not exist, callcreate_tag(with write access), then use it. Categories and accounts can still only be created in the app. -
Call
search_expensesbeforeadd_expenseand skip the add when the same payee, date, and amount are already there. Ifadd_expensestill answerspossible_duplicate, show the matches and only retry withallow_duplicate: truewhen the person says it is a separate expense. -
Call
delete_expenseonly when the person explicitly asks to delete that expense. Deleting also removes its receipts and cannot be undone. - Do not pass a space id. Do not send an API key. Do not promise a currency conversion.
Setup prompt for your AI
Paste this to the assistant you want to connect:
You are connecting to EuGasto, a personal expense ledger (https://app.eugasto.pt).
Read https://app.eugasto.pt/docs/mcp.md and follow it. Do not guess tools, fields, or currencies.
Connect the MCP server at https://app.eugasto.pt/mcp (streamable HTTP). If your client only speaks the older SSE transport, use https://app.eugasto.pt/sse. Sign in with OAuth when the browser opens. EuGasto does not use an API key for MCP. API keys are only for the REST API at https://app.eugasto.pt/api/docs.
I need an EuGasto account before this can succeed. If I do not have one, stop and tell me to create it at https://app.eugasto.pt/sign-up, then try again.
After the connection is up:
1. Call whoami. Tell me the space name, its currency, and whether access is read_only or read_write.
2. Before adding an expense, call list_categories and list_accounts, then search_expenses for a likely duplicate. If add_expense says it looks like a duplicate, show me the matches and only retry with allow_duplicate: true if I confirm.
3. Send amount_minor as an integer number of minor units. For EUR that is cents: 12.50 is 1250. Dates are YYYY-MM-DD.
4. Pass categories, tags, and accounts by the names the space actually has. Do not invent categories or accounts. If a tag I asked for is missing, create it with create_tag.
5. Do not call delete_expense unless I explicitly ask you to delete that expense.
Troubleshooting
- 401, or the tools disappear. The sign-in is missing or no longer valid. Start the connection again from the client and sign in. If the consent page says the session expired, do the same.
- Sign-in says there were too many attempts. Wait a minute. The sign-in form allows 10 attempts per minute per address.
-
429. The grant is over 120 requests in the current minute.
Wait for the
Retry-Afterseconds (60) and retry that call. Do not start a second connection to get around it; the limit is per person and space. - The assistant is in the wrong space. No tool can switch spaces. Disconnect, start the connection again, and pick the other space on the consent page. That does not revoke the old grant.
-
Read only, but you asked it to add an expense. Reconnect
and choose read and write. If the client requested only the
readscope, it cannot be given write until it connects again without that restriction. -
A category, tag, or account was not found. Call the
matching list tool and use a name it returned. A missing tag can be created
with
create_tag. -
Another currency was rejected. The space has one currency.
Omit
currency, or send that code. -
Connections to ledger.ferrolho.com or eugasto.pt stopped working.
https://ledger.ferrolho.comandhttps://ledger.ferrolho.ptno longer serve MCP. Every path on them,/mcp,/sse,/authorize,/token,/register, and/.well-known/…included, answers with a308redirect to the same path onhttps://app.eugasto.pt, as do those paths onhttps://eugasto.pt. Clients that do not follow redirects fail. Remove the connection and add it again withhttps://app.eugasto.pt/mcp.