AKKO MCP server for Trino

akko-mcp-trino

English · Français

Give your AI agents read-only access to Trino, and nothing more.

akko-mcp-trino is an MCP server for Trino. An agent can use it to find tables and columns, describe a schema or a table, list catalogs, schemas and tables, and explain or run a query. The server parses every statement and refuses any write before it reaches Trino. By default, each query runs as the user the agent acts for. The server verifies the user's token, which must be issued for this server. It then obtains a separate token for Trino from the identity provider (OAuth 2.0 Token Exchange). The user's own token never leaves the server. Trino's access control (OPA, Ranger, or Trino's own rules) then decides what that user may read. Results are limited in rows and in time, and every call leaves one audit line.

Upgrading from 0.7.0? 0.7.1 and 0.7.2 are security releases. execute_query refuses

SHOW STATS, EXPLAIN, SHOW CREATE and the other reads listed in

Security, and the user is read from sub.

With Keycloak, set MCP_JWT_USER_CLAIM=preferred_username before upgrading. See

MIGRATING.md, and Upgrading for other versions.

Understand in five steps

An agent connected through one service account with broad rights reaches Trino under that account, so the rules written for Carol no longer apply. The left panel is an illustration: the sandbox's policy would refuse such an account. akko-mcp-trino brings Carol's own identity to Trino, and the rules Trino already has do the rest.

The same query from the three users of the sandbox, through the same MCP client and the same server. Trino applies the sandbox's OPA policy to each of them; the server copies no rule.

A real trial, tool call by tool call: Mistral on 0.7.0 looks for the segment with the largest balance. The search matches word by word, the error on a wrong join names the table to read, and the agent fixes its join. Every tool answer shown is the server's, replayed in the sandbox.

Four identity modes, from the safest to the simplest. jwt is the default; service gives every caller the same account and is used only when you name it.

The same five business questions, put to Mistral and to Claude, on 0.6.1 and on 0.7.0. Mistral varies more from one run to the next than the gap between the versions, and 0.7.0 sends about 41% more input tokens per question, because its tool descriptions are longer. The harness and its reports are in akko-sandbox.

The interactive version of these five steps is on akko-ai.com/en/docs/understand (also en français).

Try it in five minutes

The sandbox starts Keycloak, Trino, OPA and the server on your machine, with the three users above:

git clone https://github.com/AKKO-p/akko-sandbox.git

cd akko-sandbox docker compose up -d --wait ./demo.sh

The quickstart goes on with a user's token, an MCP host and a first question.

Why

An agent that reads a lakehouse needs a small, predictable surface: a few tools whose descriptions a model understands, answers with hard limits, and a guarantee that a prompt injection cannot turn a question into a DROP TABLE through this server. This server is that surface, and nothing else. It does not decide access: Trino decides for each user with the rules it already has, or, in service mode, for the one identity you give it.

Features

• Read-only by construction, through this server. SQL is parsed into an AST and refused if a write appears anywhere in the tree, CTEs and subqueries included. Table functions (TABLE(...), such as a JDBC connector's system.query) and the system catalog are refused too, including through a name without a catalog when the session catalog is system. What a user can do in Trino by other means is governed by Trino's rules: see Security.
• Per-user rights by default. In jwt mode, the default, the server verifies the caller's token (issued for this server, never for Trino), exchanges it at the identity provider for a token whose audience is Trino (RFC 8693), and Trino runs the query as that user. The caller's token is never passed on. A request without a valid token is refused with 401.
• A fallback without token exchange. In impersonation mode, the server authenticates to Trino with its own account (password or client certificate), and Trino runs the query as the verified caller, under an impersonation rule that only this account has.
• One identity, only when named. In service mode, every query runs as TRINO_USER. It is never chosen by default, and the server says so at start and to every host in its initialization instructions.
• Limits by default. A row cap with a truncated flag (100), a time budget per query, cancelled in Trino (60 s), and a time budget per tool call (120 s).
• One audit line per call. Keyed by X-Request-Id, never holding the token or the SQL text: who called which tool, with which outcome, for how long.
• Nine tools, annotated with what they can really do: execute_query is annotated read-only only while TRINO_READ_ONLY is true.
• Token verification. Bearer tokens are verified against any OIDC provider's JWKS (issuer, audience bound to this server, expiry, clock tolerance), a token issued for Trino is refused, the protected resource metadata is published (RFC 9728), and the Host header is filtered.
• Extensible without forking. Tool plugins and extensions are Python packages named at start: identity modes, guards, audit fields, routes, tools. An extension can only refuse what the core allows, never widen it.
• Any MCP host, any model. Cursor, Claude Desktop, VS Code and the Python SDK; and any model, Mistral included, through the example agent.
• Tests. 100% line and branch coverage, including in-process suites on the real SDK for all three transports, a live run against Keycloak and Trino in CI (integration/), and a check that the package imports no vendor-specific code.

Documentation

These pages describe main. The documentation of a release is at its tag.

| Modules | token-policy, fingerprint-audit