This document explains how to use JWE (JSON Web Encryption) authentication with the Altinity MCP Server to securely connect to ClickHouse® instances.

JWE authentication allows you to:

• Securely pass ClickHouse® connection parameters without exposing them in plain text
• Create per-request ClickHouse® connections with different parameters
• Support dynamic connection parameters rather than using a single global connection
• Implement token-based access control with expiration

The following CLI options are available for JWE authentication:

--allow-jwe-auth                  Enable JWE encryption for ClickHouse® connection
--jwe-secret-key string           Secret key for JWE token decryption
--jwt-secret-key string           Secret key for nested JWT signature verification (optional)

You can also set these options using environment variables:

MCP_ALLOW_JWE_AUTH=true
MCP_JWE_SECRET_KEY=jwe-encryption-secret
MCP_JWT_SECRET_KEY=jwt-signing-secret

To start the server with JWE authentication enabled:

./altinity-mcp --allow-jwe-auth --jwe-secret-key="your-jwe-secret" --jwt-secret-key="your-jwt-secret" --transport=sse

This will start the server with JWE authentication enabled, using the provided keys for token processing.

Then use the token generator tool to create JWE tokens:

go run cmd/jwe_auth/jwe_token_generator.go \
  --jwe-secret-key="your-jwe-encryption-secret" \
  --jwt-secret-key="your-jwt-signing-secret" \
  --host=clickhouse.example.com \
  --port=8123 \
  --database=my_database \
  --username=my_user \
  --password=my_password \
  --protocol=http \
  --expiry=3600

For TLS-enabled connections:

go run cmd/jwe_auth/jwe_token_generator.go \
  --jwe-secret-key="your-jwe-encryption-secret" \
  --jwt-secret-key="your-jwt-signing-secret" \
  --host=clickhouse.example.com \
  --port=9440 \
  --database=my_database \
  --username=my_user \
  --password=my_password \
  --protocol=tcp \
  --tls \
  --tls-ca-cert=/path/to/ca.crt \
  --tls-client-cert=/path/to/client.crt \
  --tls-client-key=/path/to/client.key \
  --expiry=3600

This will generate a signed with --jwt-secret-key JWT token containing the specified ClickHouse® connection parameters, valid for 1 hour (3600 seconds). And encrypt it with AES using --jwe-secret-key

To generate tokens without JWT signing (using JSON serialization instead), simply omit the --jwt-secret-key parameter:

go run cmd/jwe_auth/jwe_token_generator.go \
  --jwe-secret-key="your-jwe-encryption-secret" \
  --host=clickhouse.example.com \
  --port=8123 \
  --database=my_database \
  --username=my_user \
  --password=my_password \
  --protocol=http \
  --expiry=3600

The Altinity MCP server provides a /jwe-token-generator endpoint that allows you to generate JWE tokens dynamically. This is useful for integrations where you need to generate tokens on the fly without using the command-line tool.

To use this endpoint, you must have JWE authentication enabled on the server.

Endpoint: POST /jwe-token-generator

Request Body: A JSON object with the desired claims for the token. The claims are the same as the parameters for the CLI generator.

Example Request for HTTP:

curl -X POST http://localhost:8080/jwe-token-generator \
-H "Content-Type: application/json" \
-d '{
    "host": "clickhouse.example.com",
    "port": 8123,
    "database": "my_database",
    "username": "my_user",
    "password": "my_password",
    "protocol": "http",
    "expiry": 3600
}'

Example Request for HTTPS/TLS:

Protocol is always http but with TLS enabled we need to add a couple of tls params:

curl -X POST http://localhost:8080/jwe-token-generator \
-H "Content-Type: application/json" \
-d '{
    "host": "clickhouse.example.com",
    "port": 8443,
    "database": "my_database",
    "username": "my_user",
    "password": "my_password",
    "protocol": "http",
    "tls_enabled": true,
    "tls_insecure_skip_verify": false,
    "expiry": 3600
}'

Successful Response: A JSON object containing the generated token.

{
    "token": "eyJhbGciOiJBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIiwiY3R5IjoiSldUIiwidHlwIjoiSldFIn0. ..."
}

Error Responses:

• 403 Forbidden: If JWE authentication is not enabled on the server.
• 405 Method Not Allowed: If a method other than POST is used.
• 400 Bad Request: If the request body is not valid JSON.

The JWE token generation supports two modes:

1. JWT-signed tokens (when --jwt-secret-key is provided):

   • Claims are serialized to JSON and signed using HS256 algorithm
   • The signed JWT is then encrypted using JWE
   • Provides both encryption and signature verification

2. JSON-encrypted tokens (when --jwt-secret-key is omitted):

   • Claims are serialized directly to JSON
   • The JSON is then encrypted using JWE
   • Provides encryption without signature verification

The JWT token contains the following claims:

• host: ClickHouse® server hostname
• port: ClickHouse® server port
• database: ClickHouse® database name
• username: ClickHouse® username
• password: ClickHouse® password (optional)
• protocol: ClickHouse® connection protocol (http/tcp)
• tls_enabled: Boolean indicating if TLS is enabled (optional)
• tls_ca_cert: Path to CA certificate file (optional)
• tls_client_cert: Path to client certificate file (optional)
• tls_client_key: Path to client key file (optional)
• tls_insecure_skip_verify: Boolean to skip certificate verification (optional)
• exp: Token expiration timestamp

If using the SSE transport with dynamic paths:

http://localhost:8080/<generated-jwe-token>/sse

• Always use HTTPS when transmitting JWE tokens to prevent token interception
• Use a strong, random secret key for token signing
• Set appropriate token expiration times
• To implementing token revocation if needed for additional security, change using jwe-secret-key in altinity-mcp configuration