env.example

# ========================================
# LogicMonitor MCP Server Configuration
# ========================================
# Copy this file to .env and update with your actual values
# Environment variables take precedence over CLI flags
#
# Quick Start (Minimum Required):
#   LM_COMPANY=mycompany
#   LM_BEARER_TOKEN=your-lm-api-token
#   MCP_TRANSPORT=stdio  (default - for Claude Desktop)
#
# For remote servers (SSE/HTTP), optionally set:
#   MCP_BEARER_TOKEN=your-server-auth-token  (simple authentication)
#   OR configure OAUTH_* variables            (enterprise authentication)
#   OR leave both unset                       (no authentication - dev only)

# ========================================
# LOGICMONITOR API CREDENTIALS (REQUIRED)
# ========================================

# Your LogicMonitor company/account name (subdomain)
# Example: if your portal is "mycompany.logicmonitor.com", use "mycompany"
# CLI flag: --lm-company
LM_COMPANY=your-company-name

# LogicMonitor API Bearer Token
# Generate at: Settings > Users & Roles > API Tokens
# Requires: API user with appropriate permissions
# CLI flag: --lm-bearer-token
LM_BEARER_TOKEN=your-logicmonitor-api-token

# ========================================
# TRANSPORT CONFIGURATION
# ========================================

# Transport type: stdio, sse, or streamable-http
# CLI flag: -t, --transport
# Default: stdio
#
# Transport Options:
#   - stdio:           Standard I/O for local process communication
#                      Use for: Claude Desktop, local CLI tools
#                      Authentication: Not required (local only)
#
#   - sse:             Server-Sent Events for web clients
#                      Use for: Web applications, remote access
#                      Authentication: Optional (see below)
#
#   - streamable-http: RESTful HTTP for API integrations
#                      Use for: Advanced integrations, API clients
#                      Authentication: Optional (see below)
MCP_TRANSPORT=stdio

# Server address for SSE/HTTP transports
# Format: host:port
# CLI flag: --address
# Default: localhost:3000
# Examples:
#   - localhost:3000  (local development)
#   - 0.0.0.0:3000    (listen on all interfaces)
#   - 0.0.0.0:443     (production with TLS)
MCP_ADDRESS=localhost:3000

# Base path for the server (optional)
# CLI flag: --base-path
# Example: /api/v1
# Default: none
#MCP_BASE_PATH=/api

# Endpoint path for MCP requests
# CLI flag: --endpoint-path
# Default: /mcp
# The server will listen at:
#   - SSE: {MCP_ENDPOINT_PATH}/sse
#   - HTTP: {MCP_ENDPOINT_PATH}
MCP_ENDPOINT_PATH=/mcp

# ========================================
# TLS/HTTPS CONFIGURATION (Optional)
# For SSE/HTTP transports only
# STRONGLY RECOMMENDED for production
# ========================================

# Path to TLS certificate file for HTTPS
# CLI flag: --server.tls-cert-file
# If both cert and key are configured, server uses HTTPS
# If unconfigured, server uses HTTP
#MCP_TLS_CERT_FILE=/path/to/cert.pem

# Path to TLS private key file for HTTPS
# CLI flag: --server.tls-key-file
# Both cert and key required to enable HTTPS
#MCP_TLS_KEY_FILE=/path/to/key.pem

# Generate self-signed certificate for testing:
#   openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"

# ========================================
# MCP SERVER AUTHENTICATION (Optional)
# For SSE/HTTP transports only
# Not required for STDIO transport
# ========================================

# Authentication Modes:
# 1. No Authentication (default):
#    - OAUTH_PROVIDER=none (or unset)
#    - MCP_BEARER_TOKEN not set
#    - WARNING: Only for development/testing in trusted environments
#
# 2. Static Bearer Token (simple):
#    - Set MCP_BEARER_TOKEN
#    - Clients send: Authorization: Bearer <token>
#    - Good for: API clients, internal services
#
# 3. OAuth/OIDC (enterprise):
#    - Set OAUTH_PROVIDER and related OAuth settings
#    - Users authenticate via web browser
#    - Good for: Web applications, SSO integration
#
# 4. Combined (flexible):
#    - Set both MCP_BEARER_TOKEN and OAuth
#    - Supports both authentication methods simultaneously

# --- Static Bearer Token Authentication ---

# Static bearer token for MCP server authentication
# CLI flag: --mcp-bearer-token
# Clients must send: Authorization: Bearer <your-token>
#
# Generate secure token:
#   openssl rand -base64 32
#   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
#
# Security: Use strong tokens (32+ bytes), rotate regularly
#MCP_BEARER_TOKEN=your-static-bearer-token-here

