Referenced Files in This Document

• src/config.ts
• src/cli/config.ts
• src/http/http-server-config.ts
• src/bootstrap.ts
• src/server.ts
• compose.yaml
• Dockerfile
• helm/kairos-mcp/values.yaml
• scripts/env/create-env.sh
• .devcontainer/devcontainer.json.base

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Environment Variables Reference
7. Configuration File Formats
8. Security Configuration
9. Feature Flags and Performance Tuning
10. Logging Configuration
11. Configuration Templates
12. Configuration Validation and Error Handling
13. Containerized Deployment
14. Troubleshooting Guide
15. Migration Strategies
16. Conclusion

Kairos MCP is a Model Context Protocol server that provides AI-powered development workflows and memory management capabilities. The application supports comprehensive environment configuration through multiple mechanisms including environment variables, configuration files, and container orchestration platforms. This document provides detailed guidance on configuring Kairos MCP for various deployment scenarios while maintaining security best practices and operational excellence.

The configuration system supports dynamic reloading, feature flags, performance tuning parameters, and secure authentication mechanisms including OIDC providers. It's designed to work seamlessly across development, staging, and production environments with appropriate security postures.

The Kairos MCP configuration system is distributed across multiple components:

graph TB
subgraph "Configuration Sources"
ENV[Environment Variables]
FILE[Config Files]
SECRETS[Secrets Management]
DEFAULTS[Default Values]
end
subgraph "Configuration Processing"
LOADER[Config Loader]
VALIDATOR[Config Validator]
RESOLVER[Config Resolver]
end
subgraph "Runtime Configuration"
SERVER[HTTP Server Config]
CLI[CLI Config]
SERVICES[Service Config]
AUTH[Auth Config]
end
ENV --> LOADER
FILE --> LOADER
SECRETS --> LOADER
DEFAULTS --> LOADER
LOADER --> VALIDATOR
VALIDATOR --> RESOLVER
RESOLVER --> SERVER
RESOLVER --> CLI
RESOLVER --> SERVICES
RESOLVER --> AUTH

Diagram sources

• src/config.ts:1-50
• src/bootstrap.ts:1-30

Section sources

• src/config.ts:1-100
• src/bootstrap.ts:1-50

The configuration system consists of several key components that work together to provide a robust and flexible configuration management solution:

Responsible for loading configuration from multiple sources with proper precedence handling.

Ensures all required configuration values are present and valid before application startup.

Handles runtime configuration updates and hot-reloading capabilities.

Manages sensitive configuration including secrets, certificates, and authentication settings.

Section sources

• src/config.ts:50-150
• src/cli/config.ts:1-100

The Kairos MCP configuration architecture follows a layered approach with clear separation of concerns:

sequenceDiagram
participant App as Application
participant Loader as Config Loader
participant Validator as Config Validator
participant Resolver as Config Resolver
participant Services as Runtime Services
App->>Loader : Initialize Configuration
Loader->>Loader : Load Environment Variables
Loader->>Loader : Load Config Files
Loader->>Loader : Load Secrets
Loader->>Validator : Validate Configuration
Validator-->>Loader : Validation Result
Loader->>Resolver : Resolve Final Configuration
Resolver-->>App : Complete Configuration
App->>Services : Configure Services
Services-->>App : Ready

Diagram sources

• src/bootstrap.ts:20-80
• src/config.ts:100-200

The HTTP server configuration manages network interfaces, TLS settings, CORS policies, and API endpoints.

The CLI configuration handles command-line argument parsing, local development settings, and user preferences.

Service-specific configurations for database connections, caching layers, and external service integrations.

OIDC provider settings, session management, and security policies.

Section sources

• src/http/http-server-config.ts:1-100
• src/cli/config.ts:50-150

Section sources

• src/config.ts:150-300
• src/http/http-server-config.ts:50-150

Kairos MCP supports YAML configuration files for structured configuration management:

# kairos.config.yaml
app:
  name: "kairos-mcp"
  environment: "production"
  port: 3000
  
database:
  connection_string: "${DB_CONNECTION_STRING}"
  pool_size: 20
  ssl_mode: "require"

redis:
  url: "${REDIS_URL}"
  max_retries: 5

