EuGasto

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
  1. What it is
  2. Authentication
  3. Set up a client
  4. Tools
  5. Rules
  6. For agents
  7. Setup prompt
  8. Troubleshooting

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 https://app.eugasto.pt/mcp
Older SSE transport 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.

Protected resource https://app.eugasto.pt/.well-known/oauth-protected-resource
Authorization server https://app.eugasto.pt/.well-known/oauth-authorization-server

Endpoints on the same origin: /register (dynamic client registration), /authorize (consent, PKCE), /token.

  1. If you 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. You pick 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 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)

  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

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.

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

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:

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.

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:

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

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:

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