Lagaam MCP server

Stop your agent from running the $500 query. Lagaam is a governed MCP server that sits between your AI agents and your lakehouse (Trino and Apache Pinot). Every query is schema-grounded, priced before it runs, checked against a budget, and audited — and every rejection tells the agent exactly how to fix its SQL.

Real session, real Trino, nothing mocked — reproduce it with uv run --project server python examples/demo.py.

Real session, real Pinot 1.5.1 realtime table, nothing mocked — reproduce it with uv run --project server python examples/demopinot.py.*

The problem

Agents write syntactically-valid, catastrophic SQL. A missing partition filter turns into a full scan over a petabyte table; one retry loop burns a day's warehouse budget in minutes; a SELECT * drags 40 columns into a context window that needed 2. The usual fix is to not give agents database access at all.

Lagaam gives them access with reins on:

engine's own plan before execution — EXPLAIN (TYPE IO) for the bytes it would scan, EXPLAIN (TYPE LOGICAL) for the widest row count any operator would build (the number a cross join blows and a LIMIT cannot hide). Over budget → blocked, with the number and the fix.

• Cost is a quotation, not a bill. Every query is priced from the

the estimate, a passthrough the planner can't see — the gate fails safe instead of hoping.

• Un-estimable means no. No table statistics, a self-join that breaks

multi-statement injection, no SELECT *, no table-function passthrough, and a LIMIT is injected when missing. Validated SQL is re-rendered, so what runs is exactly what was checked.

• Read-only, enforced in the AST. Single SELECT only. No DDL/DML, no

exact names, types, and row estimates — scoped to the agent's table grant, so the agent never learns names it isn't allowed to touch.

• Agents ground themselves. listcatalogs and describetable return

pages, all-NULL columns — the agent gets a warning with a next action, not a silently misleading answer.

• Results are verified before they're trusted. Zero rows, truncated

allowed or denied, and why.

• Every call is audited. One JSONL line per tool call: who, what,

Catch rate

11 queries an LLM agent plausibly writes — full scans, SELECT , DDL, injection attempts, oversized joins, out-of-grant reads. A raw MCP wrapper submits all of them to the engine. Lagaam stops 11/11 before execution while the well-scoped control query runs untouched. Reproduce: benchmarks/catchrate.py → results.

Quickstart

Against the Trino you already have (TRINOPORT / TRINOUSER if yours aren't 8080 / lagaam):

TRINO_HOST=trino.internal LAGAAM_ALLOWED_TABLES=hive.sales.orders uvx lagaam   # MCP server on stdio

Or try it on a demo warehouse:

git clone https://github.com/lagaam-ai/lagaam && cd lagaam
docker compose -f examples/docker-compose.yml --profile trino up -d   # demo warehouse
cd server && uv sync
LAGAAM_ALLOWED_TABLES=tpch.tiny.orders,tpch.tiny.lineitem \
  uv run python -m lagaam                                             # MCP server on stdio

For Pinot, --profile pinot brings up the batch quickstart and --profile pinot-realtime up -d brings up a Kafka-fed streaming one — run examples/pinot-realtime/bootstrap.sh after it to create the topics, tables and feed. Then start the server with LAGAAM_ENGINE=pinot.

Wire it into any MCP client (Claude Code, Claude Desktop, or your own agent):

Shortened. The full README is on GitHub.