Skip to main content
Glama
deenesjakoruzh
mhopareprathmesh5-creator

expense-tracker-mcp

by mhopareprathmesh5-creator
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

expense-tracker-mcp

Try it → · sign in with Google; your expenses are private to you

A remote MCP server for tracking personal expenses, backed by Postgres, driven by three different clients: Claude as a connector, a terminal agent, and a web app.

Log an expense by saying "spent 450 on groceries today", then ask "what did I spend on food this month?" — and get the same answer from any of them, because the state lives in a database rather than in a chat session.

Claude (connector) ──┐
                     │
Streamlit web app ─┐ ├─► expense-tracker-mcp ─► Neon Postgres
                   ├─┘        (FastMCP)
Terminal REPL ─────┘
   (one LangGraph agent, two front-ends)

Every query is scoped to the authenticated user, so several people share the deployment without sharing a ledger.

Status

Phase

1

Server foundation — typed tools, Postgres, category validation

done

2

LangGraph client — terminal, agent loop, checkpointed memory

done

3

Streamlit frontend on top of the working agent

done

4

Queries scoped to the authenticated user

done

5

Google sign-in, so the web app is multi-user too

done

All five are deployed and in use. Every claim was verified by checking what actually landed in Postgres, not by reading what the model said it did — the id sequence is a useful receipt here, since rejected input never advances it.

Related MCP server: expense-tracker-mcp-server

Tools

Tool

Purpose

whoami

Which user the server sees, and whether expenses are scoped.

list_categories

The valid taxonomy, so the model can look it up instead of guessing.

add_expense

Record one expense. Validates the category before writing.

list_expenses

Individual rows, newest first. Optional date range and category filters.

edit_expense

Change any field of one expense. Only what you pass is touched.

delete_expense

Remove one expense by id. Scoped to the owner.

summarize

Totals over a date range, grouped by category — or by subcategory when you filter to one category.

The taxonomy is also published as a resource, expenses://categories. That duplication is deliberate, and testing against Claude is what put it there: resources are the correct MCP primitive for read-only reference data, but a client only reads one when a user attaches it — models are handed tools, not resources. Asked "what categories can I use?", Claude reported the taxonomy as unavailable and offered to write a junk row so it could read the valid values off the rejection error. The tool is what the model can actually reach; the resource remains for clients that browse resources directly.

Categories are a fixed two-level taxonomy defined in categories.json — 20 categories, each with subcategories. Anything outside it is rejected with the valid values included in the error, so the model can correct itself in one round trip.

The terminal client

client.py is the second consumer — a LangGraph agent you talk to in plain language:

you> log 250 on petrol today
  → list_categories()
  ← 20 categories
  → add_expense(date='2026-08-21', amount=250, category='transport', subcategory='fuel')
  ← saved #15 250.00 transport/fuel on 2026-08-21

Logged: ₹250.00 for fuel (transport) on 2026-08-21.

Nothing in the taxonomy says "petrol", so the agent looks the categories up before writing rather than guessing.

uv sync --group client

uv run --group client python client.py            # against a local server
uv run --group client python client.py --remote   # against the deployed one

The client's dependencies live in a separate group. The deployment installs the project on every build and has no use for LangGraph, so keeping them out of the main list keeps the server's build lean.

Three things it does that a naive chat loop does not:

A real agent loop. "Log 90 on coffee yesterday and then tell me my food total" needs two sequential tool calls in one turn. create_agent keeps calling tools until the model stops asking for them; a single-round loop answers half the question.

One event loop, one MCP session, for the whole process. An MCP session is bound to the event loop it was created on. Calling asyncio.run() per message — which is the obvious way to bolt async onto a REPL, and what the earlier version of this project did — creates and destroys a loop each time, so the second message dies with Event loop is closed. Here everything runs inside a single asyncio.run() with the session held open.

Conversation memory that survives restarts. A LangGraph checkpointer keyed by thread_id, stored in the same Neon database. Quit the client, start it again, and ask what you said earlier — it knows, because the history is in Postgres rather than in a list in memory.

The system prompt also injects today's local date, because add_expense deliberately refuses to infer it: the server's clock is UTC and would log the wrong day either side of midnight. The client knows the user's date; the server does not.

The web UI

Live at expense-tracker-mcp.streamlit.app — sign in with Google and you get your own private ledger.

