Skip to content

deployment.md

Latest commit

 

History

History
264 lines (214 loc) · 9.52 KB

deployment.md

File metadata and controls

264 lines (214 loc) · 9.52 KB

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.