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 protocolLegacy support: Maintains
/sse
endpoint for backward compatibility with SSESupports 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:
OIDC Provider Mode (Production - Recommended)
# Configure with OAuth provider (Okta example) export TRINO_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
HMAC Mode (Development/Testing)
# Simple JWT with shared secret export TRINO_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 TRINO_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 TRINO_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 TRINO_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 variableTokens 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
) validationUse established OAuth 2.1/OpenID Connect providers
Implement token revocation mechanisms
Quick Start with OAuth
For Production (OIDC):
# Configure OAuth provider
export TRINO_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 TRINO_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
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
TRINO_OAUTH_ENABLED
Enable OAuth authentication (auto-enabled when OAUTH_PROVIDER is set)
false
OAUTH_PROVIDER
OAuth provider (hmac/okta/google/azure) - setting this enables OAuth
(empty)
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
TRINO_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
andHTTPS_KEY_FILE
environment variables. This is strongly recommended when using JWT authentication.
Last updated
Was this helpful?