The open source core

The core of akko-mcp-trino, under the Apache 2.0 licence, gives an AI agent read-only MCP access to Trino, by default under each user's own identity, without ever passing their token on.

The core of akko-mcp-trino is an MCP server for Trino, under the Apache 2.0 licence, at version 0.6.0. It gives an AI agent six tools to explore a Trino and read data from it. The read-only guard is decided on the SQL tree. Every call is bounded and leaves one audit line.

By default, every query runs as the user the agent works for. The server verifies the user’s token, issued for this server. It exchanges it at the identity provider (IdP) for a separate token, issued for Trino, through OAuth 2.0 Token Exchange (RFC 8693). The user’s own token never leaves the server. Trino and its policy then decide what the agent may read.

Coming from 0.5? 0.6.0 changes the defaults. A verified caller is required, and jwt mode exchanges the caller’s token instead of passing it on, as the MCP specification requires. A 0.5 configuration no longer starts as it is: akko-mcp-trino --check says what is missing, and MIGRATING.md walks through each step. The 0.5.x releases are no longer supported.

The core, and what AKKO and ARCHE deliver

The core suits agents that each read under the person’s own rights, on a Trino that trusts your IdP. It also suits an agent that reads under one account whose rights your rules bound. The overview describes the complete server.

Install

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

You can also install it 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 .

It needs Python 3.12 or later. The package installs a Python module (akko_mcp_trino) and a command (akko-mcp-trino); python -m akko_mcp_trino starts the same server.

In a container

The image is published on Docker Hub, for linux/amd64 and linux/arm64. It runs as a non-root user and carries a health check. It takes the same environment variables, on ports 3000 (MCP) and 3001 (health).

docker run --rm akkoai/akko-mcp-trino:0.6 akko-mcp-trino --version

docker run -d --name akko-mcp-trino -p 3000:3000 -p 3001:3001 \
  -e TRINO_HOST=trino.example.internal -e TRINO_PORT=8443 -e TRINO_HTTP_SCHEME=https \
  -e TRINO_CATALOG=iceberg \
  -e MCP_JWKS_URL=https://idp.example.com/realms/data/protocol/openid-connect/certs \
  -e MCP_OIDC_ISSUER=https://idp.example.com/realms/data \
  -e MCP_OIDC_AUDIENCE=akko-mcp \
  -e TRINO_TOKEN_EXCHANGE_URL=https://idp.example.com/realms/data/protocol/openid-connect/token \
  -e TRINO_TOKEN_EXCHANGE_CLIENT_ID=akko-mcp \
  -e TRINO_TOKEN_EXCHANGE_CLIENT_SECRET=... \
  -e TRINO_TOKEN_EXCHANGE_AUDIENCE=trino \
  akkoai/akko-mcp-trino:0.6

The 0.6 tag follows the latest release of the 0.6 line; 0.6.0 names one release.

The code, the tests and the examples are on GitHub; the changelog tracks every change, and a vulnerability is reported through the security policy.

Get started

The server reads its whole configuration from the environment. Point it at your Trino and at your IdP, then start it. The defaults are the safe ones: every query runs as the caller (jwt mode), and a request without a valid token is refused.

export TRINO_HOST=trino.example.internal
export TRINO_PORT=8443
export TRINO_HTTP_SCHEME=https         # required: a token never travels over http
export TRINO_CATALOG=iceberg

# The door: tokens issued for this server, verified against the IdP's JWKS
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=akko-mcp       # the audience of tokens issued for this server, never Trino's

# A token for Trino, by token exchange (RFC 8693), never the caller's own
export TRINO_TOKEN_EXCHANGE_URL=https://idp.example.com/realms/data/protocol/openid-connect/token
export TRINO_TOKEN_EXCHANGE_CLIENT_ID=akko-mcp
export TRINO_TOKEN_EXCHANGE_CLIENT_SECRET=...
export TRINO_TOKEN_EXCHANGE_AUDIENCE=trino

akko-mcp-trino --check                 # the effective configuration, no secret
akko-mcp-trino                         # serves streamable-http on port 3000

--check prints the effective configuration and any warning, without ever printing a secret. It exits with code 2 if the server would refuse to start. On start, the server writes a line like this one.

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

Three endpoints then let you watch the server, on the health port.

curl -s localhost:3001/health    # {"status":"ok"}     never touches Trino
curl -s localhost:3001/ready     # {"status":"ready"}  Trino answers
curl -s localhost:3001/metrics   # Prometheus metrics

/health never touches Trino, so a liveness probe cannot kill the server because Trino is slow. /ready asks Trino according to the identity mode. In jwt mode, it is Trino’s public /v1/info. In impersonation and service modes, it is a bounded SELECT 1 as TRINO_USER, impersonating no one. /metrics exposes mcp_trino_queries_total, mcp_trino_query_errors_total and mcp_trino_query_duration_seconds.

Identity in Trino

The server first verifies the caller’s token: signature against the IdP’s JWKS, issuer, audience, expiry. The audience must name this server (MCP_OIDC_AUDIENCE or MCP_RESOURCE_URL). A token issued for Trino is refused, even if it also names this server. By default, a request without a valid token gets a 401 before any query reaches Trino. The TRINO_IDENTITY_MODE variable then says under which identity Trino runs it.