oidc:
  issuer: "${OIDC_ISSUER}"
  client_id: "${OIDC_CLIENT_ID}"
  client_secret: "${OIDC_CLIENT_SECRET}"
  scopes: "openid profile email"
  
logging:
  level: "info"
  format: "json"
  output: "stdout"

Alternative JSON format support for environments preferring JSON:

{
  "app": {
    "name": "kairos-mcp",
    "environment": "production",
    "port": 3000
  },
  "database": {
    "connection_string": "${DB_CONNECTION_STRING}",
    "pool_size": 20
  }
}

Configuration values are resolved in the following order (highest precedence first):

1. Command-line arguments
2. Environment variables
3. Configuration files (YAML/JSON)
4. Default values

Section sources

• src/config.ts:200-350
• src/cli/config.ts:100-200

Configure OIDC authentication for enterprise identity management:

# Keycloak Configuration
export OIDC_ISSUER="https://keycloak.example.com/realms/kairos"
export OIDC_CLIENT_ID="kairos-mcp-client"
export OIDC_CLIENT_SECRET="${KEYCLOAK_CLIENT_SECRET}"
export OIDC_SCOPES="openid profile email groups"
export OIDC_ADMIN_GROUPS="kairos-admins,kairos-developers"
export OIDC_USER_GROUPS="kairos-users"

# Google OAuth Configuration
export OIDC_ISSUER="https://accounts.google.com"
export OIDC_CLIENT_ID="${GOOGLE_CLIENT_ID}"
export OIDC_CLIENT_SECRET="${GOOGLE_CLIENT_SECRET}"
export OIDC_SCOPES="openid email profile"

# SSL-enabled Database Connection
export DB_CONNECTION_STRING="postgresql://user:password@host:5432/dbname?sslmode=require&sslcert=/path/to/client.crt&sslkey=/path/to/client.key&sslrootcert=/path/to/ca.crt"
export DB_SSL_MODE="verify-full"

# Secure Connection Pool Settings
export DB_POOL_SIZE=20
export DB_SSL_MODE="require"

# JWT Token Settings
export JWT_SECRET="${JWT_SECRET}"
export JWT_EXPIRY="24h"
export JWT_REFRESH_EXPIRY="7d"

# API Rate Limiting
export RATE_LIMIT_WINDOW_MS=900000
export RATE_LIMIT_MAX_REQUESTS=1000
export RATE_LIMIT_BAN_DURATION_MS=3600000

Section sources

• src/http/http-auth-middleware.ts:1-100
• src/services/oidc-state-store.ts:1-100

Feature flags enable gradual rollout of new functionality and A/B testing:

# Enable New Memory System
export FEATURE_NEW_MEMORY_SYSTEM=true

# Enable Experimental Tools
export FEATURE_EXPERIMENTAL_TOOLS=false

# Enable Metrics Export
export FEATURE_METRICS_EXPORT=true

# Enable Debug Endpoints (Development Only)
export FEATURE_DEBUG_ENDPOINTS=false

# Multi-threaded Processing
export WORKER_THREADS=4
export MAX_CONCURRENT_REQUESTS=200
export REQUEST_TIMEOUT_MS=60000

# Cache Configuration
export CACHE_TTL_SECONDS=3600
export CACHE_MAX_SIZE_MB=512
export CACHE_BACKEND="redis"

# Embedding Optimization
export EMBEDDING_BATCH_SIZE=20
export EMBEDDING_MODEL="text-embedding-3-large"
export EMBEDDING_TIMEOUT_MS=30000

Section sources

• src/config.ts:300-450
• src/services/embedding/config.ts:1-100

# Production Logging
export LOG_LEVEL="warn"
export LOG_FORMAT="json"
export LOG_OUTPUT="stdout"

# Development Logging
export LOG_LEVEL="debug"
export LOG_FORMAT="text"
export LOG_OUTPUT="stdout"

Kairos MCP uses structured logging for better observability:

{
  "timestamp": "2024-01-01T00:00:00Z",
  "level": "info",
  "message": "Server started",
  "service": "kairos-mcp",
  "version": "1.0.0",
  "environment": "production",
  "pid": 1234,
  "request_id": "abc-123-def"
}

