Anumana
Anumana is a read-only MCP server that pre-checks AI-written SQL and vector queries for cost and risk before they run — using EXPLAIN, never executing anything.
Preflight SQL queries (
preflight_query): get risk tier (cheap/moderate/expensive/dangerous), rows scanned vs returned, scan strategy, and overhead flags (missing index, SELECT *, no LIMIT, N+1) without running the query.Preflight vector/RAG searches (
preflight_vector_search): catch pgvector traps — brute-force scan with no HNSW/IVFFlat index, top_k too large, unbounded search, metadata-filter/ANN recall loss.Rewrite for cost (
rewrite_query): get a verified equivalent rewrite with before/after planner cost and selectivity-gated index suggestions (HNSW for vector targets).Explain query behavior (
explain_query_working): plain-English logical gather order plus the actual physical plan, step by step.Grade a candidate query (
suggest_query): returnsnext_actionof accept or refine with high-severity flags and a verified cheaper rewrite.Read the real schema (
describe_schema_tool): tables, columns, indexes, and row counts via read-only catalog access — never data rows.Inspect configuration:
list_targetsshows configured databases (name, engine, diagnosability);list_policiesshows enforcement rules that can block or warn on queries.Work offline / zero-trust (
preflight_schema_only): static heuristic analysis against pasted CREATE TABLE DDL with no DB connection.Multi-DB support: pass
target=<name>to route any tool to a specific database; 12 engines across 7 paradigms (Postgres and SQLite live-tested).Never executes SQL: EXPLAIN only, read-only role recommended, no secrets or connection strings returned.
Offline-verified adapter for ClickHouse: preflight analysis of generated ClickHouse queries to catch expensive scans and costly patterns before they run, currently shipped as an untested adapter.
Offline-verified adapter for MongoDB: gives preflight foresight on generated Mongo queries, flagging costly scan patterns and suggesting cheaper equivalents, currently shipped as an untested adapter.
Offline-verified adapter for MySQL: performs query cost and risk preflight analysis (risk tier, scan strategy, rows scanned vs returned, rewrite suggestions) over MySQL queries, currently without live connection support.
Live-tested engine integration: analyzes SQL queries against a real Postgres schema using EXPLAIN (never EXPLAIN ANALYZE) without executing them, reporting risk tier, rows scanned vs returned, scan strategy, overhead flags, and verified equivalent rewrites with before/after planner cost plus selectivity-gated index suggestions. Connection is via a read-only DSN (ANUMANA_DSN).
Offline-verified adapter for Snowflake: analyzes generated Snowflake SQL for cost and risk before execution, reporting scan strategy, row counts, and rewrite deltas, currently shipped as an untested adapter.
Live-tested engine integration: runs the same preflight cost-and-risk analysis on SQLite queries, explaining the physical plan step by step and flagging unindexed scans and expensive operations without running the query.
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., "@Anumana preflight this query: SELECT * FROM orders WHERE user_id = 42"
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.
Anumana
Know what your query will cost — before you run it. Inference-grade foresight for every query your AI writes.
Anumana is an MCP server that catches the
costly query your AI coding agent just wrote — before it runs or reaches a PR.
It rides inside Claude, Cursor, Windsurf, Codex, Kiro, or any MCP-compatible
agent, reads your real schema via EXPLAIN (never EXPLAIN ANALYZE), and
tells you — in plain English — how the query behaves and whether it'll hurt.
Its scope is the queries AI agents actually generate: text-to-SQL today, and RAG / vector search (pgvector) alongside it — because an agent writing a similarity search has no idea it just triggered a brute-force scan over every embedding. Anumana is the feedback loop the agent is missing.
It is not another NL→SQL tool and not a DB-health dashboard. It does one job: stop AI-written database code from silently rotting production.
What it does (the features)
Tool | What it answers |
| "Will this SQL query be costly?" — risk tier (cheap/moderate/expensive/dangerous), rows scanned vs returned, scan strategy, and overhead flags. Without running it. |
| "Will this RAG similarity search be costly?" — catches the vector traps a plain SQL check misses: brute-force scan with no HNSW/IVFFlat index, |
| "Make it cheaper." — a verified equivalent rewrite with before/after planner cost, plus index suggestions gated on selectivity (won't tell you to index a column when the filter matches most of the table). |
| "How does this run?" — two layers: the logical gather order (FROM → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT) and the actual physical plan for your schema, step by step. |
| "I haven't given you DB creds yet." — static analysis against pasted |
Engines (12, across 7 paradigms): Postgres and SQLite are live-tested; MySQL, pgvector, MongoDB, DynamoDB, FalkorDB, Cassandra, Redshift, BigQuery, Snowflake and ClickHouse ship as offline-verified, untested adapters that are promoted to live one at a time. Full matrix + cost signals in SUPPORTED_ENGINES.md. The adapter interface is in DESIGN.md.
The one honest rule
Postgres planner cost is unitless — not milliseconds (docs).
Anumana never fakes a ~3.2s number. It reports rows scanned, scan strategy, a
risk tier, overhead flags, and the cost-delta of a rewrite — all defensible,
nothing invented. Every estimate carries an accuracy tier (UPPER_BOUND live,
HEURISTIC schema-only).
Related MCP server: mcp-database-tools
Install
pip install anumana-mcp # once published to PyPI
# or from source:
pip install -e .Then point your agent at it. The user installs it; the agent discovers the
tools automatically on connect via the MCP tools/list handshake — there is
no store to publish into.
Claude Desktop / Cursor / Windsurf / Kiro — mcpServers config block
{
"mcpServers": {
"anumana": {
"command": "uvx",
"args": ["anumana-mcp"],
"env": { "ANUMANA_DSN": "postgres://readonly@localhost:5432/mydb" }
}
}
}Use a read-only Postgres role. Anumana only ever EXPLAINs, but read-only is
defence in depth. Omit ANUMANA_DSN to run in schema-only mode (DDL in, no DB).
Try it with no database (30 seconds)
python3 src/demo.py # runs the engine on a canned plan, zero depsTest against a real Postgres
# a throwaway table, then:
ANUMANA_DSN=postgres://localhost/mydb anumana-mcpSee src/live_test.py for a psql-backed harness that proves the real
cost-delta and the selectivity gate on live data.
What's deliberately NOT here
No run_query (we never execute your SQL), no NL→SQL (the agent already does
that), no DB-health reports, no dollar-billing. Staying narrow is the strategy.
License
MIT — see LICENSE.
Community & contact
Contributions welcome — see CONTRIBUTING.md and the Code of Conduct. Adding a database engine is the highest- leverage contribution; the adapter contract is small (SUPPORTED_ENGINES.md).
Bugs / ideas: open a GitHub issue.
Security: see SECURITY.md — report privately.
Maintainer: nomore.report@gmail.com
Available Tools
9 toolsdescribe_schema_toolA
Read a database's REAL schema — tables/collections, columns/fields,
INDEXES, and row counts — so you can write a grounded, cost-aware query
BEFORE guessing. Call this FIRST when a user asks for data and you don't
already know the schema; it tells you which columns are indexed so your
query hits an index, not a full scan. READ-ONLY catalog access — never
reads data rows. If the schema can't be read it returns need_from_user
naming what to ask the user for. Pass target= in a multi-DB setup;
combine with list_targets to find which DB has the data.
Inputs: target. Returns: result
explain_query_workingA
Explain in plain English HOW a query behaves — two layers: (1) the logical gather order (FROM -> WHERE -> GROUP BY -> HAVING -> SELECT -> ORDER BY -> LIMIT), why 'LIMIT 10' can still be slow; and (2) the actual physical plan the engine chose for THIS query, bottom-up. Call when a user asks why a query is slow or how it runs. Teaching tool. Pass target= in a multi-DB setup.
Inputs: sql (required), target. Returns: result
list_policiesA
List the operator's standing enforcement policies — the rules that can BLOCK or WARN on a query regardless of what you intend. Each has a name, scope (which target/engine), condition (risk tier and/or flag), and action (block/warn/allow). preflight_query and suggest_query already apply these and attach the verdict; call this to explain to a user WHY a query was blocked. No policies configured means open by default (nothing blocked).
Inputs: no named parameters. Returns: result
list_targetsA
List the databases Anumana is configured to analyse — each with its name, engine, and whether it's diagnosable. Call this FIRST in a multi-DB setup to see which target holds the data the user asked for, then pass target= to the other tools. In a single-DB setup you can omit target and the one database is used. Never returns connection strings or secrets.
Inputs: no named parameters. Returns: result
preflight_queryA
Before running ANY SQL query you (the agent) just wrote, check how costly it will be on the real schema — WITHOUT executing it. Returns a risk tier (cheap/moderate/expensive/dangerous), rows scanned vs returned, scan strategy, and overhead flags (missing index, SELECT *, no LIMIT, N+1 / nested-loop blowup). EXPLAIN only — never runs the query. In a multi-DB setup pass target= (see list_targets). For similarity search use preflight_vector_search; with no DB use preflight_schema_only.
Inputs: sql (required), target. Returns: result
preflight_schema_onlyA
Analyse a query against pasted CREATE TABLE DDL with NO database connection — the zero-trust, offline front door. Call when the user gave you their schema (DDL) but not DB credentials. Catches SELECT *, missing LIMIT, un-indexed filter columns, LIKE '%...', functions on filtered columns. HEURISTIC only (no live counts) and says so. No target needed.
Inputs: ddl (required), sql (required). Returns: result
preflight_vector_searchA
Before running a VECTOR SIMILARITY SEARCH (pgvector: ORDER BY embedding <-> $1 LIMIT k, cosine <=>, inner-product <#>), check its cost WITHOUT
running it — for any RAG / semantic-search / nearest-neighbour query you
generate. Catches the vector traps a plain SQL check misses: brute-force
scan with no HNSW/IVFFlat index (FULL_VECTOR_SCAN), top_k too large
(TOP_K_TOO_LARGE), unbounded search (UNBOUNDED_VECTOR_SEARCH), and metadata-
filter/ANN recall loss (VECTOR_FILTER_INTERACTION). EXPLAIN only. Pass
target= in a multi-DB setup; the target should be a pgvector engine.
Inputs: sql (required), target. Returns: result
rewrite_queryA
Rewrite a slow query into a cheaper, equivalent one and PROVE the improvement by EXPLAIN-ing both and comparing planner cost. Call after a preflight flags a query expensive/dangerous. Returns the rewritten query, what changed, before/after cost, and index suggestions — ONLY suggesting a btree index when the filter is selective enough to help (an HNSW index for a vector target). Includes equivalence caveats. Pass target= in a multi-DB setup.
Inputs: sql (required), target. Returns: result
suggest_queryA
Grade a query you (the agent) wrote for a user's data request and get
told whether to RUN it or REFINE it — the check step of generate->check->
refine. Workflow: (1) describe_schema_tool to learn columns + indexes,
(2) write a candidate for the user's intent, (3) call this. Returns
next_action: 'accept' (cheap/moderate — run it) or 'refine' (expensive/
dangerous — here are the high-severity flags + a VERIFIED cheaper rewrite;
fix and call again). You write the SQL; Anumana owns cost truth. Bound your
loop to ~3 rounds. Pass target= in a multi-DB setup.
Inputs: intent (required), candidate_sql (required), target. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The set has a dense cluster around cost-checking a query: preflight_query, suggest_query, and rewrite_query all assess/verify query cost and rewrite behavior, making it non-obvious which to call first (descriptions do disambiguate via the generate->check->refine framing). The preflight_* trio is well-separated by scope (SQL vs vector vs offline DDL), and explain_query_working is distinct as a teaching tool.
Most names follow a verb_noun pattern (list_targets, list_policies, rewrite_query, suggest_query) and the preflight_* prefix is consistent. However, describe_schema_tool adds a redundant '_tool' suffix and explain_query_working ends in '_working', breaking the pattern in two places.
Nine tools is well-scoped for a query cost-analysis/enforcement server, with each tool covering a recognizably distinct surface (targets, policies, three preflight variants, rewrite, explanation, schema, grading). No bloat or thinness.
The domain (analyze/grade/rewrite queries without executing them) is covered end-to-end: discover targets, inspect schema, learn policies, preflight SQL/vector/offline, rewrite, and explain. Minor gaps exist, e.g. no explicit connectivity/health probe or standalone equivalence-verification tool, but core workflows are complete.
Related MCP Connectors
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Review your AI agent's database changes on your schema, with plain-language risk, before they run.
Database guardrails for AI agents: check SQL against your Vericto rules before it runs.
AI agents need permission before production SQL writes. Pilot $100 · Gateway $299. Lint≠authorize.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnforces safety and governance for SQL queries executed by AI agents, providing read-only enforcement, cost estimation, and audit trails.Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI agents to format SQL, explain queries in plain English, analyze schemas, build queries from natural language, and generate migrations, all without requiring a database connection.543 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to pre-flight estimate query costs, enforce hard budgets, reconcile actual billed spend, and suggest cheaper rewrites across BigQuery, Snowflake, and Databricks.MIT
- AlicenseBqualityCmaintenanceEnables AI coding agents to perform deterministic database architecture audits and performance engineering for PostgreSQL and MySQL, covering migration analysis with schema health scoring, ESR-based composite index recommendations, N+1 query detection, EXPLAIN plan diagnosis, transaction and deadlock analysis, partitioning and archival design, and capacity or configuration tuning. It also generates phased Expand & Contract runbooks that turn blocking DDL into zero-downtime production migrations.8MIT