cost-guard-mcp

Pre-flight query cost & result-size guardrails for AI agents, across BigQuery, Snowflake, and Databricks — before the query ever runs.

Why

An AI agent using a warehouse MCP can silently trigger a full-table scan that costs hundreds of dollars, or return millions of rows that flood its own context window. No existing warehouse MCP tells the agent "how much will this cost" or "how much data will this return" before running the query.

What makes this different

• Every cost estimate discloses its accuracy tier — PRECISE (BigQuery dryRun), UPPER_BOUND (Snowflake EXPLAIN), or HEURISTIC (Databricks EXPLAIN COST) — so your agent never over-trusts a heuristic number.
• Per-call bounds — run_query_bounded takes max_bytes_billed / max_rows / max_estimated_cost_usd on each call; no shared session state required. max_rows defaults to 1000 and the serialised result is capped at 8 MiB; executed on every result says whether the query ran.
• Zero infrastructure — a single local stdio process. No database, no gateway, no Docker Compose.

Tools

• check_credentials(engine, warehouse?) — verifies credentials/connectivity without running a real query or a dry run; call this first after configuring a new engine. Supports BigQuery, Snowflake, and Databricks. What runs: BigQuery makes one metadata call; Snowflake logs in, runs USE WAREHOUSE when a warehouse is given (SELECT CURRENT_WAREHOUSE() when none is), reads the pinned warehouse's SHOW WAREHOUSES row, and runs one session-context statement only when that row says STARTED — otherwise ok: true with a detail built from the row (the statement could resume a suspended warehouse); Databricks reads the configured SQL warehouse through the Warehouses API (a control-plane GET) and opens a session (SELECT current_user()) only when it is RUNNING — otherwise ok: false with no session (the session could start a stopped warehouse). An unreadable state counts as not running on both. Opt in with COST_GUARD_SNOWFLAKE_ALLOW_WAREHOUSE_RESUME=true / COST_GUARD_DATABRICKS_ALLOW_WAREHOUSE_START=true — see Known limitations.
• describe_engine_capabilities(engine) — what's exact vs. approximate for this engine.
• estimate_query_cost(engine, sql, warehouse?, warehouse_size?, edition?) — pre-flight cost estimate, tagged with its accuracy tier. Supports BigQuery, Snowflake, and Databricks. Accepts exactly one SQL statement per call, and only read statements by default — first keyword SELECT, WITH, VALUES, SHOW, DESCRIBE, DESC or EXPLAIN (see Known limitations). warehouse_size (Snowflake/Databricks) and edition (Snowflake) can only raise the estimate — the dollar figure is priced at the warehouse the query is pinned to, as the server observes it (the SHOW WAREHOUSES size/type/generation, or the Databricks Warehouses API), and at the operator-configured SNOWFLAKE_EDITION, whichever is higher. Warehouse types without a modelled rate (Snowpark-optimized, Databricks Classic/Pro) get a byte estimate but no dollar figure. On a Snowflake warehouse that is not `STA

... View full README on GitHub