# --- OAuth/OIDC Authentication ---

# OAuth provider type
# Options: none | github | google | azure | okta | auth0 | custom
# Default: none (OAuth disabled)
#
# Setting to 'none' or leaving unset disables OAuth authentication
# If both OAuth and MCP_BEARER_TOKEN are disabled, unauthenticated access is allowed
OAUTH_PROVIDER=none

# OAuth client credentials
# Obtain these from your OAuth provider's developer console
# Required if OAUTH_PROVIDER is set to a provider (not 'none')
#OAUTH_CLIENT_ID=your-oauth-client-id
#OAUTH_CLIENT_SECRET=your-oauth-client-secret

# OAuth session secret (for encrypting session cookies)
# Generate a strong random string:
#   openssl rand -hex 32
# Also accepts SESSION_SECRET for backward compatibility
#OAUTH_SESSION_SECRET=your-session-secret-here

# OAuth callback URL
# Must be registered with your OAuth provider
# Should match your server's public URL
# Default: http://{MCP_ADDRESS}/auth/callback
# Example: https://mcp.example.com/auth/callback
#OAUTH_CALLBACK_URL=http://localhost:3000/auth/callback

# OAuth scopes (comma-separated or space-separated)
# Different providers support different scopes
# Examples:
#   GitHub:  user:email,read:user
#   Google:  profile,email,openid
#   Azure:   openid,profile,email,User.Read
#   Okta:    openid,profile,email
#   Auth0:   openid,profile,email
# Default: Provider-specific defaults
#OAUTH_SCOPE=user:email

# ========================================
# PROVIDER-SPECIFIC OAUTH CONFIGURATION
# ========================================

# --- GITHUB OAUTH (provider=github) ---
# Setup:
#   1. Go to: https://github.com/settings/developers
#   2. Click "New OAuth App"
#   3. Set Authorization callback URL to your OAUTH_CALLBACK_URL
# Recommended scopes: user:email, read:user
# Note: GitHub doesn't support refresh tokens in standard OAuth flow

# --- GOOGLE OAUTH (provider=google) ---
# Setup:
#   1. Go to: https://console.cloud.google.com/apis/credentials
#   2. Create OAuth 2.0 Client ID (Web application)
#   3. Add your OAUTH_CALLBACK_URL to Authorized redirect URIs
# Recommended scopes: profile, email, openid
# Note: May require Google+ API to be enabled

# --- AZURE AD / MICROSOFT (provider=azure) ---
# Setup:
#   1. Go to: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps
#   2. Register new application
#   3. Add redirect URI under Authentication
# Recommended scopes: openid, profile, email, User.Read
# Azure tenant ID (common, organizations, consumers, or specific tenant ID)
#OAUTH_AZURE_TENANT_ID=common

# --- OKTA (provider=okta) ---
# Setup:
#   1. Go to Okta Admin Console > Applications
#   2. Create new OAuth application (Web)
#   3. Configure Sign-in redirect URIs
# Recommended scopes: openid, profile, email
# Your Okta domain (e.g., dev-12345.okta.com)
#OAUTH_OKTA_DOMAIN=your-domain.okta.com

# --- AUTH0 (provider=auth0) ---
# Setup:
#   1. Go to Auth0 Dashboard > Applications
#   2. Create new application (Regular Web Application)
#   3. Configure Allowed Callback URLs
# Recommended scopes: openid, profile, email
# Your Auth0 domain (e.g., yourapp.auth0.com or yourapp.us.auth0.com)
#OAUTH_AUTH0_DOMAIN=your-domain.auth0.com

# --- CUSTOM OAUTH PROVIDER (provider=custom) ---
# For custom OAuth2/OIDC providers not listed above
# All three endpoints are required for custom providers
#OAUTH_AUTHORIZATION_URL=https://provider.com/oauth2/authorize
#OAUTH_TOKEN_URL=https://provider.com/oauth2/token
#OAUTH_USER_PROFILE_URL=https://provider.com/oauth2/userinfo

# ========================================
# TOKEN REFRESH CONFIGURATION (OAuth only)
# ========================================

# Enable automatic token refresh in background
# Options: true | false
# Default: true
# When enabled, tokens are automatically refreshed before expiry
# Requires OAuth provider to support refresh tokens
#OAUTH_TOKEN_REFRESH=true

# Token refresh buffer (minutes before expiry to trigger refresh)
# Default: 5 minutes
# Lower values = more aggressive refresh (less chance of expiry)
# Higher values = fewer refresh requests (but higher risk of expiry)
# Range: 1-60 minutes
#OAUTH_TOKEN_REFRESH_BUFFER=5

