# 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)

   ```bash
   # 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)

   ```bash
   # 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:

```http
Authorization: Bearer <your-jwt-token>
```

For detailed OAuth configuration, deployment examples, and browser-based MCP client compatibility lessons learned, see [oauth.md](https://docs.tuannvm.com/mcp-trino/docs/oauth).

## HTTPS Support

For production deployments with authentication, HTTPS is strongly recommended:

```bash
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

```bash
# 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:**

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

**Load Balancer/Proxy Configuration:**

```nginx
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:

```dockerfile
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"]
```

```bash
# 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):**

```bash
# 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):**

```bash
# 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:**

```json
{
  "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.