Configuration

MCPulse can be configured through multiple methods. Configuration is loaded in the following order of precedence (highest to lowest):

1. Command-line flags
2. Environment variables (prefixed with MCPULSE_)
3. Configuration file (config.yaml)
4. Default values

Configuration File

Create a config.yaml file in your working directory or specify its location with the --config flag.

Complete Example

server:
  host: "0.0.0.0"
  port: 8080
  grpc_port: 9090
  read_timeout: "30s"
  write_timeout: "30s"
  idle_timeout: "120s"

database:
  type: "timescaledb"
  host: "localhost"
  port: 5432
  database: "mcp_analytics"
  username: "mcp_user"
  password: "changeme"
  max_connections: 50
  max_idle_connections: 10
  connection_max_lifetime: "1h"
  migrations_path: "migrations"
  retention:
    raw_data: "90d"
    hourly_aggregates: "1y"
    daily_aggregates: "forever"

ingestion:
  buffer_size: 10000
  batch_size: 1000
  batch_timeout: "5s"
  max_batch_wait: "10s"
  rate_limit:
    enabled: true
    requests_per_second: 1000
    burst: 2000

auth:
  jwt_secret: "your-secret-key-here-at-least-32-chars"
  access_token_ttl: "15m"
  refresh_token_ttl: "7d"

privacy:
  sanitize_parameters: true
  sensitive_keys:
    - "password"
    - "token"
    - "api_key"
    - "secret"
    - "authorization"
    - "auth"
  hash_session_ids: false

monitoring:
  prometheus:
    enabled: true
    path: "/metrics"
  health_check:
    enabled: true
    path: "/health"

logging:
  level: "info"
  format: "json"
  output: "stdout"

Server Configuration

Configure the HTTP and gRPC servers:

server:
  # Bind address (0.0.0.0 for all interfaces)
  host: "0.0.0.0"

  # HTTP server port
  port: 8080

  # gRPC server port
  grpc_port: 9090

  # Timeout for reading request
  read_timeout: "30s"

  # Timeout for writing response
  write_timeout: "30s"

  # Timeout for idle connections
  idle_timeout: "120s"

Environment Variables

export MCPULSE_SERVER_HOST="0.0.0.0"
export MCPULSE_SERVER_PORT="8080"
export MCPULSE_SERVER_GRPC_PORT="9090"

Database Configuration

Configure TimescaleDB connection and behavior:

database:
  # Database type (currently only timescaledb)
  type: "timescaledb"

  # Connection details
  host: "localhost"
  port: 5432
  database: "mcp_analytics"
  username: "mcp_user"
  password: "changeme"

  # Connection pool
  max_connections: 50
  max_idle_connections: 10
  connection_max_lifetime: "1h"

  # Migrations
  migrations_path: "migrations"

  # Data retention
  retention:
    raw_data: "90d"           # Raw metrics
    hourly_aggregates: "1y"   # Hourly rollups
    daily_aggregates: "forever" # Daily rollups

Environment Variables

export MCPULSE_DATABASE_HOST="localhost"
export MCPULSE_DATABASE_PORT="5432"
export MCPULSE_DATABASE_DATABASE="mcp_analytics"
export MCPULSE_DATABASE_USERNAME="mcp_user"
export MCPULSE_DATABASE_PASSWORD="changeme"

Retention Policies

Control how long data is kept:

• Raw data: Individual metric events. Default: 90 days
• Hourly aggregates: Pre-computed hourly summaries. Default: 1 year
• Daily aggregates: Pre-computed daily summaries. Default: forever

Examples:

retention:
  raw_data: "30d"      # 30 days
  raw_data: "90d"      # 90 days (default)
  raw_data: "1y"       # 1 year
  raw_data: "forever"  # Never delete

Ingestion Configuration

Configure metric ingestion and buffering:

ingestion:
  # Buffer size for incoming metrics
  buffer_size: 10000

  # Maximum metrics per batch write
  batch_size: 1000

  # Time to wait before flushing incomplete batch
  batch_timeout: "5s"

  # Maximum time to wait for batch to fill
  max_batch_wait: "10s"

  # Rate limiting
  rate_limit:
    enabled: true
    requests_per_second: 1000
    burst: 2000

Tuning for Performance

High throughput (10,000+ events/sec):

ingestion:
  buffer_size: 50000
  batch_size: 5000
  batch_timeout: "10s"

Low latency (fast writes):

