Configuration and Environment
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub MCP server uses a centralized configuration system to manage its operational behavior, security settings, and integration with Infrahub. Configuration is driven by environment variables and validated at the system boundary to ensure a fail-fast startup when settings are incorrect or incomplete.
This system manages critical parameters such as authentication modes, read-only restrictions, branch naming conventions, and observability features like logging and metrics. By centralizing these settings, the project maintains a consistent security posture and operational interface across different deployment environments.
Sources: dev/adr/0006-config-validation-at-boundary.md, GPT.md
Configuration Architecture
The configuration system follows the "Configuration Validation at Boundary" pattern. The server loads all settings into a ServerConfig object via pydantic-settings at startup. This approach ensures that internal components can trust the validated data, reducing the need for repetitive checks throughout the codebase.
Data Flow and Validation
The following diagram illustrates the flow of configuration from environment variables to the internal server components.
The server fails fast with clear error messages if the environment variables do not meet the defined constraints.
Sources: dev/adr/0006-config-validation-at-boundary.md, dev/constitution.md: Principle IV, specs/archive/20260421-144953-production-ready-mcp-server/spec.md: FR-033
Environment Variables and Options
All configuration is loaded from environment variables prefixed with INFRAHUB_MCP_. These settings control the primary functionality of the server.
Core Server Settings
| Variable Name | Type | Description |
|---|---|---|
INFRAHUB_MCP_READ_ONLY | bool | Blocks all tools tagged "write" when set to true. |
INFRAHUB_MCP_BRANCH_PATTERN | str | Pattern for auto-branching (supports {date}, {hex}, {user}). |
INFRAHUB_MCP_MAX_BRANCH_RETRIES | int | Maximum attempts to create a branch on name collision. |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md: FR-017, FR-021, FR-023, GPT.md
Authentication Configuration
The server supports four distinct authentication modes, which must be validated as complete sets at startup. Partial OIDC configurations are rejected.
| Mode | Description |
|---|---|
none | Development mode using shared environment variable credentials. |
oidc | Production mode handling full OAuth 2.0 / OIDC flows. |
token-passthrough | Extracts Bearer tokens from configurable HTTP headers. |
basic-passthrough | Uses Infrahub username/password from Basic auth headers. |
Sources: dev/constitution.md: Principle VI, specs/archive/20260421-144953-production-ready-mcp-server/spec.md: FR-010
Observability and Performance
| Variable Name | Type | Description |
|---|---|---|
INFRAHUB_MCP_LOG_LEVEL | str | Sets the severity level for structured JSON logs. |
INFRAHUB_MCP_PROMETHEUS_ENABLED | bool | Enables the /metrics endpoint for Prometheus. |
INFRAHUB_MCP_OTEL_ENABLED | bool | Enables OpenTelemetry tracing for middleware and tools. |
INFRAHUB_MCP_RATE_LIMIT_RPS | int | Token-bucket requests per second limit. |
INFRAHUB_MCP_CACHE_ENABLED | bool | Enables response caching for schema and list operations. |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md: FR-003, FR-004, FR-006, FR-009, dev/constitution.md: Performance Standards
Security Boundaries
Security is enforced through specific configuration constraints to prevent data corruption or unauthorized access.
- Branch Safety: Write operations are isolated to session branches by default to protect the
mainbranch. - Credential Isolation: Credentials processed during passthrough authentication are stored in
ContextVarfor per-request isolation and are never logged. - Startup Fail-Fast: OIDC configuration must be complete; if any required fields are missing, the server will not start.
Sources: dev/constitution.md: Principle III, VI, specs/archive/20260421-144953-production-ready-mcp-server/spec.md: FR-015
Conclusion
The configuration and environment management system provides a robust foundation for the Infrahub MCP server. By utilizing strict validation at the entry boundary and leveraging environment variables for all operational toggles, the system ensures that security principles like branch-safety and credential isolation are consistently applied. This architecture allows operators to confidently deploy the server in varied environments ranging from local development to production-scale infrastructure.