Put the Arithmetic in the Tool: an MCP Server for an AWS Waste Scanner

A developer built zombiescan, an open-source AWS waste scanner, and wrapped it in a Model Context Protocol (MCP) server so AI agents can query cost data through the same engine a terminal uses. The server exposes five read-only tools — including scan_account and estimate_savings — that return precomputed totals, counts, and breakdowns rather than raw rows, after testing showed a small model answered a simple counting question wrong in twenty out of twenty calls. An end-to-end test holds the terminal and MCP front doors to identical dollar figures.

This article provides a step by step guide to adding an MCP server to an AWS cost scanner so an agent drives the same engine a terminal does. Every tool returns figures the engine computed, and the two front doors are held to the same number by an end-to-end test. https://github.com/xbill9/zombiescan https://github.com/xbill9/zombiescan A scan produces one JSON document. A person reads it through a terminal table; an agent reads it through whatever tool it is given. Both quote dollar figures to whoever asked. When the two disagree, one of them is wrong in a way that survives review, because each looks sourced. A model handed a list of rows and asked "how much is this costing" does the addition in the answer. Eleven small integers are enough to break that: one small model asked how many of eleven ids were 10 or more answered wrong in twenty calls out of twenty. Push the count into the engine and the same question is right every time. So the tools here return totals, counts, breakdowns, minima and maxima, and the filter that produced them. aws login , a profile, SSO or environment variables uv ce:GetCostAndUsage for the calibration step The scan is read-only: Describe, List and Get calls, across every region the account has enabled. uv run zombiescan scan --all-regions --limit 8 Scanning as arn:aws:iam::<account :root 17 region s , 30 check s — read-only zombiescan — 120 findings across 17 regions Check Found Monthly ecr-stale-images 33 $6.40 unused-route53-zone 1 $0.50 empty-vpc 1 $0.00 log-group-no-retention 67 $0.00 unused-security-group 18 $0.00 Estimated waste: $6.90/month $82.80/year One hundred and twenty findings, thirty-one of them priced. That JSON document is what everything below reads. MCP over stdio is line-delimited JSON-RPC 2.0. A server answers initialize , tools/list and tools/call , and that is enough for a client to drive it. printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \ | uv run zombiescan-mcp { "protocolVersion": "2025-06-18", "capabilities": {"tools": {"listChanged": false}}, "serverInfo": {"name": "zombiescan", "version": "0.1.0"}, "instructions": "zombiescan finds AWS resources nobody is using and prices them. Every tool is read-only; nothing here deletes anything. Run scan account once, then ask estimate savings for any total, count or breakdown of the report it writes -- do not add up findings yourself." } The instructions field is served to the client on connect and carries the operating rule for the whole server. php tools/list - 'scan account', 'estimate savings', 'explain finding', 'list checks', 'plan cleanup' Five tools, about a hundred lines of framing, and no MCP SDK in the dependency list. A cost scanner's install has one job, and a second package to keep current is a second thing to break. 🔎 Tip: answer initialize with the client's own protocolVersion when you recognise it. A client that asks for a version it gets back proceeds; one that gets a different string negotiates again. estimate savings takes a report path and a filter, and answers with the arithmetic already done. { "matched": { "count": 120, "monthly cost": 6.9, "annual cost": 82.8, "free count": 89, "approximate count": 100, "costliest": { "check": "ecr-stale-images", "resource id": "ai-course-creator-app", "region": "us-east-1", "monthly cost": 0.52 } }, "by check": {"check": "ecr-stale-images", "count": 33, "monthly cost": 6.4}, {"check": "unused-route53-zone", "count": 1, "monthly cost": 0.5} } Every how-much, how-many and which-is-biggest question is answered from that one call. The costliest row is picked in code, the per-check and per-region sections are grouped in code, and the model quotes what came back. scan account follows the same rule from the other direction: it returns the totals, the breakdowns and the costliest few findings inline, and leaves all hundred and twenty rows in the report file. A busy account's rows would bury the total in the context window. A filter naming a check the report does not contain returns a precise zero with a citation, which reads as good news. estimate savings report path=..., checks= "unattached-ebs-volumes" { "filter applied": { "checks": "unattached-ebs-volumes" , "findings in report": 120, "findings matched": 0, "no such checks in report": "unattached-ebs-volumes" }, "matched": {"count": 0, "monthly cost": 0}, "not matched": {"count": 120, "monthly cost": 6.9} } The check is called unattached-ebs , so that filter matched nothing. no such checks in report says so in the same response, and not matched shows what the filter excluded. 🔎 Tip: check the predicate a model sent, not only the number it quoted. A wrong filter returns an exact figure with a source attached, which is harder to catch than a miscount. Scanning and cleaning are separate commands in this tool, and the MCP server exposes only the first. plan cleanup builds the same plan the clean command shows on a dry run: the API calls in order, the backup step before the destruction where AWS allows one, and an irreversible flag on every step with no recovery window. It stops there. Applying a plan stays zombiescan clean --apply at a terminal, where the per-resource prompt lives. Convention is weak, so the suite holds the boundary: python def test the server cannot apply a cleanup : source = pathlib.Path mcp server. file .read text assert "apply outcome" not in source assert set re.findall r"\bclean\. \w+ ", source == {"plan for", "UNSUPPORTED"} clean.plan for yields Step objects. clean.apply outcome is the one function that sends a step to AWS, and a tool that reaches it fails the suite instead of shipping. An end-to-end test runs both front doors over one account and compares them: scan account writes the report, estimate savings reads it back, and the totals must match. Two summation orders over the same one hundred and twenty findings: | Order | Monthly | |---|---| | Each finding rounded to the cent, then added | $6.90 | | Exact costs added, then rounded once | $6.92 | The report published every finding rounded to the cent and computed its headline from the unrounded values, so the document disagreed with its own rows by two cents. An agent reading the published rows can only reach the first figure. The rule that follows: a report's total is the sum of the rows it prints. ScanResult.total monthly cost rounds each finding before adding, with the same round that publishes it, and the per-check sections in the JSON, the terminal table and the HTML report do the same. result.findings = finding "half-cent", f"r-{index}", 0.125 for index in range 4 assert result.total monthly cost == 0.48 assert round sum f.monthly cost for f in result.findings , 2 == 0.50 Arithmetic on four findings priced at one half-cent: at $0.125 each they publish as $0.12 and total $0.48, where adding first and rounding once gives $0.50. The truer figure loses, because a total nobody can reproduce from the rows in front of them is worth less than one that is two cents off. Thirty-three stale container repositories carry the whole dollar total. Cost Explorer knows what they charged. aws ce get-cost-and-usage --granularity MONTHLY --metrics UnblendedCost UsageQuantity \ --group-by Type=DIMENSION,Key=USAGE TYPE \ --filter '{"And": {"Dimensions":{"Key":"RECORD TYPE","Values": "Usage" }}, {"Dimensions":{"Key":"SERVICE","Values": "Amazon EC2 Container Registry ECR " }} }' | Figure | Value | |---|---| | Billed ECR storage, 1–21 September, 20 days | 19.96 GB-Month | | Projected over 30 days | 29.94 GB-Month | | At $0.10 per GB-month | $2.99/month | | ecr-stale-images estimate, 33 repositories | $6.40/month | | Implied storage at the same rate | 64.0 GB | | Ratio | 2.1x | ECR bills unique layers once. The check sums each image's full size, so thirty-three repositories built from the same base layer are counted thirty-three times over. Every one of those findings carries approximate cost: true and an approximate reason of shared-layers , and explain finding returns the reason with the finding. An upper bound stated as an upper bound is useful. The calibration puts a number on it for this account. The plugin is the server plus two slash commands and a skill, installed from the same repository. /plugin marketplace add xbill9/zombiescan /plugin install zombiescan@zombiescan .mcp.json at the plugin root starts the server: { "mcpServers": { "zombiescan": { "command": "uv", "args": "run", "--quiet", "--project", "${CLAUDE PLUGIN ROOT}/..", "zombiescan-mcp" } } } ${CLAUDE PLUGIN ROOT} resolves to the installed plugin directory, so the same file works for a local checkout and for an install from GitHub. The skill carries the rules a client cannot infer from the schemas: scan once and keep the report path, read filter applied before quoting a zero, treat complete: false as an incomplete scan instead of an all-clear, and hand the operator the clean --apply command instead of running it. | | Terminal | MCP server | |---|---|---| | Entry point | zombiescan scan | scan account | | Output | rich table, JSON, HTML, cleanup script | JSON per tool call | | Findings shown | 25 by default, --limit 0 for all | costliest 10, full set in the report file | | Totals | printed | returned computed, with breakdowns | | Filtering | --check , --region , --min-cost | one filter argument, echoed back | | Cleanup | dry run, then --apply | plan only | | Dependencies | click, rich, boto3 | the same, plus nothing | 🥇 The terminal for the first look at an account. The table ranks and groups in one screen, and the HTML report goes in a ticket. 🥈 The MCP server for the follow-up questions. "Which region holds most of it", "what would removing the ECR repositories save", "why is that zone waste" are three tool calls against one report, with no second scan and no second set of numbers. Both read the same engine, so a disagreement between them is a defect in one of the two. The offline suite drives every check against recorded AWS API responses, so it needs no credentials. uv run pytest -q 343 passed, 3 deselected in 0.39s The three deselected are the live tests, which need a real account: ZOMBIESCAN LIVE=1 uv run pytest -m live 3 passed, 343 deselected in 25.58s The third of those is the one that compares the two front doors. The goal of this article was to give a local AWS cost scanner an agent front door without giving up the numbers. The key to the solution was making every tool return figures the engine computed, and holding both front doors to one total in a live test. The results were: estimate savings answers totals, counts, extremes and three breakdowns from one call clean --apply stays a terminal command One AWS account, 17 enabled regions, scanned on 2026-09-21 with a price table generated the same day. Prices are on-demand USD list prices from the AWS Price List API; they ignore private pricing, savings plans and credits, so they will not match an invoice to the cent. The ECR comparison projects 20 days of billed usage to 30 and compares it against a single scan taken inside that window. The model-arithmetic figures quoted in the opening were measured on 2026-09-15 with eleven ids and one API call per run, twenty runs per cell. The strategy for using MCP for AWS cost reporting was validated with an incremental step by step approach.