ingestion:
  buffer_size: 1000
  batch_size: 100
  batch_timeout: "1s"

Memory constrained:

ingestion:
  buffer_size: 1000
  batch_size: 500
  batch_timeout: "5s"

Authentication Configuration

Configure JWT-based authentication and API keys:

auth:
  # JWT secret (must be at least 32 characters)
  jwt_secret: "your-secret-key-here-at-least-32-chars"

  # Access token lifetime
  access_token_ttl: "15m"

  # Refresh token lifetime
  refresh_token_ttl: "7d"

Environment Variables

export MCPULSE_AUTH_JWT_SECRET="your-secret-key"
export MCPULSE_AUTH_ACCESS_TOKEN_TTL="15m"
export MCPULSE_AUTH_REFRESH_TOKEN_TTL="7d"

Privacy Configuration

Control parameter sanitization and privacy:

privacy:
  # Enable automatic parameter sanitization
  sanitize_parameters: true

  # Keys to redact from parameters
  sensitive_keys:
    - "password"
    - "token"
    - "api_key"
    - "secret"
    - "authorization"
    - "auth"
    - "apiKey"
    - "accessToken"
    - "privateKey"

  # Hash session IDs before storing
  hash_session_ids: false

How Sanitization Works

When enabled, any parameter with a key matching sensitive_keys will be redacted:

Before sanitization:

{
  "username": "john",
  "password": "secret123",
  "api_key": "sk_live_abc123"
}

After sanitization:

{
  "username": "john",
  "password": "[REDACTED]",
  "api_key": "[REDACTED]"
}

Monitoring Configuration

Configure Prometheus metrics and health checks:

monitoring:
  prometheus:
    enabled: true
    path: "/metrics"
  health_check:
    enabled: true
    path: "/health"

Prometheus Metrics

When enabled, metrics are exposed at http://localhost:8081/metrics:

• mcpulse_ingestion_total - Total metrics ingested
• mcpulse_ingestion_errors_total - Ingestion errors
• mcpulse_db_connections - Database connection pool stats
• mcpulse_http_requests_total - HTTP request counts
• mcpulse_http_request_duration_seconds - Request latencies

Health Check

Health check endpoint returns:

{
  "status": "healthy",
  "database": "connected",
  "version": "1.0.0",
  "uptime": "24h30m"
}

Logging Configuration

Configure logging output and level:

logging:
  # Log level: debug, info, warn, error
  level: "info"

  # Format: json or console
  format: "json"

  # Output: stdout, stderr, or file path
  output: "stdout"

Log Levels

• debug: Verbose logging for development
• info: Standard operational information
• warn: Warning messages
• error: Error messages only

Log Formats

JSON (production):

{"level":"info","ts":"2025-10-10T10:30:00Z","msg":"server started","port":8080}

Console (development):

2025-10-10T10:30:00Z INFO server started port=8080

Environment Variables

export MCPULSE_LOGGING_LEVEL="info"
export MCPULSE_LOGGING_FORMAT="json"
export MCPULSE_LOGGING_OUTPUT="stdout"

Features Configuration

Enable or disable experimental features:

features:
  # WebSocket support for real-time updates
  websocket: true

  # Automatic anomaly detection (experimental)
  anomaly_detection: false

  # Alerting system (experimental)
  alerting: false

  # Multi-tenancy support (experimental)
  multi_tenancy: false

Command-Line Flags

Override configuration with command-line flags:

mcpulse \
  --config /path/to/config.yaml \
  --server.port 9000 \
  --database.host db.example.com \
  --logging.level debug

Environment Variable Reference

All configuration options can be set via environment variables with the MCPULSE_ prefix:

Config Path	Environment Variable
server.host	MCPULSE_SERVER_HOST
server.port	MCPULSE_SERVER_PORT
database.host	MCPULSE_DATABASE_HOST
database.password	MCPULSE_DATABASE_PASSWORD
auth.jwt_secret	MCPULSE_AUTH_JWT_SECRET
logging.level	MCPULSE_LOGGING_LEVEL

Validation

Validate your configuration:

mcpulse config validate --config config.yaml

This will check for:

• Required fields
• Valid values
• Type correctness
• Security issues (weak secrets, etc.)

Example Configurations

Development

server:
  port: 8080
database:
  host: "localhost"
  password: "dev"
logging:
  level: "debug"
  format: "console"
privacy:
  sanitize_parameters: false

Next Steps

• Integrate an SDK
• View installation guide