<p align="center"> <img src="https://img.shields.io/github/actions/workflow/status/AKKO-p/akko-mcp-trino/ci.yml?branch=main&label=ci" alt="CI"> <img src="https://img.shields.io/badge/tests-322%20passed-success" alt="Tests"> <img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Coverage"> <img src="https://img.shields.io/badge/version-0.5.3-blue" alt="Version"> <img src="https://img.shields.io/badge/python-3.12%20%7C%203.13-blue" alt="Python"> <img src="https://img.shields.io/badge/trino-%E2%89%A5%20351-blue" alt="Trino"> <img src="https://img.shields.io/badge/MCP-up%20to%202025--11--25%20%C2%B7%20streamable--http%20%7C%20sse%20%7C%20stdio-blue" alt="MCP"> <img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License"> <img src="https://img.shields.io/badge/code%20style-ruff-000000" alt="Ruff"> <img src="https://img.shields.io/badge/status-beta-yellow" alt="Status"> </p>

akko-mcp-trino

English · Français

<!-- mcp-name: io.github.ab2dridi/akko-mcp-trino -->

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

akko-mcp-trino is an MCP server for Trino. It lets an agent list catalogs, schemas and tables, describe a table, explain a query and run it, and it guarantees that nothing it sends can write: every statement is parsed, and a write anywhere in it is refused before Trino. Every query runs either as the one Trino identity the administrator configured, or as the user the agent acts for, whose own token Trino verifies again. Either way Trino's access control (OPA, Ranger, or Trino's own rules) decides what the agent may read. Results are bounded in rows and in time, and every call leaves one audit line.

Why

An agent that reads a lakehouse needs a small, predictable surface: a few tools whose descriptions a model understands, answers that never run away, and a guarantee that a prompt injection cannot turn a question into a DROP TABLE. This server is that surface, and nothing else. It does not decide access: in jwt mode Trino decides for each user with the rules it already has, and in service mode for the one identity you give it, with the rights every caller of this server may have, no more.

Highlights

• Read-only by construction. 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.
• The user's own rights, end to end. In jwt mode the caller's verified token goes to Trino, which verifies it again and runs the query as that user: Ranger or OPA decide for the person, not for a service account, with no password and no right to act for another user. A request without a verified token is refused, never run as anyone else.
• Or one identity, configured by the administrator. In service mode, the default, every query runs as TRINO_USER, authenticated by TRINO_PASSWORD over https (or nothing, for a local Trino). The agent cannot name another user.
• Bounded. A row cap with a truncated flag, a time budget per query cancelled in Trino, a time budget per tool call.
• One audit line per call. Keyed by X-Request-Id, never the token, never the SQL text: who called which tool, with which outcome, for how long.
• Six tools, no more. List catalogs, schemas and tables, describe a table, explain a statement, run a read-only query.
• A guarded door. Bearer tokens verified against any OIDC provider's JWKS (issuer, audience, expiry, clock tolerance), strict mode refusing a request without a verified caller, a Host header filter.
• Built to be extended without being forked. Tool plugins and extensions are Python packages named at start: identity modes, guards at the door, 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, the Python SDK… Mistral, or any OpenAI-compatible model through the example agent.
• Small and proven. 322 tests at 100 % line and branch coverage, including in-process suites on the real SDK for all three transports, and a product-neutral guard in CI.

Documentation

• How it works, end to end: akko-ai.com/en/docs/how-it-works (also en français).
• Guide, prerequisites, configuration, examples: akko-ai.com/docs/akko-mcp-trino (also in English) and akko-ai.com/docs/exemples.
• Reference, in this repository: this README, examples/, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md.

Contents

1. How it works
2. Compatibility
3. Prerequisites
4. Install and run
5. Connect an MCP host
6. Use it from an agent
7. The tools
8. Extensions
9. What happens on a request
10. Configuration
11. Operations
12. Development
13. Design notes
14. Contributing
15. About AKKO

How it works

flowchart LR
    Host["MCP host<br/>(Cursor, Claude, VS Code, an agent)"]
    IdP["Identity provider<br/>(OIDC, JWKS)"]
    Server["akko-mcp-trino"]
    Trino["Trino"]
    Policy["Policy engine<br/>(OPA, Ranger, built-in)"]
    Data[("Data sources")]

    Host -- "1. tool call + Bearer token" --> Server
    Server -. "verify signature<br/>against JWKS" .-> IdP
    Server -- "2. read-only SQL, as the caller (jwt)<br/>or as TRINO_USER (service)" --> Trino
    Trino -- "3. may this identity read this?" --> Policy
    Trino -- "4. rows, as that identity may read them" --> Server
    Server -- "5. result" --> Host
    Trino --> Data

