Skip to content

MCP Configuration Management

Last Updated: 2026-07-11 Version: v0.2.0

**Last Updated: 2026-06-22

Overview

The MCP configuration management capability provides centralized configuration handling for Model Context Protocol services, including environment variables, mcp.json schema, runtime settings, and multi-environment support.

Keywords: mcp, configuration, settings, environment, mcp.json, config, management, runtime, validation, safeguards

Purpose

Manages MCP service configuration through: - Configuration Files: mcp.json, config.yaml, settings.py - Environment Variables: .env file support with validation - Runtime Configuration: Dynamic config reload and updates - Multi-Environment: Dev, staging, production configurations - Schema Validation: Type-safe configuration with validation

Architecture

Configuration Hierarchy

 Environment Variables (.env) 
 (highest priority) 

 overrides


 mcp.json Configuration 
 (MCP-specific settings) 

 overrides


 config.yaml / settings.py 
 (application defaults) 

Configuration Loading Flow

# Pseudocode for configuration loading
def load_config():
 # 1. Load default configuration
 config = load_defaults()

 # 2. Load config files
 config.update(load_yaml("config.yaml"))
 config.update(load_json("mcp.json"))

 # 3. Apply environment overrides
 config.update(load_env_vars())

 # 4. Validate configuration
 validate_config_schema(config)

 return config

Configuration Files

mcp.json Schema

{
 "$schema": "https://json-schema.org/draft-07/schema#",
 "title": "MCP Service Configuration",
 "type": "object",
 "properties": {
 "server": {
 "type": "object",
 "properties": {
 "host": {"type": "string", "default": "0.0.0.0"},
 "port": {"type": "integer", "minimum": 1024, "maximum": 65535},
 "workers": {"type": "integer", "minimum": 1},
 "timeout_seconds": {"type": "integer", "minimum": 1}
 },
 "required": ["port"]
 },
 "capabilities": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "name": {"type": "string"},
 "enabled": {"type": "boolean", "default": true},
 "version": {"type": "string"}
 },
 "required": ["name", "version"]
 }
 },
 "logging": {
 "type": "object",
 "properties": {
 "level": {
 "type": "string",
 "enum": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
 },
 "format": {"type": "string"}
 }
 }
 },
 "required": ["server", "capabilities"]
}

Example mcp.json

