IBM i MCP Server

# ============================================================================= # IBM i MCP Server - Environment Configuration # ============================================================================= # Copy this file to .env and configure with your settings: # cp .env.example .env # # See full documentation: https://github.com/IBM/ibmi-mcp-server#configuration # ============================================================================= # ----------------------------------------------------------------------------- # 🗄️ IBM i Database Connection # ----------------------------------------------------------------------------- # Required for SQL tools to connect to IBM i Db2 for i via Mapepire # IBM i system hostname or IP address (REQUIRED) DB2i_HOST= # IBM i user profile for database connections (REQUIRED) DB2i_USER= # Password for IBM i user profile (REQUIRED) DB2i_PASS= # Mapepire daemon/gateway port # Default: 8076 DB2i_PORT=8076 # Skip TLS certificate verification (for self-signed certs) # Default: true # ⚠️ SECURITY: Set to false in production with valid SSL certificates DB2i_IGNORE_UNAUTHORIZED=true # ----------------------------------------------------------------------------- # 🧩 YAML Tool Configuration # ----------------------------------------------------------------------------- # Path to YAML tool configurations (file, directory, or glob pattern) # Examples: # - File: tools/performance.yaml # - Directory: tools/ (loads all .yaml/.yml files) # - Glob: tools/**/*.yaml # Default: none (no tools loaded) TOOLS_YAML_PATH=tools # Comma-separated list of toolsets to load (filters available tools) # Leave empty to load all tools # Example: performance,monitoring,diagnostics # Default: none (load all) SELECTED_TOOLSETS= # Automatically reload tools when YAML files change # Default: true YAML_AUTO_RELOAD=true # --- Configuration Merging (when loading multiple YAML files) --- # Merge arrays from multiple files (true) or replace them (false) # Default: false YAML_MERGE_ARRAYS=false # Allow duplicate tool names across files # Default: false YAML_ALLOW_DUPLICATE_TOOLS=false # Allow duplicate source names across files # Default: false YAML_ALLOW_DUPLICATE_SOURCES=false # Validate merged configuration before loading tools # Default: true YAML_VALIDATE_MERGED=true # ----------------------------------------------------------------------------- # 🖥️ MCP Server Settings # ----------------------------------------------------------------------------- # Core server configuration # Server name identifier (optional, defaults to package name) # MCP_SERVER_NAME=ibmi-mcp-server # Server version (optional, defaults to package version) # MCP_SERVER_VERSION=1.9.1 # Transport protocol: "stdio" (local) or "http" (remote) # Default: stdio MCP_TRANSPORT_TYPE=http # Logging verbosity: "error", "warn", "info", "debug" # Default: debug MCP_LOG_LEVEL=debug # Directory for log files (relative to project root) # Default: logs LOGS_DIR=logs # Node environment: "development", "production", "test" # Default: development NODE_ENV=development # ----------------------------------------------------------------------------- # 🌐 HTTP Transport Settings # ----------------------------------------------------------------------------- # Only used when MCP_TRANSPORT_TYPE=http # HTTP server port # Default: 3010 MCP_HTTP_PORT=3010 # HTTP server bind address # Default: 127.0.0.1 (localhost only) # Use 0.0.0.0 to listen on all interfaces MCP_HTTP_HOST=127.0.0.1 # MCP endpoint path # Default: /mcp MCP_HTTP_ENDPOINT_PATH=/mcp # Session mode: "stateless", "stateful", or "auto" # - auto: Automatically detects client capabilities (recommended) # - stateful: Maintains persistent sessions with connection state # - stateless: Each request is independent # Default: auto MCP_SESSION_MODE=auto # Timeout for idle stateful sessions (milliseconds) # Default: 1800000 (30 minutes) MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS=1800000 # Max attempts to find available port if default is in use # Default: 15 MCP_HTTP_MAX_PORT_RETRIES=15 # Delay between port retry attempts (milliseconds) # Default: 50 MCP_HTTP_PORT_RETRY_DELAY_MS=50 # Comma-separated CORS allowed origins (leave empty to block all origins) # Example: http://localhost:3000,https://app.example.com MCP_ALLOWED_ORIGINS= # ----------------------------------------------------------------------------- # 🔐 Authentication & Authorization # ----------------------------------------------------------------------------- # Authentication mode: "none", "jwt", "oauth", "ibmi" # Default: none # ⚠️ IMPORTANT: Use "none" only in development environments MCP_AUTH_MODE=none # --- JWT Authentication --- # Required when MCP_AUTH_MODE=jwt # Secret key for signing/verifying JWT tokens (minimum 32 characters) # MCP_AUTH_SECRET_KEY=your-very-secret-key-at-least-32-characters-long # --- OAuth Authentication --- # Required when MCP_AUTH_MODE=oauth # OAUTH_ISSUER_URL=https://auth.example.com # OAUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json # OAUTH_AUDIENCE=https://api.example.com/mcp # --- IBM i HTTP Authentication --- # Required when MCP_AUTH_MODE=ibmi # Enable IBM i authentication endpoints (required for ibmi mode) # Default: false IBMI_HTTP_AUTH_ENABLED=false # Allow HTTP (non-HTTPS) authentication requests # Default: false # ⚠️ SECURITY: Set to false in production (requires HTTPS) IBMI_AUTH_ALLOW_HTTP=false # Token lifetime in seconds # Default: 3600 (1 hour) IBMI_AUTH_TOKEN_EXPIRY_SECONDS=3600 # How often to clean up expired tokens (seconds) # Default: 300 (5 minutes) IBMI_AUTH_CLEANUP_INTERVAL_SECONDS=300 # Maximum concurrent authenticated sessions # Default: 100 IBMI_AUTH_MAX_CONCURRENT_SESSIONS=100 # RSA key configuration for IBM i authentication # Generate keys with: # mkdir -p secrets # openssl genpkey -algorithm RSA -out secrets/private.pem -pkeyopt rsa_keygen_bits:2048 # openssl rsa -pubout -in secrets/private.pem -out secrets/public.pem IBMI_AUTH_KEY_ID=development IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem # ----------------------------------------------------------------------------- # 📊 OpenTelemetry (Observability) # ----------------------------------------------------------------------------- # Distributed tracing and metrics using OpenTelemetry # Enable OpenTelemetry instrumentation # Default: false OTEL_ENABLED=false # Service name for telemetry data # Default: MCP_SERVER_NAME or package name # OTEL_SERVICE_NAME=ibmi-mcp-server # Service version for telemetry data # Default: MCP_SERVER_VERSION or package version # OTEL_SERVICE_VERSION=1.9.1 # OTLP endpoint for trace export # Default: none (logs to file) # Examples: # - Jaeger: http://jaeger:4318/v1/traces # - Cloud: https://otlp.example.com/v1/traces # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT= # OTLP endpoint for metrics export # Default: none (not exported) # OTEL_EXPORTER_OTLP_METRICS_ENDPOINT= # Trace sampling ratio (0.0 to 1.0, where 1.0 = sample all traces) # Default: 1.0 (100%) OTEL_TRACES_SAMPLER_ARG=1.0 # OpenTelemetry internal diagnostic log level # Options: NONE, ERROR, WARN, INFO, DEBUG, VERBOSE, ALL # Default: INFO OTEL_LOG_LEVEL=INFO # ----------------------------------------------------------------------------- # 🤖 LLM Provider Integration (Optional) # ----------------------------------------------------------------------------- # --- OpenRouter --- # API key for OpenRouter.ai service OPENROUTER_API_KEY= # Application URL for OpenRouter dashboard # Default: http://localhost:3000 OPENROUTER_APP_URL=http://localhost:3000 # Application name for OpenRouter identification # Default: package name OPENROUTER_APP_NAME=ibmi-mcp-server # --- LLM Defaults --- # Default parameters for LLM requests (applied when not specified) # Default model identifier # Default: google/gemini-2.5-flash LLM_DEFAULT_MODEL=google/gemini-2.5-flash # Sampling temperature (randomness): 0.0 (deterministic) to 2.0 (creative) # Default: none (provider default) LLM_DEFAULT_TEMPERATURE=0.7 # Nucleus sampling threshold: 0.0 to 1.0 # Default: none (provider default) # LLM_DEFAULT_TOP_P=0.9 # Maximum tokens in response # Default: none (provider default) # LLM_DEFAULT_MAX_TOKENS=2000 # Top-K sampling (number of candidates) # Default: none (provider default) # LLM_DEFAULT_TOP_K=40 # Minimum probability threshold: 0.0 to 1.0 # Default: none (provider default) # LLM_DEFAULT_MIN_P=0.05 # ----------------------------------------------------------------------------- # 🔌 OAuth Proxy (Advanced - Optional) # ----------------------------------------------------------------------------- # OAuth proxy endpoints for advanced integration scenarios # Most users should use standard OAuth authentication via MCP_AUTH_MODE=oauth # OAUTH_PROXY_AUTHORIZATION_URL=https://auth.example.com/oauth/authorize # OAUTH_PROXY_TOKEN_URL=https://auth.example.com/oauth/token # OAUTH_PROXY_REVOCATION_URL=https://auth.example.com/oauth/revoke # OAUTH_PROXY_ISSUER_URL=https://auth.example.com # OAUTH_PROXY_SERVICE_DOCUMENTATION_URL=https://docs.example.com/oauth # OAUTH_PROXY_DEFAULT_CLIENT_REDIRECT_URIS=http://localhost:3000/callback # ----------------------------------------------------------------------------- # 💾 Additional Database Integrations (Optional) # ----------------------------------------------------------------------------- # --- Supabase --- # Uncomment to enable Supabase integration # SUPABASE_URL=https://your-project.supabase.co # SUPABASE_ANON_KEY=your-anon-key # SUPABASE_SERVICE_ROLE_KEY=your-service-role-key # ============================================================================= # Quick Start Examples # ============================================================================= # --- Development Configuration --- # MCP_TRANSPORT_TYPE=http # MCP_HTTP_PORT=3010 # MCP_SESSION_MODE=auto # MCP_LOG_LEVEL=debug # MCP_AUTH_MODE=none # NODE_ENV=development # # DB2i_HOST=ibmi-dev.local # DB2i_USER=DEVUSER # DB2i_PASS=devpass # DB2i_IGNORE_UNAUTHORIZED=true # # TOOLS_YAML_PATH=tools/ # YAML_AUTO_RELOAD=true # OTEL_ENABLED=true # --- Production Configuration --- # MCP_TRANSPORT_TYPE=http # MCP_HTTP_PORT=3010 # MCP_SESSION_MODE=auto # MCP_LOG_LEVEL=warn # MCP_AUTH_MODE=ibmi # NODE_ENV=production # # DB2i_HOST=ibmi-prod.example.com # DB2i_USER=PRODUSER # DB2i_PASS=${SECURE_PASSWORD_FROM_VAULT} # DB2i_IGNORE_UNAUTHORIZED=false # # TOOLS_YAML_PATH=/opt/mcp-tools/production.yaml # YAML_AUTO_RELOAD=false # # IBMI_HTTP_AUTH_ENABLED=true # IBMI_AUTH_ALLOW_HTTP=false # IBMI_AUTH_PRIVATE_KEY_PATH=/opt/secrets/private.pem # IBMI_AUTH_PUBLIC_KEY_PATH=/opt/secrets/public.pem # # OTEL_ENABLED=true # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.example.com/v1/traces # ============================================================================= # Security Checklist # ============================================================================= # ✅ Never commit .env files to version control # ✅ Use secrets management in production (Vault, AWS Secrets Manager, etc.) # ✅ Rotate credentials and keys regularly # ✅ Use HTTPS/TLS in production (IBMI_AUTH_ALLOW_HTTP=false) # ✅ Enable authentication (MCP_AUTH_MODE != none) # ✅ Use strong passwords (12+ characters, mixed case, numbers, symbols) # ✅ Restrict MCP_ALLOWED_ORIGINS to known domains # ✅ Set appropriate IBMI_AUTH_MAX_CONCURRENT_SESSIONS limits # =============================================================================