Middleware Stack
Relevant source files
The following files were used as context for generating this wiki page:
The Middleware Stack in the Infrahub MCP server intercepts every tool call and resource read to enforce cross-cutting concerns. It handles observability, security, resilience, and operational controls through a chain of interceptors. The system composes the stack once at startup, ensuring a predictable and debuggable execution order for all requests.
Sources: dev/adr/0002-middleware-stack-ordering.md, dev/knowledge/architecture.md
Stack Composition and Initialization
The server utilizes a 17-layer middleware stack composed via configure_middleware() in middleware.py. Activation of specific layers depends on flags defined in ServerConfig. The initialization process follows a specific sequence during server startup where sub-applications are mounted before middleware is attached.
Sources: dev/knowledge/architecture.md, src/infrahub_mcp/server.py
Request Flow and Ordering
The stack is ordered from outermost (first to execute) to innermost (closest to the tool execution). This ensures that observability layers wrap the entire request lifecycle, including potential retries or authentication failures.
The diagram shows the sequential execution of the 17-layer middleware stack from request arrival to tool execution.
Sources: dev/adr/0002-middleware-stack-ordering.md, dev/knowledge/architecture.md
Functional Categories
Middleware layers are grouped into four primary functional categories: Observability, Resilience, Security, and Operational.
Observability Layers
These layers provide structured data for monitoring and debugging.
- RequestIdMiddleware: Assigns a unique correlation ID to each operation, propagated via
ContextVar. - MetricsMiddleware: Exposes Prometheus counters and histograms.
- OTelTracingMiddleware: Creates OpenTelemetry spans for request tracing.
- StructuredLoggingMiddleware: Emits JSON-formatted logs containing request IDs, tool names, and durations.
- DetailedTimingMiddleware: Tracks per-operation timing breakdowns.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:FR-001-FR-005, dev/adr/0002-middleware-stack-ordering.md
Resilience and Error Handling
These layers manage failures and backend connectivity.
- ErrorHandlingMiddleware: Translates internal exceptions into MCP-standard error codes.
- InfrahubConnectionMiddleware: Handles SDK connection errors specifically.
- RetryMiddleware: Implements transient failure retries with configurable backoff.
- RateLimitingMiddleware: Uses a token-bucket algorithm to throttle requests based on
rate_limit_rpsandrate_limit_burst.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:FR-006, FR-008, dev/adr/0002-middleware-stack-ordering.md
Security and Audit
These layers enforce access controls and track sensitive operations.
- AuthMiddleware: Enforces OIDC scopes, particularly for write operations.
- TokenPassthroughMiddleware: Ensures credential presence in passthrough authentication modes.
- ReadOnlyMiddleware: Filters tools tagged with
"write"and blocks execution ifread_only=true. - AuditMiddleware: Emits structured audit logs for write operations, authentication outcomes, and access denials.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:FR-010-FR-020, FR-030, dev/knowledge/architecture.md
Operational and Protocol
These layers handle protocol-level concerns and optimization.
- ResponseCachingMiddleware: Caches schema and list operations using TTL-based logic.
- DereferenceRefsMiddleware: Resolves
$refpointers within JSON Schemas. - PingMiddleware: Maintains HTTP session keep-alive.
- ResponseLimitingMiddleware: Acts as the innermost layer to control and truncate oversized responses.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:FR-007, FR-009, dev/adr/0002-middleware-stack-ordering.md
Middleware Configuration Table
The activation and behavior of the stack are controlled by the ServerConfig.
| Middleware | Configuration Flag | Purpose |
|---|---|---|
MetricsMiddleware | prometheus_enabled | Exposes /metrics endpoint |
OTelTracingMiddleware | otel_enabled | Enables OpenTelemetry tracing |
ResponseCachingMiddleware | cache_enabled | Caches schema/list operations |
ReadOnlyMiddleware | read_only | Blocks write-tagged tools |
RateLimitingMiddleware | rate_limit_rps | Throttles request rates |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:FR-032, dev/adr/0002-middleware-stack-ordering.md
Implementation Details
The stack composition is centralized in middleware.py to ensure explicit ordering. Each middleware class is added to the FastMCP server instance using the add_middleware() pattern.
# Illustrative composition pattern in middleware.py
def configure_middleware(mcp: FastMCP, config: ServerConfig):
mcp.add_middleware(RequestIdMiddleware())
if config.prometheus_enabled:
mcp.add_middleware(MetricsMiddleware())
# ... remaining stack layers ...
mcp.add_middleware(ResponseLimitingMiddleware(limit=config.max_response_size))
Sources: dev/adr/0002-middleware-stack-ordering.md, specs/archive/20260421-144953-production-ready-mcp-server/plan.md:Phase 2
Summary
The Middleware Stack provides the operational foundation for the Infrahub MCP server. By using a strictly ordered 17-layer chain, the system ensures that security, observability, and resilience are applied consistently across all tools. The centralized configuration in middleware.py allows for precise control over the request lifecycle while maintaining alignment with the ServerConfig.