env.example

# MCP4OpenAPI Environment Variables Template (GitLab exmaples)
# Copy this file to .env and fill in your values
# Never commit .env file to version control!

# =============================================================================
# REQUIRED CONFIGURATION
# =============================================================================

# API Authentication Token (for stdio mode or default auth)
MCP4_API_TOKEN=your_api_token_here

# Custom Authentication Environment Variable Name
#MCP4_AUTH_ENV_VAR=MCP4_API_TOKEN

# =============================================================================
# CORE CONFIGURATION
# =============================================================================

# OpenAPI Specification (optional when profile defines openapi_spec_path)
# Can be a local file path or HTTP/HTTPS URL
# Examples:
#   MCP4_OPENAPI_SPEC_PATH=profiles/gitlab/openapi.yaml
#   MCP4_OPENAPI_SPEC_PATH=https://api.example.com/openapi.yaml
#   MCP4_OPENAPI_SPEC_PATH=http://localhost:8080/openapi.json
#MCP4_OPENAPI_SPEC_PATH=profiles/gitlab/openapi.yaml

# Profile Configuration
# (optional, but recommended - if not set, tools are auto-generated)
# Short profile ID for --profile / MCP4_PROFILE selection
#MCP4_PROFILE=gitlab
# Profiles root directory for profile ID resolution
#MCP4_PROFILES_DIR=profiles
MCP4_PROFILE_PATH=profiles/gitlab/developer-profile-oauth.json

# Transport Mode: stdio (default) or http (SSE fallback implemented)
#MCP4_TRANSPORT=stdio

# API Base URL (optional - overrides OpenAPI spec server URL)
#MCP4_API_BASE_URL=https://gitlab.example.com/api/v4

# Proxy download size limit (optional)
# Global cap for proxy_download operations (bytes, default: 10485760 = 10MB)
#MCP4_PROXY_MAX_BYTES=2097152

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

# Server Binding (optional)
#MCP4_HOST=127.0.0.1
#MCP4_PORT=3003

# CORS Configuration
# Comma-separated list of allowed origins
# Supports: exact match, wildcards (*.domain.com), CIDR (192.168.1.0/24)
#MCP4_ALLOWED_ORIGINS=https://example.com,http://localhost:*

# Session Management
#MCP4_SESSION_TIMEOUT_MS=1800000  # 30 minutes (default for non-OAuth sessions)

# OAuth Session Management (for OAuth sessions with refresh tokens)
# OAuth session timeout: 24 hours (default), 0 = unlimited
#MCP4_OAUTH_SESSION_TIMEOUT_MS=86400000  # 24 hours
#MCP4_OAUTH_SESSION_TIMEOUT_MS=0  # Unlimited (never expire)

# OAuth token refresh threshold: refresh access token this many milliseconds before expiration
#MCP4_OAUTH_REFRESH_THRESHOLD_MS=60000  # 60 seconds (default)

# SSE Heartbeat
#MCP4_HEARTBEAT_ENABLED=false
#MCP4_HEARTBEAT_INTERVAL_MS=30000  # 30 seconds

# Token Validation
#MCP4_TOKEN_MAX_LENGTH=4096  # Maximum bearer token length in characters
#MCP4_TOKEN_KEY=                          # Optional: enables AES-256-GCM encrypted token envelopes (mcp4.v1.*) for restart-resilient OAuth sessions. Accepts any passphrase, or a 64-char hex string for a raw 32-byte key. When unset, OAuth clients must re-authenticate after every gateway restart.

# Parameter Filtering (X-Mcp4-Params)
# Max values per filtering key in X-Mcp4-Params header (default: 10)
#MCP4_FILTER_MAX_VALUES=10

# HTTP profile routing (optional)
# Enable profile routing to serve multiple profiles over HTTP
#MCP4_HTTP_PROFILE_ROUTING=true
# Optional profile index page at /
#MCP4_HTTP_PROFILE_INDEX=true
# Optional admin HTML snippets for the HTML profile index detail card.
# JSON object: profile id / profile name / alias -> trusted HTML string.
# Rendered only in GET / HTML output, not in JSON index responses.
# Startup fails fast on invalid JSON, duplicate resolution conflicts, or values > 10000 chars.
#MCP4_PROFILES_DESCRIPTION={"gitlab":"<p><strong>Internal:</strong> Use SSO token.</p>"}
# Restrict routed profiles to an allowlist (ids/names/aliases)
#MCP4_ALLOW_PROFILES=gitlab,github
#MCP4_ALLOW_PROFILES_REGEX=^team-
# Hide profiles from the index page (profiles remain functional)
#MCP4_HIDDEN_PROFILES=legacy-gitlab,old-github