app.py is a Streamlit chat interface over the same agent — same prompt, same tools, same conversation memory, because both front-ends build their runtime from agent.py rather than each assembling one.

uv run --group ui streamlit run app.py

Tool calls are shown under each answer, so you can watch the agent look up a category, get a rejection, and correct itself.

Streamlit re-executes the whole script on every interaction, which is hostile to exactly what this app holds: an MCP session and a psycopg connection, both bound to the event loop that created them. Rebuilt per rerun they would be opened and closed on every keystroke. So the async half lives in one background thread owning one event loop, built once behind @st.cache_resource; the script hands coroutines to that loop and waits for results. Reruns redraw the page and cannot disturb the connections.

The conversation id lives in the URL, not in st.session_state — session state is wiped by a browser refresh, which would drop you back into the default conversation at precisely the moment persistence is supposed to prove itself. The sidebar lists your stored conversations, read back from the checkpoint tables, so conversations started in the terminal client appear there too.

How the web app knows who you are

This is the interesting part, because a web app cannot authenticate to the MCP server the way Claude does.

Each Claude user makes their own connection, so the gateway sees a distinct caller and can identify each one. The web app is one program with one API key serving many people — the gateway sees a single caller and never learns the humans exist. Keeping track of them is the app's job.

So the app signs users in with Google, then tells the server whose request each one is:

POST /mcp
Authorization: Bearer <the app's API key>    may this caller connect?     yes
x-app-secret:  <shared secret>               is this really my app?       yes
x-app-user:    alice@gmail.com               whose expense is this?    Alice's

The key opens the door; the label on the request decides whose row it becomes.

The secret is what makes the label trustworthy. x-app-user is only text — without proof of who wrote it, anyone holding an API key could name any user and read their expenses. The server accepts an asserted identity only when the shared secret matches, verified with secrets.compare_digest so a wrong value cannot be found one character at a time by timing. If the secret is unset, the path is disabled rather than open, and the app shows an error banner when the server disagrees with the browser session — it fails loudly instead of quietly writing to the wrong ledger.

Identity is keyed on email, because two doors reach the same person: Claude gives a gateway UUID, Google gives a Google subject. Keyed on ids, one human would own two unrelated ledgers. The tradeoff is that emails are mutable, so changing yours orphans your history — fine here, wrong for a bank, where you would keep an immutable id and a separate email column.

Running it locally

Prerequisites: Python 3.10+, uv, and a Neon account (the free tier is enough).

git clone https://github.com/mhopareprathmesh5-creator/expense-tracker-mcp
cd expense-tracker-mcp
uv sync

Configure the database. Copy the example file and fill in your Neon connection string:

cp .env.example .env      # PowerShell: Copy-Item .env.example .env

Two things matter about that string:

  • Use the pooled connection — the host contains -pooler.

  • Strip the ?sslmode=require&channel_binding=require query string. asyncpg doesn't accept libpq's query parameters and will raise invalid dsn: invalid connection option "sslmode". TLS is requested explicitly in code instead. (The server strips these defensively too, so a raw pasted string still works.)

Create the table. Run schema.sql once, in the Neon SQL Editor or any Postgres client. Every statement is idempotent.

Start the server:

uv run python main.py            # stdio, for a client that spawns it
uv run python main.py http       # http://127.0.0.1:8000/mcp

stdio is the default because that is what an MCP client spawning this file as a subprocess expects — JSON-RPC over stdin/stdout.

Or explore it interactively with the MCP Inspector (needs Node):

uv run fastmcp dev inspector main.py

A browser GET on /mcp returns 406 Not Acceptable. That's correct, not a failure — MCP requires POST with Accept: application/json, text/event-stream.

To run the web app, add Google sign-in credentials as well:

cp .streamlit/secrets.toml.example .streamlit/secrets.toml
uv run --group ui streamlit run app.py

Fill in a Google OAuth client id and secret (Google Cloud → Google Auth Platform → Clients → Web application), with http://localhost:8501/oauth2callback as an authorized redirect URI — Google refuses to send users anywhere not registered in advance, which is what redirect_uri_mismatch means. APP_SHARED_SECRET in .env must match the value set on the server, or the server ignores the app's claim about who is signed in and everyone falls back to one ledger.

Deploying