In every mode, the caller’s own token never leaves the server. The caller’s name always comes from their verified token, never from a header they wrote. jwt and impersonation refuse to start unless the door requires a valid token, and an unknown mode stops the server from starting.

Each user under their own rights (jwt, the default)

The caller’s token is issued for this server. The server exchanges it at the IdP for a token whose audience is TRINO_TOKEN_EXCHANGE_AUDIENCE, keeps it in memory until shortly before it expires, and sends it to Trino. The token endpoint is https only.

On the IdP, give this server a confidential client allowed to exchange tokens, and make Trino’s audience available to it. With Keycloak 26, enable Standard token exchange on that client and add an audience mapper for the Trino client to it. The clients of your MCP hosts put this server in the audience of their tokens, with an audience mapper too. The repository’s integration/ folder holds such a realm, tested on every pull request.

On the Trino side, set http-server.authentication.type=JWT and http-server.authentication.jwt.key-file to the IdP’s JWKS URL. Set http-server.authentication.jwt.principal-field to the same claim the server reads (preferred_username or sub). required-issuer and required-audience pin the token to your IdP and to Trino’s audience.

The server never passes on the token it received. It exchanges it for a token issued for Trino, with a client of its own. Trino verifies that second token and runs the query under the person’s name: Ranger or OPA decide for that person. The server’s only secret is that client: grant it, and it alone, the right to exchange for Trino’s audience. A configuration that would accept Trino’s audience refuses to start.

Without token exchange (impersonation)

When the IdP cannot exchange tokens, the server authenticates to Trino as its own account, and Trino runs each query as the verified caller.

export TRINO_IDENTITY_MODE=impersonation
export TRINO_USER=mcp-service
export TRINO_CLIENT_CERT=/certs/mcp-service.crt   # mTLS; or TRINO_PASSWORD over https
export TRINO_CLIENT_KEY=/certs/mcp-service.key

Trino authenticates that account (certificate or password authenticator, besides the one your users have) and allows it, and only it, to act as users. With Trino’s file-based access control, that is the following rule.

{"impersonation": [{"original_user": "mcp-service", "new_user": ".*", "allow": true}]}

Narrow new_user to the users the agents act for. With that rule, nobody else may act as someone else: a user who sends a header naming another user is refused by Trino. Keep the account’s credential as you would any service account’s: whoever holds it can act as any user the rule allows.

One identity (service, only when named)

export TRINO_IDENTITY_MODE=service
export TRINO_USER=mcp-reader
export TRINO_PASSWORD=...               # or TRINO_CLIENT_CERT and TRINO_CLIENT_KEY; https only

Every query runs as TRINO_USER, whoever calls. Give that identity the rights every caller of this server may have, read-only, no more. The server announces it as a warning at start, in --check and to every MCP host, in the initialization instructions. The door stays on by default. To serve without one, locally only, also set MCP_AUTH_ENABLED=false and MCP_AUTH_REQUIRED=false; the warning says so.

What proves it

On every pull request, the repository runs a live integration, Keycloak and Trino in Docker. It covers token exchange, impersonation by client certificate, service mode and every refusal at the door. The sandbox replays it in five minutes on 0.6.0. Two accounts ask the same question and get two answers. A request without a token, a forged token and a token issued for Trino instead of the server all get a 401.

The six tools

Every tool goes through Trino under the identity mode, the listing tools included: metadata is data, and Trino lists only what that identity may see. Every tool description is written for a model and says what the tool returns. Those of describe_table and execute_query say that a masked value or a missing row is the access policy, not an error to retry. Errors come back to the agent as {"error": "..."}, with Trino’s whole message; a permission refusal is an ordinary error, not a crash.

execute_query is annotated read-only (readOnlyHint: true) only while TRINO_READ_ONLY is true. With TRINO_READ_ONLY=false, its annotations and its description say it may write, so that the MCP host asks for the confirmation it would skip for a read-only tool.

Read-only

execute_query accepts any SQL Trino accepts, as long as it is a read. The statement is parsed into a syntax tree. It is refused if it holds more than one statement, or if a write (INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, GRANT, CALL, SET) appears anywhere in the tree, CTEs, subqueries and the statement an EXPLAIN explains included. EXPLAIN ANALYZE is refused, since it runs what it explains.

Table functions (TABLE(...)) are refused. A TABLE(pg.system.query(query => '...')) reads like a plain SELECT, but sends raw SQL to the source under the connector’s account, outside row filters and column masks. The system catalog is refused too. Every identifier is validated ([A-Za-z_][A-Za-z0-9_-]*) before it enters the SQL. A name without a catalog is read in the session catalog (TRINO_CATALOG): give it a data catalog.

What read-only covers

The guard refuses every write that passes through this server. It is not a guarantee about the user’s rights in Trino. In jwt and impersonation modes, Trino runs the query as the user, with the rights its policy gives that user. A user allowed to write can still write through another Trino client, with a token for Trino the IdP gives them directly. The token obtained by exchange stays in the server’s memory and is never returned to the agent or the MCP host.