# =============================================================================
# SSL/TLS CONFIGURATION (OPTIONAL)
# =============================================================================

# Enable HTTPS by providing certificate and key files
# When both are set, server automatically starts in HTTPS mode
# (cert file can include intermediate certificates)
#MCP4_SSL_CERT_FILE=/path/to/certificate.pem
#MCP4_SSL_KEY_FILE=/path/to/private-key.pem

# Example for production (Let's Encrypt):
#MCP4_SSL_CERT_FILE=/etc/letsencrypt/live/mcp.example.com/fullchain.pem
#MCP4_SSL_KEY_FILE=/etc/letsencrypt/live/mcp.example.com/privkey.pem

# =============================================================================
# RATE LIMITING (SECURITY)
# =============================================================================

# Enable HTTP rate limiting to protect against DoS attacks
#MCP4_HTTP_RATE_LIMIT_ENABLED=true

# Rate limit window in milliseconds (default: 60000 = 1 minute)
#MCP4_HTTP_RATE_LIMIT_WINDOW_MS=60000

# Maximum requests per window for /mcp, /sse, /health endpoints
#MCP4_HTTP_RATE_LIMIT_MAX_REQUESTS=100

# Maximum requests per window for /metrics endpoint
#MCP4_HTTP_RATE_LIMIT_METRICS_MAX=10

# OAuth Rate Limiting (stricter limits for OAuth endpoints)
# These limits apply to /oauth/authorize, /oauth/token, /oauth/callback endpoints
# Configuration priority: Profile oauth_rate_limit > Environment variables > Defaults
#MCP4_OAUTH_RATE_LIMIT_MAX=10  # Max OAuth requests per window (default: 10)
#MCP4_OAUTH_RATE_LIMIT_WINDOW_MS=600000  # OAuth rate limit window in ms (default: 600000 = 10 minutes)

# =============================================================================
# AUTHENTICATION CONFIGURATION
# =============================================================================
# NOTE: These settings are used only when NO profile is defined
# (auto-generated tools from OpenAPI spec).
# For profiles, use auth interceptors with types:
# 'oauth' (OAuth 2.0 flow) or 'bearer' (static token)

# Force Authentication Override
# When true, forces authentication even if OpenAPI spec doesn't require it
#MCP4_AUTH_FORCE=false

# Authentication Type: bearer, query, custom-header (default: bearer)
# Determines HOW the token is sent in HTTP requests (header vs query vs custom header)
# NOT related to OAuth - use profiles for OAuth configuration
#MCP4_AUTH_TYPE=bearer

# Query Parameter Name (required when MCP4_AUTH_TYPE=query)
#MCP4_AUTH_QUERY_PARAM=api_key

# Custom Header Name (required when MCP4_AUTH_TYPE=custom-header)
#MCP4_AUTH_HEADER_NAME=X-API-Key

# =============================================================================
# OAUTH 2.0 CONFIGURATION
# =============================================================================

# DCR (Dynamic Client Registration) OAuth Client Credentials (REQUIRED for OAuth)
#MCP4_OAUTH_CLIENT_ID=your_oauth_client_id_here
#MCP4_OAUTH_CLIENT_SECRET=your_oauth_client_secret_here

# OAuth Redirect URI (REQUIRED for OAuth)
# Must match registered redirect URI in OAuth provider
# Use https:// for production, http://localhost for development
#MCP4_OAUTH_REDIRECT_URI=http://localhost:3003/oauth/callback

# Optional: Allow unregistered OAuth clients only for approved redirect URI rules.
# CLI equivalents: --allow-unregistered-clients, --allowed-unregistered-redirect-uris
#MCP4_ALLOW_UNREGISTERED_CLIENTS=true
#MCP4_ALLOWED_UNREGISTERED_REDIRECT_URIS=http://localhost,cursor://