The server runs on Prefect Horizon (formerly FastMCP Cloud). Point it at this repo with entrypoint main.py:mcp and set DATABASE_URL and APP_SHARED_SECRET in its environment variables. Deployed servers get a *.fastmcp.app URL, which can be added directly to Claude as a connector.

Horizon reads environment variables at container start, so adding one is not enough — the app must be redeployed, or it keeps running with the old value. An unset APP_SHARED_SECRET looks identical to a wrong one from the outside, which is why whoami reports whether the server has a secret, whether the headers arrived, and whether they matched.

The web app runs on Streamlit Community Cloud, deployed from the same repo with app.py as the entry point. Its secrets hold the [auth] blocks plus DATABASE_URL, GOOGLE_API_KEY, HORIZON_API_KEY and APP_SHARED_SECRET, and redirect_uri must point at the deployed URL and be registered with Google.

Two deployment notes worth knowing:

  • Streamlit installs with uv sync against uv.lock, and uv sync installs only default groups — hence default-groups = ["ui"] in pyproject.toml. A requirements.txt is silently ignored, because uv.lock takes precedence.

  • There is deliberately no .python-version file. Horizon builds with UV_PROJECT_ENVIRONMENT=/usr/local, a system Python prefix rather than a virtualenv; a version pin makes uv reject it, download a managed CPython, and fail trying to recreate a non-venv directory. The requires-python = ">=3.10" floor is sufficient.

Design decisions

Money is NUMERIC(12,2), never a float. Binary floating point cannot represent 0.1 exactly, so summing float amounts accumulates error and totals drift by cents. Amounts are Decimal in Python, NUMERIC in Postgres, and cross the wire as strings — JSON numbers are IEEE-754 doubles, so serialising as a float would reintroduce the drift at the very last step. 450.55 + 120.45 returns exactly 571.00.

The connection pool is created lazily, never at import. Connecting at import time turns a transient database problem into a failed deploy; a lazy pool turns it into one failed tool call the caller can retry. Schema creation is likewise a separate one-time script, not something the server does on boot.

Every parameter is annotated. FastMCP builds the JSON schema the model sees from type hints, so date: date reaches the model as {"type": "string", "format": "date"} and amount carries exclusiveMinimum: 0. Untyped parameters measurably degrade tool-calling accuracy — and invalid input is rejected by schema validation before the tool body runs at all.

Every tool returns a dict, on success and on failure alike, with an ok key. A tool that returns a list on success and a dict on error forces every caller to type-check before using the result.

Every query is scoped to the authenticated user, and there is one place it can go wrong. Prefect Horizon terminates auth at its edge and forwards the identity in headers; the server resolves it in current_user_id(). Reads go through a single helper that always emits user_id = $1, so no tool builds its own WHERE clause and none can forget the filter. delete_expense scopes in the DELETE itself rather than checking ownership first — one statement cannot disagree with itself the way a check-then-delete can — and returns the same "not in your records" answer whether the id is missing or someone else's, so it never confirms that a row exists.

user_id was on the table from day one, defaulted and unused, precisely so this step would be a change of value rather than a migration. It is deliberately not a tool parameter: if the model could choose it, any client could read anyone's expenses just by asking.

edit_expense is the one place that has to read before it writes, because a partial edit cannot be validated otherwise — changing only a subcategory means checking it against the category already stored. Both statements carry the user_id filter, so the write is scoped on its own rather than trusting the read that preceded it. It also drops any field already equal to what is stored, so the result names only what genuinely changed; otherwise editing a subcategory would report the category as changed too, and the model would repeat that back to the user.

Header-based identity is only sound if headers cannot be forged, so that was tested rather than assumed: sending horizon-user-id: 00000000-dead-beef-… from a client, the gateway overwrote it and the server still saw the real subject. Had it not, this would be an assertion rather than authentication and unusable as a security boundary.

Logging goes to stderr. Over the stdio transport, stdout is the JSON-RPC channel, and a stray print() corrupts the protocol stream.

One connection string, two drivers that disagree about it. DATABASE_URL feeds asyncpg on the server and psycopg in the client's checkpointer. asyncpg rejects libpq query parameters outright; psycopg is built on libpq and wants them. So the server strips sslmode and passes ssl="require" in code, while the client adds sslmode=require back. Both directions are commented, because the natural assumption — that one DSN works everywhere — is wrong.

