Configuration Validation¶

MCP Gateway provides robust configuration validation tools to help operators catch misconfigurations early and ensure reliable deployments.

JSON Schema Export¶

Generate a machine-readable schema for all configuration options:

# Export schema to stdout
python -m mcpgateway.config --schema

# Save schema to file
python -m mcpgateway.config --schema > config.schema.json

Use this schema with validation tools in your deployment pipeline:

# Validate with ajv-cli
npx ajv-cli validate -s config.schema.json -d .env.json

# Validate with jsonschema (Python)
python -c "
import json, jsonschema
from mcpgateway.config import generate_settings_schema
schema = generate_settings_schema()
with open('.env.json') as f:
    jsonschema.validate(json.load(f), schema)
"

Environment File Validation¶

Validate your .env file before deployment:

# Validate default .env file
python -m mcpgateway.scripts.validate_env

# Validate specific file
python -m mcpgateway.scripts.validate_env .env.example

# Use in Makefile
make check-env

The validator checks for:

• Type validation: Ensures values match expected types (integers, URLs, enums)
• Security warnings: Detects weak passwords, default secrets, insecure configurations
• Range validation: Verifies ports, timeouts, and limits are within valid ranges
• Format validation: Validates URLs, email addresses, and structured data

Example Validation Output¶

Valid Configuration¶

$ python -m mcpgateway.scripts.validate_env .env.example
✅ .env validated successfully with no warnings.

Invalid Configuration¶

$ python -m mcpgateway.scripts.validate_env .env.invalid
❌ Invalid configuration: ValidationError
2 validation errors for Settings
port
  Input should be greater than 0 [type=greater_than, input=-1]
log_level
  Input should be 'DEBUG', 'INFO', 'WARNING', 'ERROR' or 'CRITICAL' [type=literal_error, input='INVALID']

Security Warnings¶

$ python -m mcpgateway.scripts.validate_env .env.dev
⚠️ Default admin password detected! Please change PLATFORM_ADMIN_PASSWORD immediately.
⚠️ JWT_SECRET_KEY: Default/weak secret detected! Please set a strong, unique value for production.
❌ Configuration has security warnings. Please address them for production use.

CI/CD Integration¶

Add validation to your deployment pipeline:

GitHub Actions¶

- name: Validate Configuration
  run: |
    python -m mcpgateway.scripts.validate_env .env.production
    if [ $? -ne 0 ]; then
      echo "Configuration validation failed"
      exit 1
    fi

Docker Build¶

COPY .env.example /app/.env
RUN python -m mcpgateway.scripts.validate_env /app/.env

Configuration Types¶

The following field types are strictly validated:

URLs and Endpoints¶

• APP_DOMAIN: Must be valid HTTP/HTTPS URL
• FEDERATION_PEERS: JSON array of valid URLs
• SSO_*_ISSUER: Valid OIDC issuer URLs

Enumerations¶

• LOG_LEVEL: DEBUG, INFO, WARNING, ERROR, CRITICAL
• CACHE_TYPE: memory, redis, database
• TRANSPORT_TYPE: http, ws, sse, all

Numeric Ranges¶

• PORT: 1-65535
• DB_POOL_SIZE: Positive integer
• TOKEN_EXPIRY: Positive integer (minutes)

Security Fields¶

• JWT_SECRET_KEY: SecretStr, minimum 32 characters
• AUTH_ENCRYPTION_SECRET: SecretStr, minimum 32 characters
• Password fields: Minimum 12 characters with complexity requirements

Best Practices¶

1. Validate Early: Run validation in development and CI before deployment
2. Use Strong Secrets: Generate cryptographically secure secrets for production
3. Environment-Specific Configs: Maintain separate .env files per environment
4. Schema Versioning: Pin schema versions in deployment scripts
5. Security Scanning: Regularly audit configurations for security issues

Troubleshooting¶

Common Validation Errors¶

Invalid Port Range

port: Input should be greater than 0 and less than 65536

Invalid URL Format

app_domain: Input should be a valid URL

Weak Secrets

JWT_SECRET_KEY: Secret should be at least 32 characters long
Admin password should be at least 8 characters long

Getting Help¶

• Use python -m mcpgateway.config --help for CLI options