# ========================================
# DEBUG AND LOGGING
# ========================================

# Enable debug mode with detailed logging
# CLI flag: --debug
# Options: true | false
# Default: false
# When enabled: verbose logging including API requests/responses
MCP_DEBUG=false

# Log format
# CLI flag: --log-format
# Options:
#   - json:  Machine-readable JSON format (recommended for production)
#   - human: Human-readable format with colors and emojis (good for development)
# Default: human
MCP_LOG_FORMAT=human

# Log level
# CLI flag: --log-level
# Options: debug | info | warn | error
# Levels (from most to least verbose):
#   - debug: All messages including debug info (most verbose)
#   - info:  Informational messages and above (recommended)
#   - warn:  Warnings and errors only
#   - error: Errors only (least verbose)
# Default: info
MCP_LOG_LEVEL=info

# ========================================
# TOOL CONFIGURATION
# ========================================

# Comma-separated list of enabled tools
# CLI flag: --enabled-tools
# Default: all tools enabled (125 tools)
# Example: list_resources,get_resource,list_alerts,get_alert
# Use case: Restrict available tools for security or simplicity
#MCP_ENABLED_TOOLS=list_resources,get_resource,list_alerts,get_alert

# Enable only read-only tools (safer mode)
# CLI flag: --read-only
# Options: true | false
# Tool counts:
#   - true:  73 read-only tools (list, get, search operations)
#   - false: 125 tools (73 read-only + 52 write operations)
# Default: true (recommended for production)
# Set to false only if write operations are needed
MCP_READ_ONLY=true

# Disable search tools
# CLI flag: --disable-search
# Options: true | false
# Removes: search_resources, search_alerts, search_audit_logs (3 tools)
# Default: false
# Use case: Reduce exposed functionality for security
MCP_DISABLE_SEARCH=false

# ========================================
# ADVANCED SERVER OPTIONS (Optional)
# ========================================

# Node environment
# Options: development | production
# Affects: logging verbosity, error messages, security features
# Default: development
#NODE_ENV=production

# Base URL for OAuth callbacks and JWT audience
# Used for:
#   - Generating absolute URLs for OAuth redirects
#   - JWT token audience validation (RFC 8707)
# MUST match the URL that clients use to access the server
# Default: http://{MCP_ADDRESS}
# Example: https://mcp.example.com
#BASE_URL=http://localhost:3000

# JWT Secret for signing tokens
# Generate with: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
# If not set, a random secret is generated at startup
# REQUIRED for production deployments with multiple server instances
# Security: Use strong secrets (64+ bytes), never commit to version control
#JWT_SECRET=your-jwt-secret-key-here

# CORS Configuration
# Comma-separated list of allowed origins
# Default: * (allow all origins - suitable for development)
# Production: Specify exact domains for security
# Example: http://localhost:3000,https://mcp.example.com
#ALLOWED_ORIGINS=*

# Transport mode for multi-transport capable endpoints
# Options: both | http-only | sse-only
# Default: both
# Use case: Restrict available transports for security or infrastructure constraints
#   - both:      Enable both SSE and HTTP transports
#   - sse-only:  Only SSE transport (disable HTTP)
#   - http-only: Only HTTP transport (disable SSE)
#TRANSPORT_MODE=both

# ========================================
# CONFIGURATION EXAMPLES
# ========================================

# Example 1: Local Development with Claude Desktop (STDIO)
# ---------------------------------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_TRANSPORT=stdio
# MCP_READ_ONLY=true
# MCP_DEBUG=false

# Example 2: Development Server (SSE, No Authentication)
# -------------------------------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_TRANSPORT=sse
# MCP_ADDRESS=localhost:3000
# OAUTH_PROVIDER=none
# # MCP_BEARER_TOKEN not set - unauthenticated access
# MCP_READ_ONLY=true
# MCP_DEBUG=true

# Example 3: Production API Server (SSE with Bearer Token)
# ---------------------------------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_TRANSPORT=sse
# MCP_ADDRESS=0.0.0.0:443
# MCP_TLS_CERT_FILE=/etc/ssl/certs/server.crt
# MCP_TLS_KEY_FILE=/etc/ssl/private/server.key
# OAUTH_PROVIDER=none
# MCP_BEARER_TOKEN=your-secure-server-token
# NODE_ENV=production
# MCP_LOG_FORMAT=json
# MCP_LOG_LEVEL=info
# MCP_READ_ONLY=true