The checkpointer disables prepared statements. Neon's pooled endpoint is PgBouncer in transaction mode, which hands a different backend to each transaction, so a statement prepared on one connection is missing on the next. prepare_threshold=None avoids it. Left on, this fails intermittently after appearing to work, which is a much worse failure than one that shows up immediately.

The checkpointer uses a pool that checks connections before lending them. Neon's free tier suspends the compute after inactivity, dropping every open connection — and the web app caches a runtime for as long as it is up, so a single held connection eventually goes stale and every later request fails with the connection is closed. It presents as one account being broken, because it hits whoever has been idle longest. AsyncConnectionPool with check=check_connection tests a connection before handing it out and replaces a dead one. The check is the load-bearing part: a pool without it just holds several stale connections instead of one.

The client sets a selector event loop on Windows. psycopg's async mode refuses to run on ProactorEventLoop, the Windows default; asyncio subprocesses on Windows run only on ProactorEventLoop. A stdio MCP connection spawns the server as a subprocess, so a stdio transport and an async Postgres checkpointer cannot share one loop. The client talks HTTP instead — which is what the deployed setup needs anyway. Neither restriction exists on Linux or macOS.

Not implemented yet

Honest limitations rather than oversights:

  • No currency column. Every amount is assumed to be in one currency; the client is told they are rupees.

  • No long-term memory. The agent remembers a conversation, not facts across conversations. Those are genuinely different features and only the first is built.

  • The web app trusts itself. The server believes an asserted user because the caller holds a shared secret. That is the standard backend-for-frontend arrangement, and it means the app is a trusted component: anyone who obtained both the API key and the secret could impersonate any user. A stricter design would have each browser user authenticate to the server directly.

  • Free-tier realities. The database suspends when idle, so the first request after a quiet spell is slow, and one shared API key funds every user's model calls.

Layout

main.py                        the server: six tools, one resource
agent.py                       the agent: MCP session, checkpointer, prompt
client.py                      terminal front-end
app.py                         Streamlit front-end, with Google sign-in
schema.sql                     one-time table + index creation
categories.json                the category taxonomy, single source of truth
.env.example                   documents every variable all three need
.streamlit/secrets.toml.example  the shape of the Google sign-in config

Built with

Server: FastMCP 3 · asyncpg · Neon Postgres · Prefect Horizon

Client: LangGraph · langchain-mcp-adapters · Gemini · Streamlit

Available Tools

6 tools
add_expenseA

Record a single expense.

Pass the user's local date -- the server does not infer 'today', because its clock is UTC and would log the wrong day either side of midnight.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateYesDate the money was spent, YYYY-MM-DD.
noteNoOptional free-text note.
amountYesAmount spent. Must be greater than zero.
categoryYesTop-level category, e.g. 'food'. Must be a known category.
subcategoryNoOptional subcategory, e.g. 'groceries'.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses a subtle, high-impact behavior: the server uses UTC and will not infer today, so the client must pass the user's local date. It does not overstate side effects, but 'record' clearly signals creation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler. The essential behavioral warning about UTC is front-loaded in the second sentence and directly actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create operation with a full output schema and complete parameter documentation, the description covers the key pitfall an agent would likely miss. It does not mention category validation or sibling alternatives, but the schema states 'Must be a known category' and sibling names are self-explanatory.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds real value for the date parameter by explaining why the caller must supply the local date and how the server's UTC clock could cause errors. It does not need to repeat the other parameters since the schema already documents them fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Record a single expense,' which is a specific verb, resource, and scope. This makes it immediately distinct from siblings like list_expenses, delete_expense, and summarize.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The wording implies when to use the tool, but it does not explicitly contrast it with alternatives or state when not to use it. The date guidance is operational context, not a when-to-use vs. alternative boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_expenseA
DestructiveIdempotent

Delete one expense, by id.

Use list_expenses first to find the id, and confirm with the user which one they mean before deleting -- ids are not guessable from a description and deleting the wrong row cannot be undone.

