This MCP server tracks LLM API usage and costs across multiple providers (Anthropic, OpenAI, DeepSeek, Qwen) via a local SQLite database, exposing tools to record, query, compare, and recommend models based on spend data.
Record usage (record_usage): Log an LLM API call with token counts (input, output, cache read/write), provider, model, project, tags, duration, and success status. Cost is automatically computed from the pricing table; a request_id prevents double-counting.
Query spending (query_spend): Get spending totals and rollups over a custom time window, grouped by provider, model, project, tag, or day, with optional filters for provider/model/project and failed calls.
Usage summary (usage_summary): A quick snapshot for today, week, month, or year — total cost, call count, top-3 providers, top-3 models by cost, and the single most expensive call.
Compare providers (compare_providers): Given a hypothetical workload (input/output tokens), rank every priced model by projected cost (cheapest first) with relative cost percentages, supporting model filtering and deduplication of variants.
Recommend a model (recommend_provider): Find the cheapest model fitting a stated budget and workload, with optional provider/model filtering. Returns the top pick plus two runner-up alternatives with reasoning.
Inspect pricing (get_pricing): Look up current per-million-token rates (input, output, cache read/write) for any model or provider.
List providers (list_providers): View all supported providers, their available models, and whether they use the OpenAI-compatible API format.
Captures and tracks spending on calls to OpenAI's API, including GPT models, with per-provider cost breakdown.
Stop treating your LLM API bills like a scary horror movie you only look at through your fingers at the end of the month. Know what your LLM calls actually cost — across every provider, in one place, on your own machine. Ask your coding agent (MCP) or type a command (CLI).
It's a cost meter, not a router: it tells you what you spent and which provider fits a workload — it never changes your calls. Pairs happily alongside a router or a model-leaderboard tool.
Or straight from the terminal — your week's spend, broken down by provider, and a cross-provider cost comparison before you commit to a model:
You're calling LLMs from a handful of providers — Claude, GPT, plus Chinese models like Qwen and DeepSeek. Each one bills in its own dashboard, in its own currency, with its own rules for what a "cached token" costs. So the simplest possible question — how much am I spending, and on what? — turns into four browser logins, looking up exchange rates for RMB to USD, and trying to decipher what a "cached context token discount" actually means in midnight math. Most people just cross their fingers and let the bill be a surprise at the end of the month.
llm-usage-mcp captures every call you make into one local store, costs it correctly per provider at the moment it happens, and hands the answer back two ways:
Ask your coding agent. It's an MCP server, so Claude Code, Cursor, or any MCP client can answer "how much did I spend on Claude this week?" or "which provider is cheapest for a 10k-in / 2k-out call?" in plain English.
Or type a command. It's also a CLI — llm-usage spend, llm-usage compare, llm-usage recommend — for when you'd rather not round-trip through an agent.
And it stays out of your way:
Local-first. No SaaS, no signup, no telemetry. Just a SQLite file at ~/.llm-usage/usage.db. Privacy is a feature, not a setting.
Multi-provider, Chinese models included. Anthropic, OpenAI, DeepSeek, Qwen — streaming and non-streaming for all four. DeepSeek and Qwen run the same capture path as Anthropic and OpenAI, not a bolted-on afterthought. More providers (Gemini, Bedrock, Moonshot, …) are on the way.
Related MCP server: MCPSpend
Two minutes from git clone to your first captured call. This part is about capture — getting calls recorded. Reading the data back comes next.
Install from PyPI with uv (or pipx) — this puts the three console scripts on your PATH:
uv tool install llm-usage-mcp # or: pipx install llm-usage-mcpPrefer to hack on it? Clone and sync from source instead:
git clone https://github.com/zhaoyue722/llm-usage-mcp.git
cd llm-usage-mcp
uv syncEither way you get three console scripts:
llm-usage — the multi-command CLI. See From the command line (CLI) below.
llm-usage-mcp — the stdio MCP server.
llm-usage-proxy — a back-compat alias; identical to llm-usage proxy.
The Quickstart below uses
uv run …(the from-source workflow). If you installed from PyPI, the scripts are already on yourPATH— drop theuv runprefix, and register the MCP server withclaude mcp add llm-usage -- llm-usage-mcp.
You only need a key for the provider(s) you actually use; the proxy starts regardless and per-route requests return 503 configuration_error for any provider whose key is missing.
export ANTHROPIC_API_KEY=sk-ant-...
# and/or:
export OPENAI_API_KEY=sk-...
export DEEPSEEK_API_KEY=sk-...
export DASHSCOPE_API_KEY=sk-... # QwenFull env-var reference: docs/configuration.md (or copy .env.example to .env and fill in).
uv run llm-usage-proxyIt binds loopback-only (127.0.0.1:5525) — never reachable from the network. The proxy holds your API keys server-side; clients never need them.
The proxy exposes one route per provider. Set the matching *_BASE_URL env var on the client side:
Provider | Client env var | Value |
Anthropic |
|
|
OpenAI |
|
|
DeepSeek |
|
|
Qwen | DashScope OpenAI-compatible base |
|
Example — launch Claude Code with calls routed through the proxy:
ANTHROPIC_BASE_URL=http://127.0.0.1:5525 claudeMake a call through your agent (or any client pointed at the proxy), then check it landed:
uv run llm-usage spendEvery call lands in ~/.llm-usage/usage.db with tokens, cost, latency, and a request_id for idempotency — and shows up in that headline. That's the whole loop: capture on one side, answers on the other.
Once calls are being captured, you read them back two ways. Same data, same numbers — pick whichever fits the moment.
Register the MCP server with Claude Code:
claude mcp add llm-usage -- uv --directory $(pwd) run llm-usage-mcpThen just ask, in plain English, inside that session:
How much did I spend on Anthropic today? Which provider is cheapest for a 10k-input / 2k-output call?
Claude picks the right tool and reads the numbers back. Seven tools are exposed over stdio; full param/return shapes are in docs/spec.md.
Tool | Purpose |
| Totals + per-group rollups over a time window (group by provider / model / project / tag / day). |
| Headline summary for |
| Given a hypothetical workload (tokens in / out), rank every priced model by cost. |
| Pick the cheapest priced model that fits a stated budget. |
| Inspect the vendored pricing snapshot. |
| List providers + their models + OpenAI-compatibility flag. |
| Manual write path — log a call when the capture proxy isn't in the picture. |
query_spend and usage_summary default to include_failed=false so partial-stream rows don't pollute totals; opt-in via the param.
The same questions, as a CLI — eight subcommands under one llm-usage console, for when typing is faster than asking your agent.
The examples below assume
llm-usageis on yourPATH— eithersource .venv/bin/activateoruv tool install .. Otherwise, prefix each command withuv run(e.g.uv run llm-usage spend).
$ llm-usage
Local-first LLM spend capture + query, exposed over MCP.
Commands
proxy Run the local LLM capture proxy on 127.0.0.1.
compare Project the cost of a hypothetical workload across every priced model.
models Browse the local pricing catalog.
recommend Recommend the cheapest priced model for a workload + budget.
spend Show recorded spend over a calendar period.
status Snapshot of the local install: DB, proxy, providers, pricing.
providers List configured providers with key state, wire-format, model count.
about Show version, author, license, and the project homepage.Command | The question it answers |
Given a workload, who's cheapest? | |
What do they actually charge per million tokens? | |
I've got $0.04 left — which model won't bankrupt me? | |
How much did I just spend? | |
Is everything actually working? | |
What's configured locally? | |
What is this, and where do I report a bug? | |
| Run the capture proxy (same as |
Conventions that hold across every command:
--json emits the same Pydantic shape the matching MCP tool returns. Pipe straight into jq.
--color {auto,always,never} honors NO_COLOR and TTY detection. The palette is a warm, low-contrast dark theme — easy on the eyes at 11pm.
Filter flags (--provider, --model) are case-insensitive on providers, case-sensitive on models, and repeatable where they act as whitelists.
--version / -V prints the version and exits. --install-completion {bash|zsh|fish|powershell} installs a tab-completion script — one shell restart later, every flag is <Tab>-able.
compareRank every priced model by projected cost for an n-input / m-output call. Cheapest first, percent against the cheapest. Default view family-deduplicates rows that share both a model family root and an identical price — so gpt-5-mini and gpt-5-mini-2025-08-07 collapse to one row with ×2. Pass --all to see every catalog row.
# How does an 8k-in / 2k-out call price out today?
$ llm-usage compare --in 8000 --out 2000
# Just OpenAI's models:
$ llm-usage compare --in 8000 --out 2000 --model gpt-5-mini --model gpt-5-nano
# Same projection, JSON for a script:
$ llm-usage compare --in 8000 --out 2000 --json | jq '.ranked[0]'
modelsCatalog browser. Sibling of compare, but answers "what does this model charge?" rather than "what would my workload cost?". Rates per million tokens, sorted alphabetically by provider by default; switch with --sort input or --sort output to find the cheapest in either axis. Cache rates are hidden until you ask (--cache) because most models don't have them and empty columns waste width.
# Full catalog, deduped.
$ llm-usage models
# OpenAI's nano models only, with cache rates:
$ llm-usage models --provider openai --match nano --cache
# Cheapest input rate first — quick "what's the floor right now?":
$ llm-usage models --sort inputrecommendPicks one. Filters by --provider, --model, and --budget, then returns the cheapest match plus two runner-ups. The reasoning string explains what it assumed and what got chosen, so you can sanity-check rather than trust blindly.
# Cheapest priced model, full stop.
$ llm-usage recommend
# Anything Anthropic that fits under one cent for a 1k/1k call:
$ llm-usage recommend --provider anthropic --budget 0.01
# Of these three specific candidates, which wins?
$ llm-usage recommend --model gpt-5-mini --model claude-sonnet-4-6 --model qwen-maxv1 ranks by cost only. --task is optional and surfaces in the reasoning text; it doesn't drive selection (the tool isn't an LLM and can't interpret free text).
spendRead the SQLite. The default view is a usage_summary headline — total dollars, top-3 providers, top-3 models, largest single call. Pass --group-by to switch into rollup mode.
# Headline for this week.
$ llm-usage spend
# This month grouped by model, JSON for a dashboard:
$ llm-usage spend --period month --group-by model --json | jq
# Spend on a specific project tag, day-by-day:
$ llm-usage spend --group-by day --project my-side-thingPeriod boundaries are calendar UTC: today = since 00:00 UTC, week = since Monday, month = since the 1st, year = since January 1st. Failed / partial-stream rows are excluded by default; opt in with --include-failed.
statusOne screen, four sections: Database, Capture proxy, Providers, Pricing. The "is everything actually working?" command. Read-only — running it on a fresh install before you've ever booted the proxy or MCP server prints database not initialized rather than silently creating the file.
$ llm-usage status
# Skip the network probe (offline, CI, slow link):
$ llm-usage status --no-net
# Machine-readable for a healthcheck script:
$ llm-usage status --jsonprovidersPer-provider configuration view. Wider than the status Providers block: adds the wire-format flag (openai-compat: yes/no) and an optional --models expansion that lists every priced model under each provider.
$ llm-usage providers
$ llm-usage providers --models # expand each provider with its model listaboutThe front-door panel: version, author, license, and the project homepage. The human-facing companion to --version — fields are read from the installed package metadata, so they match what PyPI shows.
$ llm-usage about
# Machine-readable, for a script or an issue template:
$ llm-usage about --jsonProvider | Auth | Non-streaming | Streaming | Cache pricing |
Anthropic |
| yes | yes |
|
OpenAI |
| yes | yes | nested |
DeepSeek |
| yes | yes |
|
Qwen (DashScope) |
| yes | yes | usually omitted on the OpenAI-compat endpoint |
More on the way. Google Gemini, AWS Bedrock, Moonshot (Kimi), Zhipu GLM, MiniMax, and others are scoped in docs/post_v1_providers.md.
Where prices come from. Pricing is a vendored, trimmed snapshot of LiteLLM's pricing JSON, refreshed weekly by a GitHub Action (refresh-pricing.yml). Models LiteLLM doesn't carry yet are filled in locally via pricing_overrides.json.
Everything is env vars (or a .env file at the repo root). Defaults are sane — nothing is required to start the proxy. Full reference: docs/configuration.md. The three you're most likely to touch:
Variable | Default | Purpose |
|
| Where the local DB lives. |
|
| Capture proxy port (loopback only). |
| each provider's official endpoint | Point a provider at a reverse proxy / gateway — handy in network-restricted regions. |
A minimal Dockerfile is included only for automated MCP registry validation (e.g. Glama), which verifies that the packaged server boots and responds to MCP introspection. The recommended way to run the server is still uvx llm-usage-mcp locally — this is a local-first tool, not a hosted service.
MIT.
Project the cost of a hypothetical workload across providers/models.
Returns models ranked by absolute cost ascending, with
relative_cost_pct measured against the cheapest entry
(cheapest = 100%). models, if given, restricts the comparison to
those model names. Cost is computed from input/output tokens only;
RankedEntry.notes is always None in v1 (the field is retained
for future per-row caveats like "tiered pricing approximated").
include_snapshots=False (the default) family-dedups the ranked
list: rows sharing both a model-family root (gpt-5-mini ↔
gpt-5-mini-2025-08-07) AND an identical projected cost collapse
to one representative, with RankedEntry.variant_count recording
how many catalog rows the entry stands for. Set
include_snapshots=True to see every catalog row (each with
variant_count=1) — useful when comparing snapshot-by-snapshot
pricing for production pinning.
| Name | Required | Description | Default |
|---|---|---|---|
| models | No | ||
| include_snapshots | No | ||
| expected_input_tokens | Yes | ||
| expected_output_tokens | Yes |
| Name | Required | Description |
|---|---|---|
| ranked | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does so thoroughly. It explains the output format (ranked by absolute cost, relative_cost_pct, variant_count), dedup behavior, snapshot inclusion, and that 'notes' is always None in v1. No behavioral traits are hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly verbose but front-loads the main purpose. Each sentence adds value, though some details (like 'notes is always None') could be omitted or moved to an output schema. Overall structured well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers essential aspects: input parameters, dedup logic, and output ranking. An output schema exists (though not fully shown), and the description complements it. Minor gaps: no mention of error cases or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning: 'models' restricts comparison, 'include_snapshots' controls dedup, and token parameters are implied. However, it does not explicitly restate the required token parameters' roles, though they are self-explanatory from their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Project the cost of a hypothetical workload across providers/models.' It uses a specific verb ('Project') and resource ('cost'), and distinguishes from siblings like 'list_providers' by focusing on cost projection and ranking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (for cost projection) and explains options like 'include_snapshots' and 'models'. However, it does not explicitly differentiate from sibling tools such as 'get_pricing' or 'recommend_provider', leaving some ambiguity about when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return current pricing for one model, one provider, or all models.
Both filters are optional and AND-combined. An unknown
(provider, model) returns an empty list rather than an error — the
caller can distinguish "model not in our table" from "no model
matches your filter" by passing provider alone.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | ||
| provider | No |
| Name | Required | Description |
|---|---|---|
| models | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries burden and adds behavioral context: filter combination logic and empty list return for unknown pairs. Does not cover rate limits or auth, but provides key behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by behavioral detail. No wasted words, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, description explains key return behavior (empty list). Could mention output schema fields briefly, but is complete enough for selection. Slightly more detail on output would improve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains parameters as filters (model, provider) and their optionality, but lacks individual parameter details like format. Adequate but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return current pricing for one model, one provider, or all models,' specifying the verb (return) and resource (pricing), and distinguishes from sibling tools that handle providers, comparisons, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains that both filters are optional and AND-combined, and describes behavior for unknown (provider, model) returning empty list, which guides usage. Could explicitly state when to use vs alternatives, but sibling differentiation is clear from purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every provider we know about, with their models and OpenAI-compat flag.
Sources the provider/model lists from pricing_snapshot, so a
provider whose pricing hasn't been seeded simply doesn't appear.
After bootstrap() runs on a fresh install this includes every v1
provider (anthropic, openai, qwen, deepseek). Order is alphabetical
by provider, then by model within each provider.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| providers | Yes |
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 that the list depends on pricing_snapshot, that unseeded providers are omitted, and ordering is alphabetical. These are useful behavioral traits for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is clear and front-loaded with the main purpose. It uses multiple sentences but each provides necessary detail about source, provider selection, and ordering. Could be slightly more terse, but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown, but indicated), the description does not need to detail return values. It explains the source, ordering, and which providers appear. For a zero-parameter list tool, this is complete and informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description compensates by explaining the output content (models, flag) and ordering. This adds value beyond the empty schema, earning a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List every provider we know about, with their models and OpenAI-compat flag.' It specifies the action (list) and resource (providers), and adds details about what is included (models, flag) and ordering. This distinguishes it from sibling tools like compare_providers and get_pricing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that providers appear only if pricing is seeded, and after bootstrap it includes specific providers. However, it does not explicitly state when to use this tool versus alternatives, such as when to use compare_providers or get_pricing instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return spending broken down by a chosen axis over a time window.
start and end are ISO-8601 strings (trailing-Z, +00:00, or
naive — naive is interpreted as UTC). Default window is the last
30 days. group_by is one of provider | model | project | tag | day.
filter AND-combines optional provider/model/project equality
predicates.
include_failed defaults to False so failure rows (e.g. streams
that died mid-flight with partial counts) are excluded from totals
and groups. Pass True to fold them back in — useful for debugging
capture-layer behavior, not for honest spend numbers.
Tag semantics: events with NULL/empty tags are excluded from
group_by="tag" results entirely; multi-tag events contribute once
per tag (so per-group calls sums can exceed the window total).
Project semantics are symmetric: NULL projects are dropped from
group_by="project". Groups are ordered cost-desc with
alphabetical ties.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| start | No | ||
| filter | No | ||
| group_by | No | provider | |
| include_failed | No |
| Name | Required | Description |
|---|---|---|
| groups | Yes | |
| total_calls | Yes | |
| total_cost_usd | Yes | |
| total_input_tokens | Yes | |
| total_output_tokens | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description fully discloses behavioral traits: tag semantics (NULL exclusion, multi-tag duplication), project semantics, ordering by cost-desc, and include_failed purpose (debugging vs honest spend). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded purpose and detailed parameter explanations. It is slightly long but every sentence adds value. Minor redundancy in tag semantics, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, 1 enum, and a nested object, the description covers all input semantics comprehensively. An output schema exists but is not shown, so no need to explain return values. Complete for effective tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining each parameter: start/end format and default, group_by enum values, filter predicates, and include_failed meaning. Adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns spending broken down by a chosen axis over a time window. It specifies the verb "return" and resource "spending" with clear breakdown dimensions, distinguishing it from siblings like compare_providers and usage_summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on default behavior (e.g., 30-day window, include_failed=False) but does not explicitly state when to use this tool versus alternatives like compare_providers or usage_summary. No exclusions or when-not-to-use guidance are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend the cheapest priced model that fits the workload + budget.
v1 ranks by cost only. A future release will incorporate quality
benchmarks (see quality_snapshot — the table is reserved for that
purpose) and accept a quality_priority axis; for v1 those would
rely on data we don't yet have, so the surface stays cost-only and
honest.
expected_input_tokens / expected_output_tokens default to a
nominal 1k/1k workload when absent; the reasoning notes when
defaults are in use. budget_usd, when set, filters out models
that exceed it — if nothing fits, falls back to the cheapest model
overall (the result fields are required, so there's no "no match"
return shape) and the reasoning says so plainly.
providers / models are optional whitelists (AND-combine when
both passed). Both are applied before the budget cut, so an over-
budget fallback returns the cheapest within the filter set rather
than the cheapest priced model overall. A whitelist that matches
nothing raises rather than fabricating a result — likely a
spelling error in the caller's name list.
task_description is optional and echoed into the reasoning
but does not drive selection — the tool isn't an LLM and can't
interpret free text. Omit it (or pass None) and the reasoning
opens with "Recommending …" instead of "For task 'X': …".
| Name | Required | Description | Default |
|---|---|---|---|
| models | No | ||
| providers | No | ||
| budget_usd | No | ||
| task_description | No | ||
| expected_input_tokens | No | ||
| expected_output_tokens | No |
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| provider | Yes | |
| reasoning | Yes | |
| alternatives | Yes | |
| estimated_cost_usd | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: v1 cost-only, default token values, budget fallback, whitelist AND-combination, error on unmatched whitelist, and non-functional task_description. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer but well-structured with clear sections. Every sentence adds value, though slight trimming could be possible. Front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no required, no annotations), the description is extremely complete. It covers return reasoning, fallback behaviors, error cases, and future plans. The output schema exists but is not needed for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter's effect: models/providers as whitelists, budget_usd as filter with fallback, task_description as echoed only, and token defaults. Adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Recommend the cheapest priced model that fits the workload + budget.' It uses a specific verb ('Recommend') and resource ('cheapest priced model'), and distinguishes from sibling tools like compare_providers and get_pricing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed guidance on default behaviors, budget fallback, whitelist logic, and optional parameters. While it doesn't explicitly contrast with siblings, the context is clear enough for an agent to decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a single LLM API call with token counts.
Cost is computed automatically from the pricing table at insert time.
request_id enables idempotent recording — replaying a log file
won't double-count.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| model | Yes | ||
| project | No | ||
| success | No | ||
| metadata | No | ||
| provider | Yes | ||
| error_type | No | ||
| request_id | No | ||
| duration_ms | No | ||
| input_tokens | Yes | ||
| output_tokens | Yes | ||
| cache_read_tokens | No | ||
| cache_write_tokens | No |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| warning | Yes | |
| cost_usd | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses automatic cost computation and idempotency. However, it does not describe side effects such as failure handling, whether it updates existing records, or other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but its brevity sacrifices essential detail, especially parameter descriptions. It is not as helpful as it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 13 parameters and the presence of an output schema (not detailed), the description is incomplete. It lacks parameter explanations and output behavior, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no explanation for any of the 13 parameters (4 required). With 0% schema description coverage, the tool fails to help the agent understand parameter meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a single LLM API call with token counts, and mentions automatic cost computation and idempotency. It distinguishes from sibling tools like query_spend or usage_summary, which are read-oriented.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for recording API calls, but does not explicitly state when not to use it or suggest alternative tools. The mention of idempotent recording via request_id provides some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a one-shot summary of usage over a named calendar period.
period is one of today | week | month | year (default: "week").
Boundaries are calendar UTC: today = since 00:00 UTC today,
week = since Monday 00:00 UTC, month = since the 1st of the
month, year = since January 1st. Returns totals, the top-3
providers and top-3 models by cost (with pct of total), and the
single most expensive call in the window — or largest_call=None
when the window is empty.
include_failed defaults to False: totals, top-N rollups, and
largest_call all exclude success=False rows (partial-stream
captures and other failure rows). Pass True for symmetric
debugging access to the failure population.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | week | |
| include_failed | No |
| Name | Required | Description |
|---|---|---|
| period | Yes | |
| call_count | Yes | |
| top_models | Yes | |
| largest_call | Yes | |
| top_providers | Yes | |
| total_cost_usd | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It explains the date boundaries, exclusions for failures, and the return of largest_call=None when empty. It does not explicitly state read-only nature but is thorough for a non-destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence is useful. The description is front-loaded with the main purpose, followed by parameter details in a clear and structured format. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only 2 optional params and an output schema exists (though not provided), the description covers the essential behavior and edge cases. It could mention output currency or read-only nature, but it is complete for its intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully explains both parameters: period with enum values and calendar boundaries, include_failed with default and effect on totals/rollups. This adds complete meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns a one-shot summary of usage over a calendar period. It uses a specific verb 'return' and resource 'usage summary', and clearly distinguishes from sibling tools like query_spend (detailed query) and record_usage (recording).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for quick summaries but does not explicitly state when to use this tool over alternatives like query_spend or compare_providers. No when-not or alternative references provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2compare_providersget_pricinglist_providersquery_spendrecommend_providerrecord_usageusage_summaryEach tool has a clearly distinct purpose: compare_providers for cost projection, get_pricing for current rates, list_providers for provider info, query_spend for spending breakdown, recommend_provider for cheapest model, record_usage for logging calls, and usage_summary for period summaries. No overlap in functionality.
Most tools follow a consistent verb_noun snake_case pattern (e.g., compare_providers, get_pricing, list_providers, query_spend, recommend_provider, record_usage). The only minor deviation is 'usage_summary' which is noun_noun but still clear and fits the style.
With 7 tools, the set is well-scoped for an LLM usage and cost tracker. It covers listing, comparing, recommending, recording, and querying without being overwhelming or sparse.
The server provides core functionality for tracking usage and costs, including recording, querying, and cost projection. Minor gaps exist: no tool to update/delete usage records or manage provider/pricing data, but these are likely intentional for a read-focused tracker.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Agent Cost Allocator MCP — multi-tenant LLM cost attribution for chargeback billing. Companion to
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
See, price, and control every tool call your AI agents make: policy checks, cost, and audit tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/zhaoyue722/llm-usage-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