# ✨ NEW: Automatic Autodiscovery (Simplest)
# If MCP4_API_BASE_URL is set and contains an OAuth provider,
# the server will automatically discover OAuth endpoints via RFC 8414 metadata
# Example: MCP4_API_BASE_URL=https://gitlab.example.com/api/v4
#          → Discovers https://gitlab.example.com/oauth/authorize
#          → Discovers https://gitlab.example.com/oauth/token

# Option 1: Explicit Issuer URL (auto-derives /oauth/authorize and /oauth/token)
#MCP4_OAUTH_ISSUER=https://gitlab.example.com

# Option 2: Explicit OAuth Endpoints (for non-standard paths)
#MCP4_OAUTH_AUTHORIZATION_URL=https://gitlab.example.com/oauth/authorize
#MCP4_OAUTH_TOKEN_URL=https://gitlab.example.com/oauth/token

# Configuration Priority:
# 1. Explicit URLs (MCP4_OAUTH_AUTHORIZATION_URL, MCP4_OAUTH_TOKEN_URL)
# 2. Explicit issuer (MCP4_OAUTH_ISSUER)
# 3. Autodiscovery from MCP4_API_BASE_URL (fetches /.well-known/oauth-authorization-server)

# Optional: Dynamic OAuth client store safety limits (DoS hardening)
# Max dynamic OAuth clients stored in memory (default: 1000)
#MCP4_OAUTH_CLIENT_STORE_MAX_CLIENTS=1000
# Max redirect_uris per dynamically registered OAuth client (default: 10)
#MCP4_OAUTH_CLIENT_STORE_MAX_REDIRECT_URIS=10
# Max length of one redirect URI for dynamic OAuth clients (default: 256)
#MCP4_OAUTH_CLIENT_STORE_MAX_REDIRECT_URI_LENGTH=256
# Minimum age in milliseconds before an idle OAuth client is evictable (default: 0)
#MCP4_OAUTH_CLIENT_STORE_IDLE_GRACE_MS=0

# =============================================================================
# TOOL NAMING CONFIGURATION
# =============================================================================
# NOTE: Tool naming configuration is ignored with profiles.

# Maximum tool name length in characters (default: 45)
#MCP4_TOOLNAME_MAX=45

# Tool name shortening strategy: none, balanced, iterative, hash, auto (default: none)
#MCP4_TOOLNAME_STRATEGY=none

# Only warn about long tool names, don't shorten them: true, false (default: true)
#MCP4_TOOLNAME_WARN_ONLY=true

# Advanced tool naming parameters (used by balanced/iterative strategies)

# Number of similar tool names to consider for uniqueness (default: 3)
#MCP4_TOOLNAME_SIMILAR_TOP=3

# Similarity threshold for considering names too similar (default: 0.75)
#MCP4_TOOLNAME_SIMILARITY_THRESHOLD=0.75

# Minimum number of path parts for balanced strategy (default: 3)
#MCP4_TOOLNAME_MIN_PARTS=3

# Minimum length in characters for balanced strategy (default: 20)
#MCP4_TOOLNAME_MIN_LENGTH=20

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

# Global tool filtering (comma-separated, case-sensitive)
#MCP4_TOOL_FILTER_ALLOW_NAMES=get_user,list_users
#MCP4_TOOL_FILTER_ALLOW_NAME_REGEX=get_.*
#MCP4_TOOL_FILTER_DENY_NAMES=delete_user
#MCP4_TOOL_FILTER_DENY_NAME_REGEX=delete_.*

# Allow tools by detected operation category (comma-separated)
# Supported values: list, read
# Example: allow all list/read-only tools (including composites where all steps are list/read)
#MCP4_TOOL_FILTER_ALLOW_CATEGORIES=list,read

# Warn if more than this percent of tools are filtered (default: 90)
#MCP4_TOOL_FILTER_WARN_THRESHOLD_PCT=90

# Max entries in X-Mcp4-Tools header (default: 100)
#MCP4_TOOL_FILTER_SESSION_MAX_TOOLS=100

# =============================================================================
# LOGGING CONFIGURATION
# =============================================================================

# Log Level: debug, info, warn, error (default: info)
#MCP4_LOG_LEVEL=info

# Log Format: console, json (default: console)
#MCP4_LOG_FORMAT=console

# =============================================================================
# METRICS CONFIGURATION
# =============================================================================

# Enable Prometheus metrics endpoint at /metrics
#MCP4_METRICS_ENABLED=false

# Metrics endpoint path (default: /metrics)
#MCP4_METRICS_PATH=/metrics