# Log File Configuration
export LOG_OUTPUT="file"
export LOG_FILE_PATH="/var/log/kairos-mcp/app.log"
export LOG_MAX_SIZE_MB=100
export LOG_MAX_FILES=10

Section sources

• src/utils/structured-logger.ts:1-100
• src/utils/log-core.ts:1-100

# .env.development
APP_ENV=development
APP_PORT=3000
APP_HOST=localhost

DB_CONNECTION_STRING="postgresql://postgres:postgres@localhost:5432/kairos_dev"
DB_SSL_MODE=disable
DB_POOL_SIZE=5

REDIS_URL=redis://localhost:6379

OIDC_ISSUER=http://localhost:8080/realms/kairos-dev
OIDC_CLIENT_ID=kairos-mcp-dev
OIDC_CLIENT_SECRET=dev-secret

LOG_LEVEL=debug
LOG_FORMAT=text
FEATURE_DEBUG_ENDPOINTS=true

# .env.staging
APP_ENV=staging
APP_PORT=3000
APP_HOST=0.0.0.0

DB_CONNECTION_STRING="postgresql://${STAGING_DB_USER}:${STAGING_DB_PASS}@${STAGING_DB_HOST}:5432/kairos_staging"
DB_SSL_MODE=require
DB_POOL_SIZE=10

REDIS_URL=redis://${STAGING_REDIS_HOST}:6379
REDIS_PASSWORD=${STAGING_REDIS_PASSWORD}

OIDC_ISSUER=https://keycloak-staging.example.com/realms/kairos
OIDC_CLIENT_ID=kairos-mcp-staging
OIDC_CLIENT_SECRET=${STAGING_OIDC_CLIENT_SECRET}

LOG_LEVEL=info
LOG_FORMAT=json

# .env.production
APP_ENV=production
APP_PORT=3000
APP_HOST=0.0.0.0

DB_CONNECTION_STRING="postgresql://${PROD_DB_USER}:${PROD_DB_PASS}@${PROD_DB_HOST}:5432/kairos_prod?sslmode=verify-full"
DB_SSL_MODE=verify-full
DB_POOL_SIZE=20

REDIS_URL=redis://${PROD_REDIS_HOST}:6379
REDIS_PASSWORD=${PROD_REDIS_PASSWORD}

OIDC_ISSUER=https://keycloak-prod.example.com/realms/kairos
OIDC_CLIENT_ID=kairos-mcp-prod
OIDC_CLIENT_SECRET=${PROD_OIDC_CLIENT_SECRET}
OIDC_ADMIN_GROUPS="kairos-admins"
OIDC_USER_GROUPS="kairos-users"

LOG_LEVEL=warn
LOG_FORMAT=json
FEATURE_DEBUG_ENDPOINTS=false

Section sources

• scripts/env/create-env.sh:1-100
• .devcontainer/devcontainer.json.base:1-50

The configuration system implements comprehensive validation:

flowchart TD
Start([Configuration Load]) --> Parse["Parse Configuration"]
Parse --> ValidateRequired["Validate Required Fields"]
ValidateRequired --> RequiredValid{"All Required Fields Present?"}
RequiredValid --> |No| ErrorMissing["Error: Missing Required Configuration"]
RequiredValid --> |Yes| ValidateTypes["Validate Data Types"]
ValidateTypes --> TypesValid{"Types Valid?"}
TypesValid --> |No| ErrorTypes["Error: Invalid Configuration Types"]
TypesValid --> |Yes| ValidateValues["Validate Value Ranges"]
ValidateValues --> ValuesValid{"Values Valid?"}
ValuesValid --> |No| ErrorRanges["Error: Invalid Configuration Values"]
ValuesValid --> |Yes| ValidateDependencies["Validate Dependencies"]
ValidateDependencies --> DepsValid{"Dependencies Satisfied?"}
DepsValid --> |No| ErrorDeps["Error: Missing Dependencies"]
DepsValid --> |Yes| Success["Configuration Valid"]
ErrorMissing --> Exit([Exit with Error])
ErrorTypes --> Exit
ErrorRanges --> Exit
ErrorDeps --> Exit
Success --> Exit

