Supports pricing and cost accounting for OpenAI-compatible models, enabling estimation of model usage costs, comparison of run costs across models, ranking by expected cost per successful task, and tracking spend against budgets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Agent Cost MCP Server compare models for a 2000 input, 500 output token task by cost per success"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives agents and developers tools to estimate, budget, and compare the cost of LLM work before and during a run — the model-spend counterpart to AWS infrastructure cost tooling.
Agent frameworks decide for themselves how many model calls a task takes, so the cost of a run is usually only visible after the bill arrives. This server answers, from inside your tooling:
What will this task cost on model A vs model B?
Which model is cheapest per successful task, not per token?
Has this run already burned its budget?
The server is self-contained: a maintained pricing snapshot ships with it, no AWS account or API key is needed, all state is a local JSON ledger, and it makes no network calls at runtime.
Tool | Arguments | Returns |
|
| Input/output/total cost in USD for one concrete usage record |
|
| The model's cost for one run, plus the same workload priced on every other model, cheapest first |
|
| All models ranked by expected cost per successful task (cost per attempt ÷ success rate) |
|
| The recorded ledger entry, priced at list rates |
|
|
|
Cost per token is the wrong ranking for agent work: a cheap model that
fails half its tasks costs more per success than a pricier, reliable one.
Pass measured success rates to compare_models_for_task if you have them;
models without a supplied rate are ranked on raw cost.
This server supplies the numbers. Enforcing a budget (stopping a run) belongs to the agent framework — see BudgetedModel in strands-agents/samples for that pattern.
Related MCP server: CosTrack MCP
Run it with uvx:
{
"mcpServers": {
"agent-cost": {
"command": "uvx",
"args": ["agent-cost-mcp-server"]
}
}
}Or install with pip:
pip install agent-cost-mcp-server
agent-cost-mcp-serverPrices live in src/agent_cost_mcp_server/pricing.json — a versioned
snapshot of list prices (USD per 1M tokens) for major Bedrock and
OpenAI-compatible models, dated in the file. Prices change; verify against
the provider's pricing page before making spending decisions. Updating the
snapshot is a one-file change, and the server reads it at startup.
record_spend appends to a local JSON ledger at
~/.agent-cost-mcp-server/ledger.json. Set AGENT_COST_LEDGER_PATH to use
a different file. Nothing leaves the machine.
The pricing and cost-per-success model are a port of tokenecon, an open-source library for per-task agent cost accounting (paper: doi.org/10.5281/zenodo.23195511), including a Strands integration that prices live agent runs. This server exposes the same math over MCP so any agent or IDE can call it.
Proposed for the awslabs/mcp collection in RFC #4772.
uv sync --extra dev # or: pip install -e ".[dev]"
pytestApache-2.0 — see LICENSE.
Copyright 2026 Karmendra Pandey.
Check a task's recorded spend against a budget.
Args: task_id: The task identifier used with record_spend. budget_usd: The budget for the task, in USD.
Returns spent, remaining, call count, and whether the task is over budget. This server supplies the numbers; enforcing the budget (stopping a run) belongs to the agent framework.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| budget_usd | Yes |
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 describes the returned values and draws an important boundary: the server reports spend status but does not stop runs or enforce the budget. It could still be more explicit about read-only behavior, permissions, or error conditions, but the key behavioral trait is clearly disclosed.
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 front-loaded with the tool's purpose, then cleanly documents arguments, return values, and the server-versus-framework responsibility boundary. Every part is relevant and the overall length is appropriate for a simple two-parameter tool.
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?
For a simple read-style status tool with no output schema and no annotations, the description supplies the needed context: what it checks, both parameter meanings, what it returns, and what it explicitly does not do. An agent can call it correctly without additional structured documentation.
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%, so the description must compensate for both parameters. It does: task_id is explained as the identifier used with record_spend, and budget_usd is explained as the budget in USD. Both required parameters are given meaning beyond their bare 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 states a specific verb and resource: checking a task's recorded spend against a budget. It clearly differs from record_spend by referring to recorded spend and by noting that enforcement belongs to the agent framework, but it does not explicitly contrast with the other sibling tools such as estimate_run_cost or price_usage.
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 after spend has been recorded, since task_id is described as the identifier used with record_spend. It also clarifies that the server only supplies numbers and does not enforce the budget, which is useful usage context, but it gives no explicit when-to-use or when-not-to-use guidance relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank models for a task by expected cost per successful task.
Cost per token is the wrong ranking for agent work: a cheap model that fails half its tasks costs more per success than a pricier, reliable one. Pass measured success rates (0-1 per model_id) if you have them; models without a supplied rate are ranked on raw cost.
Args: input_tokens: Input tokens for one attempt at the task. output_tokens: Output tokens for one attempt at the task. success_rates: Optional map of model_id to success rate in (0, 1].
| Name | Required | Description | Default |
|---|---|---|---|
| input_tokens | Yes | ||
| output_tokens | Yes | ||
| success_rates | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses ranking methodology and fallback behavior for missing success rates, which is useful, but says nothing about output format, prerequisites, or what models are ranked.
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?
Front-loads purpose in the first sentence, then rationale, then an Args list that fills schema gaps. No filler; every sentence adds either justification or parameter semantics.
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?
No output schema and no annotations, so the description should help interpret returns. It fully covers parameters and purpose, but does not describe the ranking output format or edge cases, leaving a clear gap for a tool whose result is a ranked list.
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%, so the description compensates by documenting all three parameters: input/output tokens as 'for one attempt at the task' and success_rates as an optional model_id-to-rate map in (0,1]. This adds substantial meaning beyond the bare schema types.
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?
States a specific verb 'Rank' and resource 'models for a task' with a precise metric: 'expected cost per successful task'. It contrasts with cost-per-token ranking, but does not explicitly name or differentiate from sibling tools like estimate_run_cost or price_usage.
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 context for when to supply success_rates and how missing rates are treated (ranked on raw cost), but never states when to choose this tool over sibling cost tools or when not to use it. Usage is implied by the purpose rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate what one run of a workload will cost on a model.
Args: model_id: Model to price the workload on. input_tokens: Expected input tokens for one run. output_tokens: Expected output tokens for one run.
Returns the model's cost plus the same workload priced on every other model in the snapshot, cheapest first.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | ||
| input_tokens | Yes | ||
| output_tokens | 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 does disclose the return behavior — the target model's cost plus every other model's cost, cheapest first — which is genuinely useful. However, it never states that this is a read-only, side-effect-free operation, and it doesn't cover errors or limits.
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 core purpose is front-loaded in the first sentence and the Args/Returns split is easy to scan. The Args block partially duplicates schema property names, which is defensible given 0% schema coverage, so little is wasted.
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?
With no output schema, the description properly explains the return payload, and with no annotations it partially covers behavior. Gaps remain: what format model_id takes, what the 'snapshot' refers to, and whether the operation has any side effects.
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 the description must compensate. The Args section gives meaning to all three parameters, notably scoping the token counts to 'for one run.' This is adequate but thin — no format or example for model_id, and no unit or magnitude guidance.
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 a specific verb and resource: 'Estimate what one run of a workload will cost on a model.' An agent can distinguish this from budget_status or record_spend. It doesn't explicitly name or contrast with the closest sibling, price_usage, which also deals with cost computation.
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 scenario of use is implied by 'one run of a workload,' but there is no explicit when-to-use or when-not guidance. With siblings like price_usage and compare_models_for_task, the description should route the agent between them but does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Price a concrete usage record at a model's list rates.
Args: model_id: Model identifier from the pricing snapshot, e.g. "anthropic.claude-sonnet-4-5" or "openai.gpt-5-mini". input_tokens: Input (prompt) tokens consumed. output_tokens: Output (completion) tokens consumed.
Returns the input/output/total cost in USD.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | ||
| input_tokens | Yes | ||
| output_tokens | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that pricing comes from a 'pricing snapshot' at list rates and that the result is USD cost, but says nothing about unknown model handling, rounding, or what happens if the model isn't in the snapshot. Partial behavioral coverage only.
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?
Front-loaded purpose sentence followed by args and a return note; every line is functional. Slightly list-like but no wasted prose.
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?
For a simple compute tool, the description covers inputs, their formats, and the return shape in USD despite no output schema. Remaining gap is absence of error/edge-case behavior.
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%, so the description must compensate, and it does: it documents all three parameters with concrete model_id examples ('anthropic.claude-sonnet-4-5') and clarifies token semantics (prompt vs. completion). That is meaningful added value beyond the bare 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?
States a specific verb+resource: 'Price a concrete usage record at a model's list rates.' The word 'concrete' implicitly distinguishes it from the estimate sibling, but no sibling is named outright. An agent can mostly tell what it does.
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 distinction from estimate_run_cost is only implied via 'concrete usage record' vs. an estimate; no explicit when-to-use or when-not-to-use guidance is given. For a tool sitting among four cost-related siblings, more routing guidance would be expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a run's actual token usage in the local per-task ledger.
Args: task_id: Caller-chosen identifier grouping one task's runs. model_id: Model the run used. input_tokens: Actual input tokens consumed. output_tokens: Actual output tokens consumed.
Returns the recorded entry, priced at the model's list rates.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| model_id | Yes | ||
| input_tokens | Yes | ||
| output_tokens | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the persistence target ('local per-task ledger') and the return ('priced at the model's list rates'), but says nothing about whether repeated calls for the same task_id append or overwrite, whether the write is reversible, or what happens when model_id is unknown to the pricing table. For a mutation tool with zero annotation coverage this is thin.
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?
Front-loaded purpose sentence, then a compact Args block where every line adds semantics absent from the schema, then a one-line return note. 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?
Covers purpose, all four parameters, and the return shape without an output schema. The gap is behavioral: no guidance on idempotency/append semantics or error cases, which matters for a ledger-writing mutation with no annotations to lean on.
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%, so the description must compensate, and it does: all four parameters are documented with meaning beyond their names, notably task_id as a 'caller-chosen identifier grouping one task's runs' and the input/output token counts as 'actual' consumption. Only model_id is restated near-tautologically.
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?
States a specific verb and resource with scope: 'Record a run's actual token usage in the local per-task ledger.' The word 'actual' implicitly contrasts with the estimation siblings (estimate_run_cost, price_usage), but no sibling is named explicitly, so the differentiation is left to inference.
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?
Usage is implied rather than stated: recording 'actual' usage signals the post-run scenario as opposed to the estimation tools. There is no explicit when-to-use, no named alternative, and no prerequisite (e.g., whether the model must already be priced).
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.
v0.1.0budget_statuscompare_models_for_taskestimate_run_costprice_usagerecord_spendScored across 5 tools
price_usage and estimate_run_cost both price input/output tokens and could be momentarily confused, but the descriptions clearly separate a concrete recorded usage from a projected single run with cross-model comparison. compare_models_for_task (success-rate ranking), record_spend (ledger write), and budget_status (ledger read) each target a distinct concern.
Four names follow a clean verb_noun snake_case pattern (price_usage, estimate_run_cost, compare_models_for_task, record_spend). budget_status is a noun_noun query name, a minor deviation, but the set remains readable and predictable.
Five tools is well-scoped for a cost estimation server: price, estimate, compare, record, and check budget. No tool is redundant and none feels like filler.
The pricing, projection, ranking, recording, and budget-checking lifecycle is covered, with estimate_run_cost implicitly exposing the model snapshot. Minor gaps remain: no explicit tool to list available models or model_ids, and no way to read back or clear ledger entries beyond budget_status.
Enforce AI budgets before the model call and track cost per customer across 10 providers.
Cost per run, tool, model and day for AI agents, from one call or an OpenTelemetry export.
Budget & cost control for AI agents — per-agent spend caps + rate limits before each call.
Track API spend, credit balances and runway across OpenAI, Anthropic, OpenRouter and 25 more.