# EuGasto MCP server

This page is for people and for AI agents. It is English only. The same guide is an HTML page at <https://app.eugasto.pt/docs/mcp>. This file is the plain-text copy.

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

- Streamable HTTP endpoint: `https://app.eugasto.pt/mcp`
- Older SSE transport, for clients that still need it: `https://app.eugasto.pt/sse`
- Spec: [MCP streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#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 the user to a consent page. No client id is issued in advance.

Discovery:

- `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`.

What the person sees:

1. If they are signed out, `/authorize` shows 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.
2. The consent page names the connecting app and where it will send the browser afterwards. The person picks **one** space and one access level: **read only**, or **read and write**.
3. Read only covers expenses, categories, tags, accounts, reports, and budgets. Read and write can also add, edit, and delete expenses, and create tags.
4. Write is offered only when the client asked for the `write` scope, or asked for no scopes. A client that asked only for `read` cannot be upgraded to write on the consent page. Scopes are `read` and `write`. Write always includes read.
5. 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 the person's 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)**

1. Open **Customize → Connectors**. In Claude Desktop the same list is under **Settings → Connectors**.
2. Add a custom connector (Add, then Add custom connector, or Custom → Web). Labels move; the URL does not.
3. Name it `EuGasto`.
4. Remote MCP server URL: `https://app.eugasto.pt/mcp`.
5. Choose sign-in with OAuth. Do not add an API key or a request header.
6. If asked how the client is identified, choose automatic registration (dynamic client registration). You do not create a client id.
7. 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**

```bash
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.

1. 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.
2. Open Plugins (or Apps) and choose Add custom MCP server.
3. Name: `EuGasto`. Server URL: `https://app.eugasto.pt/mcp`. Authentication: OAuth. Do not choose "no authentication" and do not paste an API key.
4. 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.

```json
{
  "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`:

```bash
npx mcp-remote https://app.eugasto.pt/mcp
```

```json
{
  "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):

```json
{
  "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 [add_expense](#add_expense)).

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

Scope: `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:

```json
{ "name": "whoami", "arguments": {} }
```

Example result:

```json
{
  "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

Scope: `read`. No parameters.

The granted space. Always exactly one entry, even if the person belongs to other spaces.

Example call:

```json
{ "name": "list_workspaces", "arguments": {} }
```

Example result:

```json
{
  "workspaces": [
    {
      "id": "1c0b9a88-6e24-4f5a-8d33-0a7e2b1c4d90",
      "name": "Personal",
      "slug": "personal",
      "role": "owner",
      "plan": "free",
      "currency": "EUR"
    }
  ]
}
```

### list_categories

Scope: `read`. No parameters.

Active categories only. Archived categories are omitted. `parentId` is null when the category has no parent.

Example call:

```json
{ "name": "list_categories", "arguments": {} }
```

Example result:

```json
{
  "categories": [
    {
      "id": "5b1e0c44-2a77-4e18-9f60-3d8c7a6b5e12",
      "name": "Groceries",
      "parentId": null,
      "icon": "shopping-basket",
      "color": "#12b76a"
    }
  ]
}
```

### list_tags

Scope: `read`. No parameters.

Example call:

```json
{ "name": "list_tags", "arguments": {} }
```

Example result:

```json
{
  "tags": [{ "id": "2d6e8a90-1b45-4c7d-8e12-6f0a3b5c7d21", "name": "weekly" }]
}
```

### create_tag

Scope: `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:

```json
{ "name": "create_tag", "arguments": { "name": "Personal" } }
```

Example result:

```json
{
  "tag": { "id": "7f3c2b10-4a8e-4d21-9b6f-1e0d5c8a2f43", "name": "Personal" }
}
```

Errors:

- A tag with the same name in any case already exists (`personal` when `Personal` exists): `A tag with that name already exists.` The existing tag is not returned and nothing changes. Call `list_tags` to 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

Scope: `read`. Payment accounts (cash, cards, bank).

| Parameter          | Type    | Required            | Notes                              |
| ------------------ | ------- | ------------------- | ---------------------------------- |
| `include_archived` | boolean | No, default `false` | `true` includes archived accounts. |

`type` is one of `cash`, `checking`, `savings`, `credit`, `wallet`, `other`.

Example call:

```json
{ "name": "list_accounts", "arguments": { "include_archived": false } }
```

Example result:

```json
{
  "accounts": [
    {
      "id": "9a4d2f10-8c33-4b6e-a1d5-7e0f3c2b8a64",
      "name": "Checking",
      "type": "checking",
      "currency": "EUR",
      "archived": false
    }
  ]
}
```

### search_expenses

Scope: `read`. Filters combine. Newest first by default. Paginated.

| 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.                                                                                                |

`from` must not be after `to`. `min_amount_minor` must not be above `max_amount_minor`.

Example call:

```json
{
  "name": "search_expenses",
  "arguments": {
    "query": "Mercado",
    "from": "2026-11-01",
    "to": "2026-11-30",
    "category": "Groceries",
    "page": 1,
    "page_size": 25
  }
}
```

Example result:

```json
{
  "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

Scope: `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:

```json
{
  "name": "find_duplicates",
  "arguments": { "from": "2026-11-01", "to": "2026-11-30" }
}
```

Example result:

```json
{
  "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

Scope: `read`. Totals for a date range, plus the previous period of equal length.

| 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`. 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.

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:

```json
{
  "name": "get_report",
  "arguments": {
    "group_by": "category",
    "from": "2026-11-01",
    "to": "2026-11-30"
  }
}
```

Example result:

```json
{
  "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

Scope: `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`.

`status` is one of:

- `under` — spent is within the budget and under 80%.
- `near` — at least 80% used, and spent is not over the budget. Exactly 100% is `near`, not `over`.
- `over` — spent is greater than the budget.
- `inactive` — `as_of` is 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:

```json
{ "name": "budget_status", "arguments": { "as_of": "2026-11-16" } }
```

Example result:

```json
{
  "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

Scope: `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:

```json
{
  "name": "add_expense",
  "arguments": {
    "amount_minor": 1250,
    "date": "2026-11-02",
    "category": "Groceries",
    "account": "Checking",
    "tags": ["weekly"],
    "payee": "Mercado",
    "note": "Fruit"
  }
}
```

Example result:

```json
{
  "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:47` and `Cartã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:

```json
{
  "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

Scope: `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:

```json
{
  "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

Scope: `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:

```json
{
  "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_minor` is 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: `1250` means 12.50. JPY and KRW have no fraction (`1250` means 1250). BHD and KWD use three decimal places (`1250` means 1.250). The formatted `amount` always uses a dot.
- **Dates are `YYYY-MM-DD`.** `2026-02-30` is 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_report` totals the current base currency and lists the rest in `otherCurrencies`. `budget_status` reports `currency_mismatch` for 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 with `list_tags` and `list_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 `/mcp` and `/sse`. Over the limit the response is HTTP `429` with `Retry-After: 60` and 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

1. Call `whoami` first. Say which space you are in, its currency, and whether you can write.
2. Call `list_categories`, `list_tags`, and `list_accounts` before `add_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, call `create_tag` (with write access), then use it. Categories and accounts can still only be created in the app.
3. Call `search_expenses` before `add_expense` and skip the add when the same payee, date, and amount are already there. If `add_expense` still answers `possible_duplicate`, show the matches and only retry with `allow_duplicate: true` when the person says it is a separate expense.
4. Call `delete_expense` only when the person explicitly asks to delete that expense. Deleting also removes its receipts and cannot be undone.
5. 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:

```text
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-After` seconds (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 `read` scope, 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.com` and `https://ledger.ferrolho.pt` no longer serve MCP. Every path on them, `/mcp`, `/sse`, `/authorize`, `/token`, `/register`, and `/.well-known/…` included, answers with a `308` redirect to the same path on `https://app.eugasto.pt`, as do those paths on `https://eugasto.pt`. Clients that do not follow redirects fail. Remove the connection and add it again with `https://app.eugasto.pt/mcp`.
