akko-mcp-trino

A governed MCP server for Trino. Every tool call carries the user's identity; Trino and its policy engine decide.

Give your AI agents access to Trino without giving them your data.

akko-mcp-trino is a governed MCP server for Trino. Every tool call an agent makes carries the identity of the person it acts for; what that person may read is decided inside Trino, by the policy engine you already run (OPA, Ranger, or Trino’s own access control). The server never reads on the user’s behalf with a service account, and it never decides access on its own.

Why

Most MCP servers for SQL engines connect with one technical account. Every agent, every user, every prompt then reads with the same broad rights, and the only thing between a prompt injection and your customer table is the model’s good will.

This server takes the opposite stance. The agent brings the user’s token. The token becomes X-Trino-User. Trino applies that user’s catalog scope, row filters and column masks, exactly as it does for a BI tool or a notebook.

Same question, same server, two users:

That run is real: a Mistral model driving the tools, on a Trino behind Keycloak and OPA. The model did not know carol was restricted; it did not need to.

Repository: github.com/AKKO-p/akko-mcp-trino · Package: pip install akko-mcp-trino · Apache 2.0.

In one minute

Highlights

• Identity, end to end. Verified JWT (JWKS, issuer, audience, expiry) → X-Trino-User, or the same JWT forwarded to Trino’s own authenticator (TRINO_IDENTITY_MODE=jwt). No impersonation without a verified identity, no service credential in jwt mode.
• Read-only by construction. SQL is parsed into an AST and refused if a write appears anywhere in the tree, CTEs and subqueries included.
• Two principals. X-Agent-Key names the calling product (Cursor, Claude, your own agent) for quotas and audit; it is never a user.
• Standard discovery. RFC 9728 metadata and WWW-Authenticate on every 401, so hosts know where to log in.
• Quotas, revocation, audit. Per-user and per-agent limits, optional RFC 7662 introspection, one JSON audit line per call keyed by X-Request-Id, never the token.
• Any OIDC provider, any MCP host, any model. Keycloak, Entra ID, Okta… Cursor, Claude Desktop, VS Code, the Python SDK… Mistral, or any OpenAI-compatible model through the example agent.
• Small and proven. 1 900 lines, 260 tests at 100 % line and branch coverage (including an in-process suite on the real SDK for all three transports), a product-neutral guard in CI, and eight live proofs (functional, adversarial, agent-driven, stdio, a real host, JWT passthrough on public https, context providers, OpenMetadata) on a real cluster.

How it works

The user logs in to the identity provider the platform already has. The MCP host sends the resulting JWT on every request. The server verifies it (signature against the provider’s JWKS, issuer, audience, expiry), reads the subject, and runs the SQL in Trino as that subject. Trino asks its policy engine, applies the user’s catalog scope, row filters and column masks, and returns only what the user could have read from any other client.

Two people asking the same question through the same server get two different answers. That is the whole point.

Concepts

Four words are enough to read the rest of this page.

User (the subject)

The person the agent works for. They log in to your identity provider and receive a JWT. The server verifies it and reads the subject (preferred_username or sub), which becomes X-Trino-User.

Agent product

The software that calls: Cursor, Claude Desktop, a home-grown agent. It identifies itself with a key (X-Agent-Key) used for quotas and audit. A product is never a user and has no rights on data.

Guard

The middleware that receives every MCP request and applies, in order, the product key, the token, revocation, quotas. It knows no data access rule; it carries identity.

Policy engine

What really decides: OPA, Ranger or Trino's access control. It knows the user, their groups, the row filters and column masks. The server neither replaces nor duplicates it.

Note. If you keep one sentence: the server carries identity, the engine decides. Everything else follows.

Compatibility

Prerequisites

Optional: a Prometheus to scrape /metrics, and, for revocation before expiry, an RFC 7662 introspection endpoint with a client registered for this server.

Install and run

pip install akko-mcp-trino

Or from source:

git clone https://github.com/AKKO-p/akko-mcp-trino.git
cd akko-mcp-trino
python -m venv .venv && source .venv/bin/activate
pip install -e .

