Authentication and Deployment Guide

Transport Methods

The server supports two transport methods:

STDIO Transport (Default)

• Direct integration with MCP clients

• Ideal for desktop applications like Claude Desktop

• Uses standard input/output for communication

HTTP Transport with StreamableHTTP

• Modern approach: Uses the /mcp endpoint with StreamableHTTP protocol

• Legacy support: Maintains /sse endpoint for backward compatibility with SSE

• Supports web-based MCP clients

• Enables JWT authentication for secure access

OAuth 2.0 Authentication

✅ Production-Ready: Complete OAuth 2.0 implementation with OIDC provider support for secure remote deployments.

Supported Authentication Modes:

1. OIDC Provider Mode (Production - Recommended)

   # Configure with OAuth provider (Okta example)
   export OAUTH_ENABLED=true
   export OAUTH_PROVIDER=okta
   export OIDC_ISSUER=https://your-domain.okta.com
   export OIDC_AUDIENCE=your-service-audience
   export MCP_TRANSPORT=http
   mcp-trino

2. HMAC Mode (Development/Testing)

   # Simple JWT with shared secret
   export OAUTH_ENABLED=true
   export OAUTH_PROVIDER=hmac
   export JWT_SECRET=your-secret-key-here
   export MCP_TRANSPORT=http
   mcp-trino

Key Features:

• Multiple Providers: Okta, Google, Azure AD, and custom OIDC providers

• JWKS Validation: Automatic key rotation and signature verification

• Token Caching: Performance optimization with 5-minute cache expiration

• MCP Compliance: Full OAuth 2.1 and MCP authorization specification support

Client requests must include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

For detailed OAuth configuration, deployment examples, and browser-based MCP client compatibility lessons learned, see oauth.md.

HTTPS Support

For production deployments with authentication, HTTPS is strongly recommended:

export HTTPS_CERT_FILE=/path/to/certificate.pem
export HTTPS_KEY_FILE=/path/to/private-key.pem
export OAUTH_ENABLED=true
export MCP_TRANSPORT=http
mcp-trino

The server will automatically start with HTTPS when certificate files are provided.

Remote MCP Server Deployment

Since the server supports JWT authentication and HTTP transport, you can deploy it as a remote MCP server accessible to multiple clients over the network.

Important: When deploying a remote MCP server (behind a load balancer, reverse proxy, or with a public domain), you must set MCP_URL to the public base URL of your MCP server (including scheme and port if non-standard). This value is used in OAuth metadata and printed endpoints so clients discover the correct URLs.

Production Deployment Example

# Deploy with HTTPS and JWT authentication
export MCP_TRANSPORT=http
export MCP_PORT=443
export MCP_URL=https://your-mcp-server.com
export OAUTH_ENABLED=true
export HTTPS_CERT_FILE=/etc/ssl/certs/mcp-trino.pem
export HTTPS_KEY_FILE=/etc/ssl/private/mcp-trino.key
export TRINO_HOST=your-trino-cluster.com
export TRINO_PORT=443
export TRINO_USER=service-account
export TRINO_PASSWORD=service-password

# Start the server
mcp-trino

Client Configuration for Remote Server

With JWT Authentication:

{
  "mcpServers": {
    "remote-trino": {
      "url": "https://your-mcp-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}

Load Balancer/Proxy Configuration:

server {
    listen 443 ssl;
    server_name your-mcp-server.com;

    ssl_certificate /etc/ssl/certs/mcp-trino.pem;
    ssl_certificate_key /etc/ssl/private/mcp-trino.key;

    location /mcp {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Authorization $http_authorization;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Docker Deployment

For containerized deployment:

FROM ghcr.io/tuannvm/mcp-trino:latest

ENV MCP_TRANSPORT=http
ENV MCP_PORT=8080
ENV OAUTH_ENABLED=true
ENV TRINO_HOST=your-trino-cluster.com
ENV TRINO_PORT=443
ENV TRINO_USER=service-account
ENV TRINO_PASSWORD=service-password

EXPOSE 8080

CMD ["mcp-trino"]

# Build and run with Docker
docker build -t mcp-trino-server .
docker run -d -p 8080:8080 \
  -e HTTPS_CERT_FILE=/certs/cert.pem \
  -e HTTPS_KEY_FILE=/certs/key.pem \
  -v /path/to/certs:/certs \
  mcp-trino-server

Security Considerations

• JWT Audience Validation: The server enforces JWT audience claims to prevent cross-service token reuse

  • Audience must be explicitly configured via OIDC_AUDIENCE environment variable

  • Tokens must include the correct audience claim to be accepted

  • Prevents unauthorized access from other services using the same OAuth provider

• JWT Token Management: Implement proper token rotation and validation

• Network Security: Use HTTPS in production and consider network-level security

• Access Control: Implement proper authentication and authorization mechanisms

• Monitoring: Set up logging and monitoring for security events

• Token Security:

  • Never commit JWT secrets to version control

  • Use strong, randomly generated secrets (minimum 256 bits)

  • Implement short token expiration times with refresh mechanisms

  • Store tokens securely in client applications

• Production Recommendations:

  • Use asymmetric algorithms (RS256, ES256) instead of HS256

  • Implement proper issuer (iss) and audience (aud) validation

  • Use established OAuth 2.1/OpenID Connect providers

  • Implement token revocation mechanisms

Quick Start with OAuth

For Production (OIDC):

# Configure OAuth provider
export OAUTH_ENABLED=true
export OAUTH_PROVIDER=okta
export OIDC_ISSUER=https://your-domain.okta.com
export OIDC_AUDIENCE=https://your-domain.okta.com
export MCP_TRANSPORT=http

# Start server
mcp-trino

For Development (HMAC):

# Simple JWT testing
export OAUTH_ENABLED=true
export OAUTH_PROVIDER=hmac
export JWT_SECRET="your-test-secret"
export MCP_TRANSPORT=http

# Start server
mcp-trino

Client Configuration:

{
  "mcpServers": {
    "trino-oauth": {
      "url": "https://your-mcp-server.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_JWT_TOKEN"
      }
    }
  }
}

Configuration Reference

Variable	Description	Default
TRINO_HOST	Trino server hostname	localhost
TRINO_PORT	Trino server port	8080
TRINO_USER	Trino user	trino
TRINO_PASSWORD	Trino password	(empty)
TRINO_CATALOG	Default catalog	memory
TRINO_SCHEMA	Default schema	default
TRINO_SCHEME	Connection scheme (http/https)	https
TRINO_SSL	Enable SSL	true
TRINO_SSL_INSECURE	Allow insecure SSL	true
TRINO_ALLOW_WRITE_QUERIES	Allow non-read-only SQL queries	false
TRINO_QUERY_TIMEOUT	Query timeout in seconds	30
MCP_TRANSPORT	Transport method (stdio/http)	stdio
MCP_PORT	HTTP port for http transport	8080
MCP_HOST	Host for HTTP callbacks	localhost
MCP_URL	Public base URL of MCP server (used for OAuth metadata and client discovery); required for remote deployments	http://localhost:8080
OAUTH_ENABLED	Enable OAuth authentication	false
OAUTH_PROVIDER	OAuth provider (hmac/okta/google/azure)	hmac
JWT_SECRET	JWT secret for HMAC mode	(empty)
OIDC_ISSUER	OIDC provider issuer URL	(empty)
OIDC_AUDIENCE	OIDC audience identifier (required for OIDC providers)	(empty - must be set)
OIDC_CLIENT_ID	OIDC client ID	(empty)
HTTPS_CERT_FILE	Path to HTTPS certificate file	(empty)
HTTPS_KEY_FILE	Path to HTTPS private key file	(empty)

Note: When TRINO_SCHEME is set to "https", TRINO_SSL is automatically set to true regardless of the provided value.

Important: The default connection mode is HTTPS. If you're using an HTTP-only Trino server, you must set TRINO_SCHEME=http in your environment variables.

Security Note: By default, only read-only queries (SELECT, SHOW, DESCRIBE, EXPLAIN) are allowed to prevent SQL injection. If you need to execute write operations or other non-read queries, set TRINO_ALLOW_WRITE_QUERIES=true, but be aware this bypasses this security protection.

For Web Client Integration: When using with web clients, set MCP_TRANSPORT=http and connect to the /mcp endpoint for StreamableHTTP support. The /sse endpoint is maintained for backward compatibility.

OAuth Authentication: When OAUTH_ENABLED=true, the server supports multiple OAuth providers including OIDC-compliant providers (Okta, Google, Azure AD) for production use and HMAC mode for development/testing.

HTTPS Support: For production deployments, configure HTTPS by setting HTTPS_CERT_FILE and HTTPS_KEY_FILE environment variables. This is strongly recommended when using JWT authentication.