Server data from the Official MCP Registry
Stops an agent's Trino or Pinot query before it runs if it costs too much or reads outside its grant
About
Stops an agent's Trino or Pinot query before it runs if it costs too much or reads outside its grant
Security Report
Valid MCP server (1 strong, 3 medium validity signals). 7 known CVEs in dependencies (1 critical, 1 high severity) Package registry verified. Imported from the Official MCP Registry.
6 files analyzed · 8 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: LAGAAM_ALLOWED_TABLES
Environment variable: LAGAAM_ALLOW_ALL_TABLES
Environment variable: LAGAAM_ENGINE
Environment variable: TRINO_HOST
Environment variable: TRINO_PORT
Environment variable: TRINO_USER
Environment variable: TRINO_PASSWORD
Environment variable: TRINO_JWT
Environment variable: TRINO_HTTP_SCHEME
Environment variable: TRINO_VERIFY
Environment variable: PINOT_CONTROLLER_URL
Environment variable: PINOT_BROKER_URL
Environment variable: PINOT_USER
Environment variable: PINOT_PASSWORD
Environment variable: LAGAAM_AGENT_NAME
Environment variable: LAGAAM_MAX_SCAN_BYTES
Environment variable: LAGAAM_MAX_ROWS
Environment variable: LAGAAM_MAX_INTERMEDIATE_ROWS
Environment variable: LAGAAM_MAX_RETURNED_ROWS
Environment variable: LAGAAM_QUERY_TIMEOUT
Environment variable: LAGAAM_METADATA_TTL
Environment variable: LAGAAM_AUDIT_LOG
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"lagaam": {
"command": "uvx",
"args": [
"lagaam==1.0.0"
],
"env": {
"TRINO_JWT": "your-trino-jwt-here",
"PINOT_USER": "your-pinot-user-here",
"TRINO_HOST": "your-trino-host-here",
"TRINO_PORT": "your-trino-port-here",
"TRINO_USER": "your-trino-user-here",
"TRINO_VERIFY": "your-trino-verify-here",
"LAGAAM_ENGINE": "your-lagaam-engine-here",
"PINOT_PASSWORD": "your-pinot-password-here",
"TRINO_PASSWORD": "your-trino-password-here",
"LAGAAM_MAX_ROWS": "your-lagaam-max-rows-here",
"LAGAAM_AUDIT_LOG": "your-lagaam-audit-log-here",
"PINOT_BROKER_URL": "your-pinot-broker-url-here",
"LAGAAM_AGENT_NAME": "your-lagaam-agent-name-here",
"TRINO_HTTP_SCHEME": "your-trino-http-scheme-here",
"LAGAAM_METADATA_TTL": "your-lagaam-metadata-ttl-here",
"LAGAAM_QUERY_TIMEOUT": "your-lagaam-query-timeout-here",
"PINOT_CONTROLLER_URL": "your-pinot-controller-url-here",
"LAGAAM_ALLOWED_TABLES": "your-lagaam-allowed-tables-here",
"LAGAAM_MAX_SCAN_BYTES": "your-lagaam-max-scan-bytes-here",
"LAGAAM_ALLOW_ALL_TABLES": "your-lagaam-allow-all-tables-here",
"LAGAAM_MAX_RETURNED_ROWS": "your-lagaam-max-returned-rows-here",
"LAGAAM_MAX_INTERMEDIATE_ROWS": "your-lagaam-max-intermediate-rows-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.

One agent query shouldn't stall everyone's Trino. On a shared cluster, a missing partition filter or an accidental cross join doesn't cost you a bill — it costs everyone else their queries. Lagaam is an MCP server that sits between your AI agents and your lakehouse (Trino and Apache Pinot): every query is schema-grounded, priced from the engine's own plan before it runs, checked against a budget, and audited — and the bad one is refused before it runs, with a fix the agent can act on.

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/demo_pinot.py.
The problem
Agents write syntactically-valid, catastrophic SQL, and on a shared cluster
the damage isn't theirs alone. A missing partition filter turns into a full
scan that ties up every worker; an accidental cross join fills worker memory
while everyone else's queries wait behind it; a retry loop runs it again. 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:
- Cost is a quotation, not a bill. Every query is priced from the
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 aLIMITcannot hide). Over budget → blocked, with the number and the fix. - Un-estimable means no. No table statistics, a self-join that breaks the estimate, a passthrough the planner can't see — the gate fails safe instead of hoping.
- Read-only, enforced in the AST. Single
SELECTonly. No DDL/DML, no multi-statement injection, noSELECT *, no table-function passthrough, and aLIMITis injected when missing. Validated SQL is re-rendered, so what runs is exactly what was checked. - Agents ground themselves.
list_catalogsanddescribe_tablereturn 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. - Results are verified before they're trusted. Zero rows, truncated pages, all-NULL columns — the agent gets a warning with a next action, not a silently misleading answer.
- Every call is audited. One JSONL line per tool call: who, what, allowed or denied, and why. A query's line puts the quote next to what the engine says it actually read, so you can see how far off the estimate was before you loosen or tighten a budget.
Doesn't Trino already limit this?
It limits a query once it is running. Lagaam refuses it before it starts. Keep both.
| Acts | What the agent sees | Catches a cross join that reads little | |
|---|---|---|---|
query.max-scan-physical-bytes | during execution: terminated once the bytes are scanned | a query failure | no — it counts bytes read, not rows built |
query.max-execution-time | during execution: terminated after the time is spent | a query failure | only after it has held the cluster that long |
Resource groups (hardPhysicalDataScanLimit, softMemoryLimit, …) | on the next query: new queries queue once the group is over its share | its later queries wait | no — the running query continues |
| Lagaam | before execution, from EXPLAIN | a refusal with the number and the fix | yes — it prices the rows the widest step would build |
Measured on Trino 476: SELECT o.orderkey, l.partkey FROM tpch.tiny.orders o CROSS JOIN tpch.tiny.lineitem l LIMIT 10 reads 676,575 bytes by Trino's own
plan — any scan cap above 0.7 MB lets it run — and would build 902,625,000
rows. Lagaam refuses it before it runs: "This query would build 902,625,000
rows at its widest step, over your budget of 50,000,000 … a LIMIT will not
help — join on a column with more distinct values, or filter each side
before the join."
Resource groups stay your backstop for everything that does reach the cluster; Lagaam is the gate in front of it for agent traffic.
What about other database MCP servers?
They're good servers that do a different job: keep the agent read-only and bound what comes back. Lagaam does that too, and also prices the query first.
| Read-only | Row cap | Timeout | Checks the plan before running | |
|---|---|---|---|---|
| tuannvm/mcp-trino | on by default | results truncated while fetching (TRINO_MAX_ROWS) | during execution (TRINO_QUERY_TIMEOUT) | no — explain_query shows the agent a plan; it doesn't gate execute_query |
| startreedata/mcp-pinot | always on, parsed before execution | LIMIT rewritten before execution, paged results | during execution (PINOT_QUERY_TIMEOUT, 60 s) | no |
| bytebase/dbhub | opt-in (readonly): keyword check plus the database's own read-only transaction | opt-in (max_rows), injected as LIMIT/TOP | opt-in (query_timeout), during execution | no — opt-in explain_sql shows a plan; it doesn't gate execute_sql |
| Lagaam | always on, parsed before execution | 1,000 by default; a bigger LIMIT is lowered before it runs | during execution (LAGAAM_QUERY_TIMEOUT, 300 s) | yes — scan bytes and widest-step rows from EXPLAIN; over budget is refused |
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/catch_rate.py →
results.
Quickstart
Against the Trino you already have (TRINO_PORT / TRINO_USER 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):
{
"mcpServers": {
"lagaam": {
"command": "uvx",
"args": ["lagaam"],
"env": {
"TRINO_HOST": "localhost",
"LAGAAM_MAX_SCAN_BYTES": "5368709120",
"LAGAAM_ALLOWED_TABLES": "hive.sales.orders,hive.sales.customers"
}
}
}
}
In Claude Code, install it as a plugin instead:
/plugin marketplace add lagaam-ai/lagaam
/plugin install lagaam@lagaam
It asks for the tables to allow (LAGAAM_ALLOWED_TABLES) and your Trino
host, port and user (localhost / 8080 / lagaam if you leave them).
From a shell, pass them as flags:
claude plugin marketplace add lagaam-ai/lagaam
claude plugin install lagaam@lagaam \
--config allowed_tables=hive.sales.orders --config trino_host=trino.internal
On Pinot, pick engine=pinot and set the controller and broker URLs
(http://localhost:9000 / http://localhost:8000 if you leave them):
claude plugin install lagaam@lagaam --config engine=pinot \
--config allowed_tables=pinot.default.baseballStats \
--config pinot_controller_url=http://pinot.internal:9000 \
--config pinot_broker_url=http://pinot.internal:8099
Other LAGAAM_* settings, the Trino login (TRINO_PASSWORD or TRINO_JWT,
plus TRINO_VERIFY for a private CA), and PINOT_USER / PINOT_PASSWORD for
a Pinot with auth, are read from the environment you start claude in, so a
password never sits in the plugin's config.
The agent gets three tools — list_catalogs, describe_table,
query_data — and cannot reach the engine any other way.
Configuration
| Env var | Meaning | Default |
|---|---|---|
LAGAAM_ALLOWED_TABLES | Comma list of catalog.schema.table grants | required |
LAGAAM_ALLOW_ALL_TABLES | true to run with no grant at all | off |
LAGAAM_AGENT_NAME | Identity stamped on the audit trail | anonymous |
LAGAAM_MAX_SCAN_BYTES | Scan-bytes budget per query, pre-execution | 50 GiB |
LAGAAM_MAX_ROWS | Scanned-row estimate budget per query | ungated |
LAGAAM_MAX_INTERMEDIATE_ROWS | Rows the engine would build at its widest step — not rows returned, so a LIMIT doesn't lower it | 50,000,000 |
LAGAAM_MAX_RETURNED_ROWS | Rows returned to the agent per query — unset, the server applies its own 1000-row cap, and a bigger LIMIT in the query is lowered to it before it runs | 1000 (max 100000) |
LAGAAM_QUERY_TIMEOUT | Wall-clock seconds per query | 300 |
LAGAAM_METADATA_TTL | Metadata cache TTL, seconds | 300 |
LAGAAM_AUDIT_LOG | Audit JSONL file path | stderr |
LAGAAM_ENGINE | pinot to run the native Pinot adapter | trino |
PINOT_CONTROLLER_URL / PINOT_BROKER_URL | Pinot controller and broker | http://localhost:9000 / http://localhost:8000 |
PINOT_USER / PINOT_PASSWORD | Basic-auth login for Pinot | unset (no login) |
TRINO_HOST / TRINO_PORT / TRINO_USER | Trino coordinator | localhost / 8080 / lagaam |
TRINO_PASSWORD | Password for TRINO_USER, for a cluster that wants a login | unset (no login) |
TRINO_JWT | JWT to log in with instead of a password — set one or the other, not both | unset |
TRINO_HTTP_SCHEME | http or https | https once a password or JWT is set, else http |
TRINO_VERIFY | Check the cluster's TLS cert: true, false, or the path of your CA bundle (PEM) for a private CA | true |
A shared Trino with a login works the same way. Set TRINO_PASSWORD (or
TRINO_JWT) and lagaam talks https, since Trino won't take a password over
plain http; set TRINO_PORT to the cluster's https port too (often 443 or
8443). A login the cluster refuses tells the agent so, without the password,
and a password and a JWT both set stop the server at startup rather than
guessing which one you meant. Try it locally against a Trino that wants both:
examples/trino-auth/setup.sh, then
docker compose -f examples/docker-compose.yml --profile trino-auth up -d.
The server will not start without LAGAAM_ALLOWED_TABLES. An agent that
can reach every table in every catalog is the thing this exists to prevent, so
that has to be asked for — set LAGAAM_ALLOW_ALL_TABLES=true if you mean it.
The budget dimensions above apply whether or not you set them. Leaving
LAGAAM_MAX_SCAN_BYTES and LAGAAM_MAX_INTERMEDIATE_ROWS unset gives you
their defaults, not an open gate — an unconfigured server refuses what it
cannot afford rather than waving it through. If queries are being denied and
you expected no limits, that is why; raise the dimension you mean to raise.
Cost quotes come from the engine's own plan estimates, and those need table
statistics: a table without stats cannot be priced, so its queries are refused
rather than guessed at. Run ANALYZE on your tables before pointing an agent
at them — a connector that has no statistics at all is effectively unusable
through the gate. That is deliberate: a query nobody can size is exactly the
kind that stalls a shared cluster.
What it doesn't do
- One agent per server process, over stdio. Identity and grant come from
the environment at startup; there is no HTTP transport or per-request token.
Run one
lagaamper agent. - No stats, no answer. A table without statistics can't be priced, so its queries are refused (see above).
- Per query, not per day. Budgets bound each query; there is no running total across an agent's session.
- Trino and Pinot only. Other engines would need their own adapter behind
the same
QueryEngineport. - Actuals are recorded, never enforced. The audit line shows what a query
really read next to its quote; nothing is cut off mid-run on those numbers —
that is what
LAGAAM_QUERY_TIMEOUTand your engine's own limits are for.
How it works
A QueryEngine port with a Trino adapter and a native Pinot adapter —
grounding, execution, and a synthesised cost quotation for both OFFLINE and
REALTIME tables. Every query_data call walks one pipeline: validate
(sqlglot AST) → table allowlist → cost quotation → budget gate → execute
(row cap + timeout) → verify → audit.
On Trino, the quote is the engine's own plan, not a guess from the SQL text:
EXPLAIN (TYPE IO) prices the bytes a query would scan, and
EXPLAIN (TYPE LOGICAL) prices the widest row count any operator would
build — the number a cross join blows and a LIMIT cannot hide.
Pinot gives no such plan — every table scan reports the same placeholder row count whatever the table holds, and no endpoint reports bytes at all — so its quote is synthesised instead: from static segment metadata, the broker's own pruning oracle (how many segments survive the predicate), and the plan's join/union shape. A consuming (REALTIME) segment, which the controller reports as empty mid-flight, is priced at the stream's own flush threshold instead of zero. A join is charged its bound rather than the product wherever the catalog can prove the join key. See ADR 0008 and ADR 0009.
Details in docs/architecture.md; the longer story in docs/vision.md.
Status
v1.0.0 — on PyPI as lagaam, listed in the MCP Registry as io.github.lagaam-ai/lagaam, installable as a Claude Code plugin (lagaam@lagaam). Trino adapter, schema tools, plan-based cost guard, query
budgets, read-only enforcement, per-agent allowlists, result verification,
audit log with post-execution actuals, https + password/JWT login for a shared
Trino. 1,243 unit + 219 integration tests (live Trino 476 and Pinot
1.5.1, batch and realtime), mypy strict. LAGAAM_ENGINE=pinot starts the
native Pinot adapter: grounding, execution and a quotation synthesised from
segment metadata and the broker's own pruning oracle, for OFFLINE and
REALTIME tables alike — a consuming segment is charged at the stream's
flush threshold, and a join is charged its bound rather than the product
wherever the catalog proves the key.
The MCP server is feature-complete: what's here is what v1 is, and new work is bug fixes and engine compatibility. The Kubernetes control plane in the roadmap is not scheduled.
Apache 2.0.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