{
 "server": {
 "host": "0.0.0.0",
 "port": 8080,
 "workers": 4,
 "timeout_seconds": 30
 },
 "capabilities": [
 {
 "name": "code_analysis",
 "version": "1.0.0",
 "enabled": true
 },
 {
 "name": "documentation",
 "version": "2.1.0",
 "enabled": false
 }
 ],
 "logging": {
 "level": "INFO",
 "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 },
 "auth": {
 "enabled": true,
 "api_key_header": "X-API-Key" <!-- pragma: allowlist secret -->
 }
}

Environment Variables (.env)

# .env file
MCP_SERVER_PORT=8080
MCP_SERVER_HOST=0.0.0.0
MCP_WORKERS=4
MCP_LOG_LEVEL=INFO

# Database
MCP_DB_HOST=localhost
MCP_DB_PORT=5432
MCP_DB_NAME=mcp_db

# Authentication
MCP_API_KEY=your-secret-api-key
MCP_JWT_SECRET=your-jwt-secret

# Feature flags
MCP_ENABLE_CACHING=true
MCP_ENABLE_METRICS=true

Python Settings Module

# settings.py
from pydantic import BaseSettings, Field

class MCPSettings(BaseSettings):
 """MCP Service Configuration."""

 # Server settings
 server_host: str = Field("0.0.0.0", env="MCP_SERVER_HOST")
 server_port: int = Field(8080, env="MCP_SERVER_PORT", gt=1024, le=65535)
 workers: int = Field(4, env="MCP_WORKERS", gt=0)

 # Database settings
 db_host: str = Field("localhost", env="MCP_DB_HOST")
 db_port: int = Field(5432, env="MCP_DB_PORT")
 db_name: str = Field("mcp_db", env="MCP_DB_NAME")

 # Authentication
 api_key: str = Field(..., env="MCP_API_KEY")
 jwt_secret: str = Field(..., env="MCP_JWT_SECRET")

 # Feature flags
 enable_caching: bool = Field(True, env="MCP_ENABLE_CACHING")
 enable_metrics: bool = Field(True, env="MCP_ENABLE_METRICS")

 class Config:
 env_file = ".env"
 env_file_encoding = "utf-8"
 case_sensitive = False

# Usage
settings = MCPSettings()

Usage Examples

Example 1: Load Configuration

import json
from pathlib import Path

def load_mcp_config(config_path: str = "mcp.json"):
 """Load MCP configuration with validation."""
 with open(config_path) as f:
 config = json.load(f)

 # Validate required fields
 assert "server" in config, "Missing 'server' section"
 assert "port" in config["server"], "Missing 'server.port'"

 return config

# Usage
config = load_mcp_config()
print(f"Server port: {config['server']['port']}")

Example 2: Environment Override

import os
from typing import Any, Dict

def apply_env_overrides(config: Dict[str, Any]) -> Dict[str, Any]:
 """Apply environment variable overrides to config."""

 # Server overrides
 if "MCP_SERVER_PORT" in os.environ:
 config["server"]["port"] = int(os.environ["MCP_SERVER_PORT"])

 if "MCP_SERVER_HOST" in os.environ:
 config["server"]["host"] = os.environ["MCP_SERVER_HOST"]

 # Logging overrides
 if "MCP_LOG_LEVEL" in os.environ:
 config.setdefault("logging", {})["level"] = os.environ["MCP_LOG_LEVEL"]

 return config

# Usage
config = load_mcp_config()
config = apply_env_overrides(config)

Example 3: Dynamic Configuration Reload

import time
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class ConfigReloadHandler(FileSystemEventHandler):
 def __init__(self, config_path: str, on_reload_callback):
 self.config_path = config_path
 self.callback = on_reload_callback

 def on_modified(self, event):
 if event.src_path.endswith(self.config_path):
 print(f"Configuration changed, reloading...")
 new_config = load_mcp_config(self.config_path)
 self.callback(new_config)

def setup_config_watch(config_path: str, callback):
 """Watch configuration file for changes."""
 event_handler = ConfigReloadHandler(config_path, callback)
 observer = Observer()
 observer.schedule(event_handler, path=".", recursive=False)
 observer.start()
 return observer

# Usage
def on_config_reload(new_config):
 print(f"Updated configuration: {new_config}")

observer = setup_config_watch("mcp.json", on_config_reload)

Example 4: Multi-Environment Configuration

import os

class ConfigManager:
 """Manages multi-environment configurations."""

 def __init__(self):
 self.env = os.getenv("MCP_ENV", "development")
 self.config = self._load_config()

 def _load_config(self):
 """Load environment-specific configuration."""
 base_config = self._load_json("config.base.json")
 env_config = self._load_json(f"config.{self.env}.json")

 # Merge configurations (env overrides base)
 return {**base_config, **env_config}

 def _load_json(self, path: str):
 """Load JSON config file."""
 try:
 with open(path) as f:
 return json.load(f)
 except FileNotFoundError:
 return {}

 def get(self, key: str, default=None):
 """Get configuration value."""
 return self.config.get(key, default)

# Usage
config_mgr = ConfigManager()
db_host = config_mgr.get("database.host", "localhost")

Integration with Audit Pipeline

Detection Command

# Check configuration capability
python scripts/space_traversal/audit_runner.py explain mcp-configuration

# Run full audit
python scripts/space_traversal/audit_runner.py run

Programmatic Detection

from scripts.space_traversal.detectors import mcp_configuration

# Run detector
file_index = {
 "files": [
 {"path": "mcp.json"},
 {"path": ".env"},
 {"path": "config.yaml"},
 {"path": "src/services/settings.py"}
 ]
}

result = mcp_configuration.detect(file_index)
print(f"Found patterns: {result['found_patterns']}")
print(f"Config types: {result['meta']['config_types']}")

Best Practices

Configuration Security

  1. Never Commit Secrets

    # .gitignore
    .env
    .env.local
    .env.*.local
    *secret*
    *key*
    

  2. Use Environment Variables for Secrets

    # Good
    api_key = os.getenv("MCP_API_KEY")
    
    # Avoid
    api_key = "hardcoded-secret-key" <!-- pragma: allowlist secret -->
    

  3. Encrypt Sensitive Configuration

    from cryptography.fernet import Fernet
    
    def encrypt_config(config: dict, key: bytes) -> bytes:
     f = Fernet(key)
     return f.encrypt(json.dumps(config).encode())
    

Configuration Validation

  1. Validate on Load

    from jsonschema import validate
    
    schema = {...} # JSON schema
    validate(instance=config, schema=schema)
    

  2. Type Checking

    from pydantic import BaseModel, ValidationError
    
    class Config(BaseModel):
     port: int
     host: str
    
    try:
     Config(**config)
    except ValidationError as e:
     print(f"Invalid config: {e}")
    

  3. Range Validation

    assert 1024 <= config["port"] <= 65535, "Invalid port range"
    

Configuration Documentation

  1. Document All Settings: Provide descriptions and examples
  2. Include Defaults: Specify default values 3. Show Environment Variables: Document env var names and mappings
  3. Provide Examples: Include example configurations for common scenarios

Troubleshooting

Issue: Configuration Not Found

Solution:

from pathlib import Path

config_path = Path("mcp.json")
if not config_path.exists():
 print(f"Config not found at {config_path.absolute()}")
 config_path = Path("/etc/mcp/mcp.json") # Fallback

Issue: Invalid JSON

Solution:

import json

try:
 config = json.load(f)
except json.JSONDecodeError as e:
 print(f"Invalid JSON at line {e.lineno}: {e.msg}")

Issue: Missing Environment Variables

Solution:

required_vars = ["MCP_API_KEY", "MCP_DB_HOST"]
missing = [var for var in required_vars if var not in os.environ]
if missing:
 raise ValueError(f"Missing required environment variables: {missing}")

Performance Considerations

  • Config Caching: Cache loaded configuration to avoid repeated file I/O
  • Lazy Loading: Load configuration sections on-demand for large configs
  • Hot Reload: Use file watchers instead of polling for configuration changes

Monitoring

Configuration Audit Trail

import logging

logger = logging.getLogger(__name__)

def log_config_change(key: str, old_value, new_value):
 logger.info(f"Config changed: {key} = {old_value} {new_value}")

Configuration Drift Detection

# Compare production config against baseline
diff config.production.json config.baseline.json
  • mcp-schema-validation: Configuration schema validation
  • mcp-security-safeguards: Secure configuration handling
  • documentation-system: Configuration documentation

Safeguards

  1. Validation: All configuration validated on load
  2. Type Safety: Strong typing with Pydantic
  3. Bounds Checking: Port ranges, worker counts validated
  4. Secret Management: Environment variables for sensitive data
  5. Error Handling: Graceful degradation with defaults

Last Updated: 2025-12-09 Capability ID: mcp-configuration