ParametersJSON Schema
NameRequiredDescriptionDefault
expense_idYesid of the expense to delete, from list_expenses.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already mark the tool as destructive and idempotent. The description adds meaningful behavioral context by warning that deleting the wrong row cannot be undone and that user confirmation is required. This goes beyond the annotation flags and helps the agent weigh the consequences of invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loads the core purpose in the first sentence. The second part provides essential usage and safety guidance without redundancy. It is slightly longer than necessary, but every sentence earns its place by adding important operational context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter delete operation, the description covers the key aspects: what to delete, how to get the id, and the need for user confirmation. The presence of destructive and idempotent annotations plus a full output schema means the description does not need to explain return values. Minor gaps, such as related data effects, are not significant for this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, expense_id, has full schema description coverage: it says 'id of the expense to delete, from list_expenses.' The tool description reinforces this by telling the agent to use list_expenses to find the id, but it does not add fundamentally new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate given 100% coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the precise action 'Delete one expense, by id', specifying exactly what resource is affected and how it is identified. This clearly distinguishes it from siblings like add_expense and list_expenses, and no other delete tool exists in the sibling set, so there is no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs the agent to call list_expenses first to obtain the id and to confirm with the user before deleting. It also explains why this is necessary: ids are not guessable and deletion is irreversible. This gives clear when-to-use and safety guidance beyond just naming the operation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_categoriesA

List every valid category and its subcategories.

Call this before logging an expense if you are unsure which category a purchase belongs to. Categories are a fixed taxonomy; anything outside it is rejected.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the disclosure burden. It reveals that categories form a fixed taxonomy and that invalid values are rejected, which is the key behavioral contract for an agent deciding whether to use it. It does not explicitly state that the operation is read-only, though the verb 'List' and the workflow context make that clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no redundancy. The primary action is front-loaded, followed by usage guidance and a validation caveat, making it scannable for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, has no parameters, and has an output schema, so the description need not describe return values. It provides the essential workflow context (when to call and validation behavior) and fits the agent's decision-making needs relative to siblings like add_expense and list_expenses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the input schema is empty and schema description coverage is 100%. The description does not need to explain any parameter semantics, and the baseline for a zero-parameter tool is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the concrete action 'List every valid category and its subcategories', giving a clear verb and resource. It differentiates the tool from sibling expense-management tools by identifying it as a taxonomy lookup rather than a mutation or expense operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs the agent to call this tool 'before logging an expense if you are unsure which category a purchase belongs to', connecting it to the add_expense workflow. It also provides a decisive boundary condition: categories are a fixed taxonomy and anything outside is rejected, so the agent knows when this list is authoritative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_expensesA

List individual expenses, newest first.

All filters are optional; with none set this returns the most recent expenses. Use summarize instead when you want totals rather than rows.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum rows to return.
categoryNoOnly return expenses in this category.
end_dateNoLatest date to include, inclusive, YYYY-MM-DD.
start_dateNoEarliest date to include, inclusive, YYYY-MM-DD.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It discloses ordering ('newest first'), return granularity ('individual expenses' as rows), and default filtering behavior. While it does not explicitly state read-only semantics, 'List' strongly implies a non-mutating operation, and the output schema covers return structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no wasted words. The core purpose and ordering are front-loaded, followed by filter semantics and the alternative-tool pointer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with a rich schema and output schema, the description covers purpose, behavior, defaults, and the main sibling distinction. It does not discuss pagination beyond the `limit` parameter, but that is documented in the schema and not a significant gap here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter and its meaning. The description adds useful high-level context about filters being optional and the default result set, but does not need to compensate for any parameter-schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List individual expenses') plus a clear ordering ('newest first'), and explicitly differentiates itself from the sibling `summarize` by contrasting rows vs. totals. An agent can tell exactly what this tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says all filters are optional and describes the default behavior when none are set. It also names the alternative tool (`summarize`) and the condition for choosing it ('when you want totals rather than rows'), giving clear when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

summarizeA

Total spending over a date range, broken down by category.