Diagram sources

• src/config.ts:350-500

Configuration errors are handled gracefully with informative messages:

• Missing Required Configuration: Clear indication of which variables are missing
• Invalid Data Types: Specific type requirements and examples
• Value Range Violations: Allowed ranges and default fallbacks
• Dependency Errors: Guidance on resolving configuration dependencies

Section sources

• src/config.ts:450-600

# Dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

ENV NODE_ENV=production
ENV APP_PORT=3000
ENV LOG_LEVEL=warn

EXPOSE 3000

CMD ["node", "dist/index.js"]

# compose.yaml
version: '3.8'

services:
  kairos-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - APP_ENV=production
      - DB_CONNECTION_STRING=postgresql://postgres:postgres@db:5432/kairos
      - REDIS_URL=redis://redis:6379
      - OIDC_ISSUER=https://keycloak:8080/realms/kairos
    depends_on:
      - db
      - redis
      - keycloak

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=kairos
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

  keycloak:
    image: quay.io/keycloak/keycloak:23.0
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=admin
    command: start-dev

# helm/kairos-mcp/values.yaml
replicaCount: 2

image:
  repository: kairos/mcp
  tag: latest
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 3000

resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 500m
    memory: 512Mi

env:
  APP_ENV: production
  LOG_LEVEL: warn
  FEATURE_DEBUG_ENDPOINTS: "false"

secrets:
  DB_CONNECTION_STRING:
    valueFrom:
      secretKeyRef:
        name: kairos-secrets
        key: db-connection-string
  OIDC_CLIENT_SECRET:
    valueFrom:
      secretKeyRef:
        name: kairos-secrets
        key: oidc-client-secret

Section sources

• compose.yaml:1-100
• Dockerfile:1-50
• helm/kairos-mcp/values.yaml:1-100

Symptoms: Connection timeouts, authentication failures Solutions:

• Verify connection string format
• Check database credentials
• Ensure network connectivity
• Validate SSL certificate paths

Symptoms: Login redirects, token validation errors Solutions:

• Verify OIDC issuer URL
• Check client ID and secret
• Validate redirect URIs
• Review scope permissions

Symptoms: Cache misses, session loss Solutions:

• Verify Redis URL and authentication
• Check Redis availability
• Validate cluster configuration
• Review network policies

# Validate configuration
npm run config:validate

# Test database connection
npm run config:test-db

# Test OIDC configuration
npm run config:test-oidc

# Test Redis connection
npm run config:test-redis

Enable debug logging for troubleshooting:

export LOG_LEVEL=debug
export FEATURE_DEBUG_ENDPOINTS=true

Section sources

• src/config.ts:500-650

When updating configuration schemas, follow these migration strategies:

• Maintain support for deprecated configuration keys
• Provide migration scripts for automated updates
• Use graceful degradation for missing optional fields

# kairos.config.v2.yaml
version: "2.0"
app:
  name: "kairos-mcp"
  environment: "production"

• Keep previous configuration versions available
• Implement configuration backup and restore
• Test configuration changes in staging before production

# Rotate database credentials
./scripts/rotate-secrets.sh --type database --new-password $(openssl rand -base64 32)

# Rotate OIDC client secrets
./scripts/rotate-secrets.sh --type oidc --client-id kairos-mcp-prod

# Rotate encryption keys
./scripts/rotate-secrets.sh --type encryption --algorithm aes-256-gcm

Section sources

• scripts/env/create-env.sh:50-150

Kairos MCP provides a comprehensive and flexible configuration system that supports diverse deployment scenarios while maintaining security and operational excellence. The multi-layered configuration approach ensures reliability through validation, error handling, and rollback capabilities.

Key benefits include:

• Flexibility: Multiple configuration sources with clear precedence rules
• Security: Comprehensive security configuration for OIDC, databases, and APIs
• Scalability: Performance tuning parameters for various workload sizes
• Observability: Structured logging and monitoring integration
• Reliability: Robust validation and error handling
• Portability: Support for containerized and orchestrated deployments

By following the guidelines and templates provided in this document, you can deploy Kairos MCP securely and efficiently across development, staging, and production environments.