# Example 4: Production Web Server (SSE with OAuth)
# --------------------------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_TRANSPORT=sse
# MCP_ADDRESS=0.0.0.0:443
# MCP_TLS_CERT_FILE=/etc/ssl/certs/server.crt
# MCP_TLS_KEY_FILE=/etc/ssl/private/server.key
# OAUTH_PROVIDER=github
# OAUTH_CLIENT_ID=your-github-client-id
# OAUTH_CLIENT_SECRET=your-github-client-secret
# OAUTH_SESSION_SECRET=your-session-secret
# OAUTH_CALLBACK_URL=https://mcp.example.com/auth/callback
# BASE_URL=https://mcp.example.com
# NODE_ENV=production
# MCP_LOG_FORMAT=json
# MCP_LOG_LEVEL=info
# MCP_READ_ONLY=true

# Example 5: Production Flexible (Both OAuth and Bearer Token)
# -------------------------------------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_TRANSPORT=sse
# MCP_ADDRESS=0.0.0.0:443
# MCP_TLS_CERT_FILE=/etc/ssl/certs/server.crt
# MCP_TLS_KEY_FILE=/etc/ssl/private/server.key
# # OAuth for web users
# OAUTH_PROVIDER=github
# OAUTH_CLIENT_ID=your-github-client-id
# OAUTH_CLIENT_SECRET=your-github-client-secret
# OAUTH_SESSION_SECRET=your-session-secret
# # Bearer token for API clients
# MCP_BEARER_TOKEN=your-secure-server-token
# BASE_URL=https://mcp.example.com
# NODE_ENV=production
# MCP_LOG_FORMAT=json
# MCP_READ_ONLY=true

# Example 6: Restricted Tools (Only Alert Management)
# ----------------------------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_ENABLED_TOOLS=list_alerts,get_alert,acknowledge_alert,add_alert_note
# MCP_READ_ONLY=false  # Allow acknowledge and add_alert_note
# MCP_DISABLE_SEARCH=true

# Example 7: Docker Development
# ------------------------------
# LM_COMPANY=mycompany
# LM_BEARER_TOKEN=your-lm-api-token
# MCP_TRANSPORT=sse
# MCP_ADDRESS=0.0.0.0:3000
# OAUTH_PROVIDER=none
# MCP_DEBUG=true
# MCP_LOG_FORMAT=json

# ========================================
# SECURITY RECOMMENDATIONS
# ========================================

# Development:
#   - STDIO transport (no authentication needed)
#   - Or SSE/HTTP with OAUTH_PROVIDER=none (unauthenticated)
#   - Use only in trusted environments
#   - Enable MCP_DEBUG for troubleshooting

# Production:
#   - ALWAYS use TLS/HTTPS (MCP_TLS_CERT_FILE, MCP_TLS_KEY_FILE)
#   - ALWAYS enable authentication:
#     * Bearer token (MCP_BEARER_TOKEN) for API clients
#     * OAuth (OAUTH_PROVIDER) for web users
#     * Or both for flexibility
#   - Set NODE_ENV=production
#   - Use MCP_LOG_FORMAT=json for structured logging
#   - Enable MCP_READ_ONLY=true unless write operations are required
#   - Rotate tokens regularly (monthly recommended)
#   - Use strong secrets (32+ bytes for tokens, 64+ bytes for JWT)
#   - Restrict ALLOWED_ORIGINS to specific domains
#   - Configure firewall rules to limit access
#   - Monitor logs and health endpoints (/health, /healthz)
#   - Never commit .env file to version control

# ========================================
# QUICK REFERENCE
# ========================================

# Server entry point: build/servers/index.js
# NPM scripts:
#   npm start               # Default (stdio)
#   npm run start:stdio     # STDIO transport
#   npm run start:sse       # SSE transport
#   npm run start:http      # HTTP transport
#
# Health check endpoints (SSE/HTTP only):
#   GET /healthz            # Simple health check (returns "ok")
#   GET /health             # Detailed health information (JSON)
#
# OAuth endpoints (when OAuth is configured):
#   GET /auth/login         # Initiate OAuth login
#   GET /auth/callback      # OAuth callback handler
#   GET /logout             # Logout and clear session
#
# MCP endpoints (SSE/HTTP only):
#   GET  {MCP_ENDPOINT_PATH}/sse  # SSE connection
#   POST {MCP_ENDPOINT_PATH}      # HTTP request
#
# Default values:
#   MCP_TRANSPORT:     stdio
#   MCP_ADDRESS:       localhost:3000
#   MCP_ENDPOINT_PATH: /mcp
#   MCP_READ_ONLY:     true
#   MCP_LOG_FORMAT:    human
#   MCP_LOG_LEVEL:     info
#   OAUTH_PROVIDER:    none
#   TRANSPORT_MODE:    both