The package installs a Python module (akko_mcp_trino) and a command (akko-mcp-trino); python -m akko_mcp_trino is the same entrypoint.

Point it at your Trino and your identity provider, then serve:

export TRINO_HOST=trino.example.internal
export TRINO_PORT=8080
export TRINO_USER=mcp-trino            # the account that connects and impersonates
export TRINO_CATALOG=iceberg

export MCP_AUTH_ENABLED=true
export MCP_AUTH_REQUIRED=true          # refuse requests without a verified identity
export MCP_JWKS_URL=https://idp.example.com/realms/data/protocol/openid-connect/certs
export MCP_OIDC_ISSUER=https://idp.example.com/realms/data
export MCP_OIDC_AUDIENCE=data-platform

python -m akko_mcp_trino

Before serving, akko-mcp-trino --check prints the effective configuration (never a secret) and exits with 2 if something would refuse to start. Then:

INFO:__main__:serving transport=streamable-http port=3000 auth=True strict=True

Check it is alive and can reach Trino:

curl -s localhost:3001/health   # {"status":"ok"}       never touches Trino
curl -s localhost:3001/ready    # {"status":"ready"}    runs a bounded SELECT 1
curl -s localhost:3001/metrics  # Prometheus exposition

Warning. To try it on a laptop without an identity provider, leave MCP_AUTH_ENABLED unset: every query then runs as TRINO_USER. Never run it that way where the data matters.

Container

A Dockerfile ships with the repository (non-root, health check, OCI labels); releases publish the image to ghcr.io/akko-p/akko-mcp-trino. Run it with the same environment variables, publishing ports 3000 (MCP) and 3001 (health).

Connect an MCP host

The host needs the user’s access token from the identity provider. With MCP_RESOURCE_URL set, hosts that implement OAuth discovery find the provider on their own (see Discovery); otherwise paste the token.

Cursor, Claude Desktop, VS Code (mcp.json):

{
  "mcpServers": {
    "trino": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer <the user's access token>",
        "X-Agent-Key": "<the key registered for this product, if any>"
      }
    }
  }
}

From Python, with the official SDK:

import anyio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main(token: str):
    headers = {"Authorization": f"Bearer {token}", "X-Agent-Key": "my-agent-key"}
    async with streamablehttp_client("http://localhost:3000/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("execute_query", {"sql": "SELECT 1"})
            print(result.content[0].text)

anyio.run(main, "<token>")

streamable-http (/mcp) is the default and what current hosts expect. Set MCP_TRANSPORT=sse for older hosts (/sse); the guard is the same on both.

Local hosts over stdio

Claude Desktop, Cursor and Mistral Vibe can launch the server themselves. There is no request then, so the identity comes from the environment: the user’s own access token, verified exactly like a bearer header would be, and bound to the process. Strict mode refuses to start without it.

{
  "mcpServers": {
    "trino": {
      "command": "uvx",
      "args": ["akko-mcp-trino"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "TRINO_HOST": "trino.example.internal",
        "MCP_AUTH_ENABLED": "true", "MCP_AUTH_REQUIRED": "true",
        "MCP_JWKS_URL": "https://idp.example.com/realms/data/protocol/openid-connect/certs",
        "MCP_OIDC_ISSUER": "https://idp.example.com/realms/data",
        "MCP_OIDC_AUDIENCE": "data-platform",
        "MCP_USER_TOKEN": "<the user's access token>"
      }
    }
  }
}

uvx akko-mcp-trino runs the published package without installing anything.

Use it from an agent

examples/agent.py is a complete agent in eighty lines: any OpenAI-compatible model (Mistral on La Plateforme, through OpenRouter or LiteLLM; or any other provider), the MCP tools, the user’s token. The model never sees the token; the server receives it on every tool call.

pip install akko-mcp-trino openai
export LLM_BASE_URL=https://api.mistral.ai/v1
export LLM_API_KEY=...
export LLM_MODEL=mistral-small-latest
export MCP_URL=http://localhost:3000/mcp
export USER_TOKEN=<the user's access token>
python examples/agent.py "Which catalogs can I see, and what is in them?"

Run it twice with two users’ tokens and compare. The examples folder has the details.

The tools

Every tool runs in Trino under the caller’s identity, discovery included: metadata is data, and a user who may not read a schema does not list it either. Every description is written for a model: what the tool returns, and that a masked value or a missing row is the access policy, not an error to retry.

Every identifier is validated ([A-Za-z_][A-Za-z0-9_-]*) before it is placed in SQL. execute_query accepts any SQL Trino accepts, as long as it is a read: the statement is parsed into an AST and refused if it is more than one statement, or if an INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, GRANT, CALL or SET appears anywhere in the tree, including inside a CTE, a subquery, or the statement an EXPLAIN explains. EXPLAIN ANALYZE is refused: it executes what it explains. Results are capped at TRINO_MAX_ROWS.

Errors come back to the agent as {"error": "..."}; a permission refusal from Trino is an ordinary error, not a crash.

Context: what Trino cannot say

DESCRIBE gives columns and types. It does not say what segment means, who owns the table, whether it is trustworthy, which column joins it to another, or that email is personal data. A model without that guesses, and guesses wrong.

The server knows no catalogue. It knows an interface, ContextProvider, and a chain of providers fills it, in priority order:

{"version": 1, "tables": {
  "core_postgres.clients.customers": {
    "description": "One row per customer", "owner": "Customer data team", "tier": "gold",
    "grain": ["customer_id"],
    "joins": [{"columns": ["customer_id"], "target": "core_postgres.clients.accounts", "target_columns": ["customer_id"]}],
    "tags": ["pii"],
    "columns": {"email": {"description": "Contact address", "classification": ["PII"]},
                "segment": {"description": "Commercial segment", "values": ["retail", "business", "premium"]}}}}}

With MCP_CONTEXT_PROVIDERS=file,trino-comments, describe_table returns the columns and a table block (description, owner, tier, grain, joins, tags) and a column_context block; explain_table answers from the same knowledge, or {"known": false}. The file wins where both speak. A provider describes; it never decides: knowing a column is PII changes nothing about the mask, which the engine applies. A provider that fails never hides the columns.

What happens on a request

Order matters. The agent key is checked before the token, so an unregistered product never triggers a JWKS lookup. Quotas are counted after authentication, so a forged token cannot consume the slot of the person it names. A refused request consumes nothing.

Configuration

Everything is read from the environment. Nothing is hardcoded.

Trino

Two ways to reach Trino as the user

Both fail closed: a password never travels over plain http, and the jwt mode never falls back to the service account when a request has no bearer.

Identity

Auth enabled without a JWKS URL refuses to start: an authentication layer that cannot verify anything must not pretend to. A malformed MCP_AGENT_KEYS entry refuses to start for the same reason.

Guards

Context providers

Serving

Operations

Two principals

A workspace key from Cursor or Claude is not a user. When MCP_AGENT_KEYS is set, every request must carry both:

Discovery

With MCP_RESOURCE_URL set, the server publishes RFC 9728 metadata without a token, and every 401 says where to go:

curl -s https://mcp.example.com/.well-known/oauth-protected-resource
# {"resource":"https://mcp.example.com","authorization_servers":["https://idp.example.com/realms/data"],"bearer_methods_supported":["header"]}

curl -si https://mcp.example.com/mcp | grep -i -e www-auth -e x-reason
# WWW-Authenticate: Bearer realm="trino-mcp", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"
# X-Reason: unauthenticated

authorization_servers stays empty unless MCP_OIDC_ISSUER is set; the server never guesses a provider.

Refusals

Every refusal carries X-Reason and the request id, never the token:

Audit

Every response carries X-Request-Id, the one the edge sent, or one the server generated. Every tool call writes one JSON line to the mcp.audit logger keyed by that id:

{"request_id":"edge-42","tool":"execute_query","subject":"alice","agent":"cursor","token_id":"jti-9","ok":false,"error":"Access Denied: Cannot select from columns [email] in table customers"}

token_id is the JWT’s jti. The record has no field that could hold the bearer. Join it with your gateway logs and Trino’s query log on the request id.

Revocation before expiry

A signature and an exp prove a token was valid. With MCP_INTROSPECTION_URL set, the guard asks the provider (RFC 7662) and refuses a token whose active is false. Verdicts are cached by jti for MCP_INTROSPECTION_TTL_SECONDS. If the provider cannot answer, the request is refused with 503, because “unknown” is not “still valid”.

Note. Keycloak accepts introspection only from a client that appears in the token’s aud. Register this server as its own confidential client and add it to the audience mapper; the client that issued the token is not enough.

Quotas

Two in-memory sliding windows, one per user subject and one per agent product. Counters live in the process: with several replicas the quota is per replica.

Health and metrics

/health on the health port never touches Trino, so a liveness probe cannot kill the server because Trino is slow. /ready runs a bounded SELECT 1. /metrics exposes mcp_trino_queries_total, mcp_trino_query_errors_total and mcp_trino_query_duration_seconds.

Development

pip install -e ".[dev]"
ruff check akko_mcp_trino tests examples && ruff format akko_mcp_trino tests examples
ruff check akko_mcp_trino --select D100,D101,D102,D103,D105,D107   # every public name documented
mypy akko_mcp_trino           # the package ships py.typed and type-checks clean
pip-audit                     # no known vulnerability in the dependency tree
bash lint-vendor-neutral.sh   # fails if the package imports anything product-specific
pytest                        # 260 tests; line or branch coverage below 100 % fails the run
python -m build && twine check dist/*
akko-mcp-trino --check        # effective configuration, no secrets, exit 2 if it would not start

CI runs the same steps on Python 3.12 and 3.13, then builds the container image; CodeQL scans every push and Dependabot opens weekly update pull requests for pip, Actions and the base image. A v* tag publishes the package to PyPI (trusted publishing) and the image to GHCR, see release.yml.

Every module in akko_mcp_trino/ has one responsibility and its own test file:

The README is tested too: every variable listed here is read by config.py, and the defaults stated here are the defaults in the code.

What has been proven

Eight replayable proofs run against a real cluster (Trino 483 behind Keycloak 26 and OPA), without redeploying anything:

These proofs caught six real defects before they shipped: a token whose iat was one second ahead (the issuer’s clock) was refused one time in three (clock leeway added); the launcher did not hand context plugins their variables; WITH w AS (DELETE FROM t) SELECT 1 passed a guard that only looked at the root of the tree (it now walks the whole tree); the trailing semicolon models add by habit, which Trino refuses (stripped server-side); in 0.2, discovery tools that queried Trino as the service account instead of the user (a test now walks every tool); and a DATE column that broke the serialisation of any result (dates, decimals and binaries are rendered properly).

Design notes

The guard is a pure ASGI middleware, not BaseHTTPMiddleware. The latter runs the downstream in a separate task and breaks ContextVar propagation: the identity would never reach the tools. This was verified with concurrent sessions of two users on both transports, zero crossed responses.

Mounting is transport-independent. One code path builds the transport app and mounts the guard, whatever the transport. The guard once lived only on the branch the default transport never took; a test now asserts it for both.

Every tool carries the identity, not only execute_query. Version 0.1 ran discovery as the service account; a restricted user could list what the engine would hide from them. Fixed in 0.2 with a test that walks every tool.

Read-only is decided on the AST, anywhere in the tree. A leading-keyword check lets WITH w AS (DELETE FROM t) SELECT 1 through. So did a root-node check, until a live adversarial proof caught it. The guard now walks the whole tree.

Identity comes from the token, never from a header. A caller sending X-Trino-User or X-Forwarded-User changes nothing; the subject forwarded to Trino is the verified JWT subject.

The server does not decide access. It carries identity. Putting policy in the server would duplicate, and eventually contradict, what the engine already enforces for every other client.