For read-only end to end, the engine must hold the line too. Give read-only rules to the identities agents reach Trino with. Let only this server’s client exchange for Trino’s audience. Narrow the impersonation rule to the users agents act for. Refuse table functions and the system catalog in the policy too. The guard stays a second line. The blog tells how it took its shape.

Bounds

A question an agent asks should come back within a minute. A query that needs longer is usually a full scan the agent should narrow, and the error it gets says so. Two minutes per call leave room for a tool that runs two or three queries. 0 removes a budget’s limit, and --check prints both. The budget is held by the server, not set as a session property, so that an engine that forbids session properties does not refuse every query.

The log

Every response carries an X-Request-Id header: the gateway’s when it is a plain token, otherwise a generated one. 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","ok":false,"error":"USER_ERROR:PERMISSION_DENIED","duration_ms":84}

With the default logging configuration, the line comes out prefixed with INFO:mcp.audit:; a collector that expects pure JSON strips that prefix. The line says who called which tool, with which outcome and for how long. It has no field that could hold the token or the SQL text. An error appears as a code, never a message, because a message from Trino may quote a value read from a row (Cannot cast '<value>' to INT). The agent reads the whole message.

Refusals and warnings

Every refusal carries an X-Reason header and the request id, never the token. A request without a valid token (none, forged, expired, or issued for another audience, Trino’s included) gets 401 unauthenticated, with a body that says what to send. When MCP_RESOURCE_URL is set, the server publishes its protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource, and the 401 carries WWW-Authenticate: Bearer resource_metadata="…", as the MCP authorization specification asks.

A configuration that leaves something open is said three times: a WARNING line at start, in --check, and to every MCP host in the initialization instructions. The core warns of service mode and of a door that does not require a valid token.

Connect an MCP host

Remotely, the MCP host connects to the server’s address (/mcp over streamable-http, the default transport; /sse for an older MCP host). It sends the user’s access token, issued for this server. An MCP host that implements MCP authorization finds the IdP itself, through the metadata the server publishes when MCP_RESOURCE_URL is set.

{
  "mcpServers": {
    "trino": {
      "url": "https://mcp.example.internal/mcp",
      "headers": {"Authorization": "Bearer <the user's access token, issued for this server>"}
    }
  }
}

Locally, Claude Desktop, Cursor or Mistral Vibe start the server themselves over stdio. There is no HTTP request: the caller comes from the environment, through the user’s access token in MCP_USER_TOKEN, issued for this server and verified like a header. In strict mode, the default, the server refuses to start without it. In jwt mode, that token is exchanged for a token for Trino, as over http.

{
  "mcpServers": {
    "trino": {
      "command": "uvx",
      "args": ["akko-mcp-trino"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "TRINO_HOST": "trino.example.internal", "TRINO_PORT": "8443", "TRINO_HTTP_SCHEME": "https",
        "TRINO_CATALOG": "iceberg",
        "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": "akko-mcp",
        "TRINO_TOKEN_EXCHANGE_URL": "https://idp.example.com/realms/data/protocol/openid-connect/token",
        "TRINO_TOKEN_EXCHANGE_CLIENT_ID": "akko-mcp",
        "TRINO_TOKEN_EXCHANGE_CLIENT_SECRET": "<this server's client secret>",
        "TRINO_TOKEN_EXCHANGE_AUDIENCE": "trino",
        "MCP_USER_TOKEN": "<the user's access token, issued for this server>"
      }
    }
  }
}

In impersonation mode, replace the TRINO_TOKEN_EXCHANGE_* variables with TRINO_IDENTITY_MODE=impersonation, TRINO_USER and its certificate or password. Filter the Host header with MCP_ALLOWED_HOSTS when a browser can reach the server.

Extend without modifying

A Python package can add tools or behaviour around the core, without modifying it. It registers under an entry-point group, and the operator names it at start.

[project.entry-points."akko_mcp_trino.tools"]
my-tools = "my_package.tools:register"

export MCP_TOOL_PLUGINS=my-tools

Nothing is loaded that is not named, and an unknown name stops the server from starting. An added tool goes through the same client, hence under the same identity mode, with the same read-only guard and the same log line.

A broader extension (MCP_EXTENSIONS, group akko_mcp_trino.extensions) can add identity modes, accepted audiences (never Trino’s), guards at the door, routes, tools or log fields. Its guards run around the token verification, never instead of it, and the read-only guard applies to every query. An identity mode that sends Trino a token for the caller must obtain one for Trino, never forward the caller’s.

Configuration

The whole configuration is read from the environment; nothing is hardcoded.

Trino

Identity

Verification on without a JWKS URL, or without an audience of this server’s own, refuses to start. So does MCP_AUTH_REQUIRED=true with MCP_AUTH_ENABLED=false, since the server would refuse every request.

Serving

Compatibility

Going further

For other ways to carry the user’s identity, an audit linked to the engine’s log, the business context of the catalogue and agent and access management, see the server delivered in AKKO and ARCHE. For a question, write to us. To report a problem with the core, open an issue.