The host calls a tool. When authentication is on, the server verifies the caller's token (signature against the provider's JWKS, issuer, audience, expiry) and refuses a request without one in strict mode; the caller's name goes into the audit line. The server then checks the statement (read-only, identifiers, table functions, the system catalog) and runs it in Trino under the identity mode TRINO_IDENTITY_MODE names. Trino asks its policy engine and returns what that identity may read, bounded in rows and time.

| Mode | Who Trino sees | What Trino needs | Who decides | |---|---|---|---| | service (default) | TRINO_USER, the same for every caller | a password (or nothing, locally) | the rights of that one identity | | jwt | the caller, by their own verified token | its JWT authenticator, trusting the same identity provider | the rights of each user |

In service mode the caller's token never leaves the server. In jwt mode it goes to Trino only once verified, over https only, and never into the audit line; without one, the query is refused. An extension (see Extensions) may add other identity modes.

Compatibility

| | Supported | Tested | |---|---|---| | Python | 3.12, 3.13 | 3.12, 3.13 (CI) | | Trino | 351 and later, over http (local) or https with a password; https with the JWT authenticator for jwt | a recent release behind OPA, with row filters and column masks | | Policy engines | OPA (trino-opa), Ranger (Trino plugin), Trino file-based access control | OPA with row filters and column masks | | Identity providers (the door) | any OIDC provider publishing a JWKS | Keycloak 26 | | MCP | protocol negotiated by the official mcp SDK 2.2 (versions up to 2025-11-25); transports streamable-http, sse and stdio | all three, official SDK client, in CI | | MCP hosts | remote: anything that sends a bearer header; local: any stdio host | Python SDK, the example agent | | Models | any, the server never talks to a model | Mistral Small 3.2 through OpenRouter, driving the tools |

Prerequisites

| You need | Why | Notes | |---|---|---| | Python 3.12 or later | runtime | pip and a virtual environment | | A reachable Trino coordinator | the engine | any recent version; https when a password is set, and for jwt | | A Trino identity for this server (service) | the rights of every caller | TRINO_USER, and TRINO_PASSWORD when Trino authenticates by password; give it read rights only on what every caller may read | | Or Trino's JWT authenticator (jwt) | each user reads with their own rights | http-server.authentication.type=JWT with the identity provider's JWKS; the token's audience must be one Trino accepts | | A policy engine deciding for Trino | the governance | OPA (opa.policy.uri), Ranger, or Trino file-based rules | | An OIDC provider with a JWKS endpoint | the door (optional) | Keycloak, Entra ID, Okta, Dex… Tokens must carry iss, aud, exp, and a subject (preferred_username or sub) | | An MCP host | the client | Cursor, Claude Desktop, VS Code, or any client built on the mcp SDK |

Optional: a Prometheus to scrape /metrics.

Install and run

pip install akko-mcp-trino        # or: pipx install akko-mcp-trino
uvx akko-mcp-trino --version      # run it without installing, the way most MCP hosts do

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=8443
export TRINO_HTTP_SCHEME=https
export TRINO_CATALOG=iceberg
export TRINO_USER=mcp-reader
export TRINO_PASSWORD=...               # Basic authentication, https only

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; over stdio it checks that MCP_USER_TOKEN is present, not that it is valid (the real start verifies the token). Then:

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

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"}    service: a bounded SELECT 1 as TRINO_USER; jwt: Trino's /v1/info
curl -s localhost:3001/metrics  # Prometheus exposition

Every query runs as TRINO_USER, whoever calls: give that identity the rights every caller of this server may have, no more. In strict mode, a request without a verified token is refused before any query.

Each user with their own rights (jwt)

When Trino trusts the same identity provider, let it decide for each user:

export TRINO_IDENTITY_MODE=jwt         # the caller's verified token goes to Trino
export TRINO_HTTP_SCHEME=https         # required: a token never travels over http
export MCP_AUTH_ENABLED=true
export MCP_AUTH_REQUIRED=true
# TRINO_USER and TRINO_PASSWORD are not used

On the Trino side, http-server.authentication.type=JWT, http-server.authentication.jwt.key-file set to the provider's JWKS URL, and http-server.authentication.jwt.principal-field naming