Why I Built cost-guard-mcp: Pre-Flight Cost Guardrails for AI Agents Talking to Data Warehouses
Cost‑Guard‑MCP is a lightweight Python server that sits between AI agents and data warehouses, offering cost estimation, bounded execution, and strict security. It supports BigQuery and Snowflake, providing precise, upper‑bound, or heuristic estimates and refusing unsafe queries. The project emphas…
When an AI agent is handed a warehouse connection, it can quickly craft a SQL query that scans an entire multi‑terabyte table. If the agent forgets a partition filter or runs a SELECT * against a large table, the query can silently generate a bill in the hundreds of dollars and flood the agent’s context window with millions of rows. No malicious intent is required—just the agent’s normal behavior of writing plausible SQL and executing it.
Why the Gap Exists
Traditional DBAs pause to eyeball a query, run EXPLAIN, and estimate cost before execution. An AI agent, however, receives a generic “run this SQL” tool and has no instinct to check the query’s impact. Most warehouse management platforms, including BigQuery and Snowflake, do not expose a pre‑execution cost or data‑volume estimate to an external tool. Cost‑Guard‑MCP fills this void by acting as a Model Context Protocol (MCP) server that fronts the warehouse APIs.
The server offers three key operations:
describe_engine_capabilities(engine)– discovers what an engine can report.estimate_query_cost(engine, sql, warehouse)– returns a cost and byte estimate before any execution.run_query_bounded(engine, sql, max_bytes_billed, max_rows, max_estimated_cost_usd)– runs the query while enforcing the supplied limits.
Three Accuracy Tiers
Cost‑Guard‑MCP never returns a bare number. Every CostEstimate includes an accuracy_tier field, enforced by a Pydantic model with no default. The three tiers are:
- PRECISE – used by BigQuery’s dry‑run API, which submits the query to the planner, returns the exact
total_bytes_processed, and guarantees the figure matches a real execution. - UPPER_BOUND – used by Snowflake’s
EXPLAIN USING JSON. Snowflake’s plan estimates the bytes that *might* be scanned; runtime optimizations can reduce this number, so the estimate is treated as an upper bound. - HEURISTIC – reserved for Databricks. No dry‑run or explain API is available, so the estimate would be a guess. The project deliberately leaves this tier unimplemented to avoid presenting a false sense of precision.
BigQuery’s dry‑run response also includes an accuracy field. Cost‑Guard‑MCP maps values like LOWER_BOUND or unknown strings to the UPPER_BOUND tier, ensuring conservative reporting when the planner’s confidence is low.
Fail‑Closed, Least‑Privilege Design
Safety is baked into every operation. For example, run_query_bounded refuses to execute a query if the caller supplies a max_estimated_cost_usd but the estimate returned estimated_cost_usd=None—a situation that occurs with capacity‑billed BigQuery projects where no dollar‑per‑byte rate exists. The tool responds with a refused status and a clear reason instead of silently ignoring the cap.
Snowflake integration requires an explicit SNOWFLAKE_ROLE environment variable; missing it raises a ConfigError to prevent accidental use of the default ACCOUNTADMIN role. All interactions with Snowflake or BigQuery clients are wrapped in a sanitize_exceptions decorator that redacts passwords, keys, tokens, and URLs from exception messages, guarding against credential leakage.
Two security fixes were applied on the day the vulnerable code shipped: validation of the Snowflake warehouse name before interpolating it into a USE WAREHOUSE statement, and validation of the GCP project ID before embedding it in an API filter. Both used regex allowlists and raised ValueError on failure, turning potential injection vectors into hard failures.
Rapid Development and Hardening
The entire project—15 Python files, 715 lines—was built and shipped within eighteen hours. Version 0.1.0 launched on 2026‑09‑12, and a hardened version 0.1.1 followed the next day with full CI protection: PyPI Trusted Publishing, CodeQL, OpenSSF Scorecard, secret scanning, Dependabot, and branch protection. Unit tests cover 60 cases, and integration tests run against live BigQuery and Snowflake credentials on a weekly schedule.
Cost‑Guard‑MCP also implements a clever row‑cap technique: it wraps the user’s SQL in SELECT * FROM () AS cost_guard_row_cap LIMIT max_rows + 1. Fetching one extra row allows the tool to detect whether the result set was truncated, ensuring the query remains bounded without affecting performance.
What’s Next
Future work includes adding support for Databricks with a true heuristic estimation layer, expanding the set of supported engines, and refining the accuracy tier mapping for emerging warehouse features. The project’s architecture—MCP server, strict type contracts, and fail‑closed execution—provides a solid foundation for secure AI‑driven data access.
Why it matters
By giving AI agents a transparent cost estimate and enforcing execution limits, Cost‑Guard‑MCP prevents accidental runaway queries that could bill users hundreds of dollars and expose sensitive data, safeguarding both finances and privacy.
Key points
- AI agents can generate costly queries without human oversight
- Cost‑Guard‑MCP offers precise, upper‑bound, and heuristic cost estimates
- The tool refuses unsafe queries instead of silently executing them
- Security hardening is built into the project from day one
- Future plans include Databricks support and expanded engine coverage
Frequently asked questions
What is an MCP server?
MCP stands for Model Context Protocol, a standard for communicating between AI models and external tools. Cost‑Guard‑MCP implements this protocol to provide cost estimates and bounded query execution.
How does Cost‑Guard‑MCP handle Snowflake?
It uses Snowflake’s <code>EXPLAIN USING JSON</code> to estimate bytes, treats the result as an upper bound, and requires an explicit role via environment variable for security.
Can I use it with any SQL engine?
Currently it supports BigQuery and Snowflake. Databricks is planned but not yet implemented due to the lack of a reliable estimation API.