Summing happens in Postgres over NUMERIC values, so the total is exact. Prefer this over listing every row and adding them up.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryNoRestrict to one category. When set, the breakdown is by subcategory instead of by category.
end_dateNoLatest date to include, inclusive, YYYY-MM-DD.
start_dateNoEarliest date to include, inclusive, YYYY-MM-DD.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds a non-obvious guarantee: 'Summing happens in Postgres over NUMERIC values, so the total is exact.' This is genuinely useful context about precision. It does not explicitly say the operation is read-only, but the aggregation wording and lack of mutation signals make that reasonably clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences, each earning its place: purpose, correctness guarantee, and usage preference. It is front-loaded with the primary function and contains no redundant filler or repeated schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only aggregate tool with three optional parameters and a present output schema, the description covers purpose, usage guidance, and an important behavioral guarantee. Any remaining edge cases (e.g., empty results, invalid date ranges) are not essential for an agent to invoke the tool correctly, especially since the output schema and parameter descriptions provide the rest.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description only restates the date-range and category-breakdown concepts, adding no new meaning about date formats, inclusive bounds, or the categorical behavior beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Total spending over a date range, broken down by category.' This clearly conveys the aggregation behavior and differentiates it from sibling tools like list_expenses. The phrase 'Prefer this over listing every row' reinforces that it summarizes rather than enumerates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The instruction 'Prefer this over listing every row and adding them up' explicitly tells the agent to use this tool for totals rather than manually aggregating list results. It does not name the sibling tool list_expenses directly, nor does it state exclusions (e.g., 'use list_expenses when line items are needed'), so it falls just short of fully explicit alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoamiA

Report which user the server sees, and whether expenses are scoped.

Worth having permanently rather than as a one-off diagnostic: "why can't I see my expenses?" is answered by this tool in one call, and the answer is almost always that the request arrived unauthenticated and landed in the shared local bucket.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral disclosure burden. It explains that the tool reveals the server-side user, whether expenses are scoped, and that the likely cause of invisibility is an unauthenticated request landing in the shared local bucket. This adds meaningful diagnostic context beyond the tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence is a crisp summary, and the second sentence earns its place by explaining practical value. The wording is slightly discursive with the quoted diagnostic scenario, but overall it is compact and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter diagnostic tool with an output schema, the description covers purpose, usage rationale, and a common failure context. It does not explicitly state that the tool is read-only or side-effect-free, but the name and description strongly imply a safe diagnostic operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the input schema is empty, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and the description appropriately does not invent parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Report which user the server sees, and whether expenses are scoped.' This clearly distinguishes whoami from the expense-management siblings by framing it as a diagnostic identity/scoping tool rather than a data operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a concrete use case: answering 'why can't I see my expenses?' in one call, and advises keeping it permanently rather than as a one-off diagnostic. It does not explicitly contrast against sibling tools or state when not to use it, but the usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedadd_expense
    • First observeddelete_expense
    • First observedlist_categories
    • First observedlist_expenses
    • First observedsummarize
    • First observedwhoami
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0

Scored across 6 tools

Disambiguation4/5

Each tool maps to a distinct action (auth check, category lookup, add, list, delete, summarize), and the list_expenses vs summarize distinction is explicitly drawn as rows versus totals. whoami is a bit of an outlier but clearly scoped to diagnosing visibility. Only minor overlap exists between listing and summarizing expense data.

Naming Consistency4/5

Most tools follow a clear lower_snake_case verb_noun pattern (list_categories, add_expense, list_expenses, delete_expense). summarize and whoami break the noun-object pattern but are still readable and not confusingly styled. The pluralization of expenses is slightly inconsistent (list_expenses vs delete_expense) but harmless.

Tool Count5/5

Six tools is a well-scoped size for an expense tracker: one diagnostic, one taxonomy lookup, and core expense operations. Each tool earns its place without redundancy or bloat. This is in the ideal 3–15 tool range.

Completeness4/5

The core lifecycle is covered: add, list, delete, summarize, plus category validation and auth scoping. The only notable gap is an update/edit operation, but users can delete and re-add an incorrect expense. Overall agents can accomplish expense tracking without dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • expense-mcp

    justfsl50
    A
    license
    A
    quality
    D
    maintenance
    Personal expense tracker MCP server that enables tracking expenses, income, budgets, and savings goals through natural language.
    10
    1
    MIT

  • expense-tracker-mcp-server

    SAYOUNCDR
    F
    license
    B
    quality
    D
    maintenance
    MCP server for tracking personal expenses using FastMCP and SQLite, enabling adding, listing, updating, deleting expenses and summarizing by category via natural language tools.
    5
    1
    -

  • local-expense-tracker

    K37VIN
    F
    license
    Not graded
    quality
    D
    maintenance
    A local MCP server for tracking personal expenses using SQLite, enabling users to add, list, and summarize expenses via natural language.
    -

  • Expense Tracker MCP

    InfoSage05
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server for tracking expenses with local SQLite storage. Provides tools to add, list, and summarize expenses by category.
    -