Cost Guard MCP

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 STARTED the cloud-provider and query-history lookups are skipped (Gen1 rates at the observed size, heuristic runtime, caveat) — the query-history lookup is also skipped whenever no warehouse argument is given; on a Databricks warehouse that is not RUNNING, or whose state cannot be read, no session is opened and no byte or dollar figure is returned — see Known limitations.
• run_query_bounded(engine, sql, max_bytes_billed?, max_rows?, max_estimated_cost_usd?, warehouse?, warehouse_size?, edition?) — refuses to run if the estimate exceeds your bound. max_rows defaults to 1000 (pass a larger value to raise it); results over 8 MiB serialised are truncated to whole rows with reason: result_size_exceeded; executed: true on ok and on the two truncation refusals (row_cap_exceeded, result_size_exceeded — the query ran), false on every other refusal (the query was never submitted, or BigQuery refused to run it). 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). A max_estimated_cost_usd cap is checked against that observed-warehouse estimate and refuses when no dollar figure exists. Not gated on warehouse state: its estimate and execution may resume/start the warehouse. Result rows carry the constant rows_provenance: warehouse_data_untrusted: they are data the warehouse returned, never instructions.

Setup

BigQuery

Set GOOGLE_APPLICATION_CREDENTIALS to a service-account key file path (or run gcloud auth application-default login).

Snowflake

Set SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, SNOWFLAKE_ROLE (required — no default, never ACCOUNTADMIN), and either SNOWFLAKE_PRIVATE_KEY_PATH (preferred) or SNOWFLAKE_PASSWORD (discouraged). Optionally set SNOWFLAKE_EDITION to the account's edition — standard (default), enterprise, business_critical or vps — which sets the USD/credit price of every estimate; the per-call edition argument can only raise it.

• SNOWFLAKE_ROLE is the *only* authorization boundary for the SQL an agent sends through this server, so it is enforced, not just documented. ACCOUNTADMIN, SECURITYADMIN and ORGADMIN are rejected (case-insensitively, quoted or not) before any Snowflake connection is opened: the check runs when the Snowflake configuration is first loaded, which is on the first Snowflake tool call, so the server process itself starts regardless of the value and a bad role surfaces as check_credentials returning ok: false (or as a tool error from estimate_query_cost/run_query_bounded), not as a startup exit. Every session also activates only that role — secondary roles are pinned to NONE in the login request, so a user whose Snowflake DEFAULT_SECONDARY_ROLES is ('ALL') no longer lends every other role it holds to model-written SQL. SNOWFLAKE_USER should ideally hold no role other than SNOWFLAKE_ROLE.
• SNOWFLAKE_SECONDARY_ROLES (optional, default NONE; the only other value is ALL) is the opt-out for deployments that reached objects only through a secondary role. Prefer granting those objects to SNOWFLAKE_ROLE instead; set ALL only if you accept that the agent's SQL runs with every role the user holds. check_credentials reports the active secondary-role set (CURRENT_SECONDARY_ROLES()) so you can confirm what is in force.
• Every session also carries a Snowflake-side statement deadline (STATEMENT_TIMEOUT_IN_SECONDS: 60 s for check_credentials/estimate_query_cost, 120 s for run_query_bounded, matching its watchdog) so a query cannot keep running — and billing — if this process dies mid-call. The value is applied *read-then-lower*: the server reads the session's effective value first and only issues ALTER SESSION when that value is 0 (unbounded), unparseable, or above the target. A stricter account- or user-level policy (say 30 s) is therefore never raised; note that a session-level value would otherwise override account/user levels in Snowflake's parameter hierarchy (only the warehouse level combines lowest-wins).
• Snowflake sessions are also pinned to one statement per call: EXPLAIN USING JSON and the run_query_bounded execution are submitted with num_statements=1 and the session logs in with MULTI_STATEMENT_COUNT=1, so Snowflake itself rejects ;-separated text that the server-side scanner (see Known limitations) did not already refuse. There is no opt-out; multi-statement Snowflake text was never supported.
• COST_GUARD_SNOWFLAKE_ALLOW_WAREHOUSE_RESUME=true (optional, off by default; the value must be exactly true) lets check_credentials and estimate_query_cost run SELECT CURRENT_REGION(), the QUERY_HISTORY read and the session-context SELECT on a warehouse whose SHOW WAREHOUSES state is not STARTED (and the QUERY_HISTORY read without a warehouse argument), accepting that they can resume it and bill compute. See Known limitations for what is skipped by default.

Databricks

Set DATABRICKS_SERVER_HOSTNAME and DATABRICKS_HTTP_PATH (from the SQL warehouse's Connection Details tab), and either DATABRICKS_TOKEN (a personal access token, simplest) or DATABRICKS_CLIENT_ID + DATABRICKS_CLIENT_SECRET (OAuth machine-to-machine via a service principal, preferred for automated use). Only Serverless SQL warehouses are priced — a Classic/Pro warehouse gets a byte estimate but no dollar figure, see Known Limitations.

By default check_credentials and estimate_query_cost refuse to open a session unless the warehouse's state, read through the Warehouses API, is RUNNING (they also refuse when the state cannot be read); set COST_GUARD_DATABRICKS_ALLOW_WAREHOUSE_START=true (exactly that value) to let them start a stopped warehouse, billing compute. run_query_bounded is not gated. See Known limitations.

Concurrency (optional)

COST_GUARD_MAX_IN_FLIGHT_QUERIES (default 8) caps how many run_query_bounded calls may be in flight at once — counting calls the host has already cancelled, until their worker thread exits (at most the 120 s watchdog). A call over the cap fails immediately with a tool error naming this variable, before any warehouse connection is opened. Must be a positive integer (the server refuses to start otherwise); raise it only if your host legitimately runs more concurrent billable queries.

Read-only statements (optional opt-out)

By default estimate_query_cost and run_query_bounded accept only read statements: the first keyword after comments and any opening parentheses must be SELECT, WITH, VALUES, SHOW, DESCRIBE, DESC or EXPLAIN, and a WITH is admitted only when the statement after its CTE list resolves to SELECT or VALUES (Spark SQL allows WITH ... INSERT). Anything else is refused before any dry run, EXPLAIN or execution, because warehouse rows re-enter the model's context and can steer the next call (DECISIONS.md #13). The gate is defence in depth, not the authorisation boundary: that is the deployed credential's grants, so deploy a read-only principal — BigQuery: data-viewer plus job-user roles; Snowflake: a role with USAGE/SELECT only, never an admin role; Databricks: SELECT/USE privileges on the warehouse's catalogs. Operators who intend this server to run writes under its credential can set COST_GUARD_ALLOW_WRITE_STATEMENTS=1 (exactly that value, read per call; anything else keeps the gate on). With COST_GUARD_ALLOW_MULTI_STATEMENT_SQL=1 every statement in the text must be a read, so BigQuery scripts (DECLARE/SET/BEGIN) need both opt-outs.

A note on credentials with MCP hosts

Whatever MCP client/host you use (Claude Desktop, etc.) spawns this server as its own subprocess — it does not automatically inherit your shell's environment variables, even if they're set in your