High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub MCP Server connects AI assistants to Infrahub using the Model Context Protocol (MCP). It provides a structured, audited interface for agents to read and modify infrastructure state. The system acts as a trust boundary, enforcing security, authentication, and branch isolation between AI clients and the Infrahub backend.
The architecture centers on a Python 3.13 runtime utilizing FastMCP and the Infrahub SDK. It organizes logic into tools, resources, and prompts, protected by a comprehensive 17-layer middleware stack.
Sources: GPT.md:3-7, dev/constitution.md:120-125, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:5-9
System Components
The server consists of several core modules that handle configuration, request processing, and Infrahub integration.
Core Architecture Components
| Component | Description |
|---|---|
| FastMCP Server | The primary entry point that manages the MCP protocol and mounts sub-applications. |
| Infrahub SDK | The authoritative client for all Infrahub API operations, including GraphQL and node operations. |
| Middleware Stack | A 17-layer chain composed at startup to handle logging, auth, caching, and rate limiting. |
| AppContext | An immutable container for the SDK client and ServerConfig, shared via the application lifespan. |
| Tools | Executable functions (e.g., node_upsert, find_paths) that agents call to perform actions. |
| Resources | Structured data (e.g., infrahub://schema) exposed via URI templates. |
Sources: GPT.md:12-22, dev/constitution.md:43-52, specs/archive/20260421-144953-production-ready-mcp-server/plan.md:10-15
Data Flow Diagram
The following diagram illustrates how an AI agent request flows through the server layers to Infrahub.
Middleware Stack
The server utilizes a strictly ordered 17-layer middleware stack composed once at startup. This stack provides observability, resilience, and security.
Middleware Layers (Outermost to Innermost)
- RequestId: Assigns a unique ID to every operation.
- Metrics / OTelTracing: Observability and Prometheus metrics.
- StructuredLogging / DetailedTiming: JSON logs for request duration and token estimates.
- ErrorHandling: Translates internal failures to MCP-standard errors.
- InfrahubConnection / Retry: Manages SDK connectivity and transient failures.
- RateLimiting: Token-bucket algorithm enforcing request limits.
- ResponseCaching: Caches schema and list operations.
- Auth / TokenPassthrough: Enforces OIDC or credential passthrough.
- ReadOnly: Blocks tools tagged
"write"if the server is in read-only mode. - Audit: Emits structured JSON logs for write operations.
- ResponseLimiting: Prevents oversized responses from overwhelming client context windows.
Sources: dev/knowledge/architecture.md, specs/archive/20260421-144953-production-ready-mcp-server/plan.md:78-95, dev/constitution.md:127-140
Authentication and Security
The server acts as a security boundary, ensuring credentials never leak into logs or global state.
Authentication Modes
The server supports four distinct authentication modes, validated at startup via ServerConfig.
| Mode | Implementation | Use Case |
|---|---|---|
| none | Uses environment variable credentials. | Development and local testing. |
| token-passthrough | Extracts Bearer token from HTTP headers. | Per-user identity via API tokens. |
| basic-passthrough | Extracts credentials from Basic Auth headers. | Delegated authentication. |
| oidc | Full OAuth 2.0 flow via OIDC proxy. | Enterprise production deployments. |
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:55-75, dev/constitution.md:95-110
Security Sequence: Token Passthrough
Branch Safety and Recovery
Infrastructure safety is maintained through Branch-Safe by Default operations. Write operations are isolated to session branches to prevent accidental modification of the default branch.
Branch Management Logic
- Lazy Creation: Session branches are created only on the first write operation.
- Isolation: The
AppContextmaintains aWeakKeyDictionaryof session branches keyed by the MCP session object. - Automatic Recovery: If a session branch is merged or deleted, the server proactively detects the
MERGEDorDELETINGstatus viaBranchData.status. It then clears the session cache and recreates a fresh branch. - Validation: Branch names must conform to the configured
branch_pattern(supporting{date},{hex}, and{user}placeholders).
Sources: dev/constitution.md:62-75, specs/archive/20260604-141223-session-branch-recovery/plan.md:10-25, specs/archive/20260604-141223-session-branch-recovery/tasks.md:15-30
Tooling and Capabilities
The server exposes specialized tools for infrastructure management.
Graph Traversal Tools
Introduced for Infrahub 1.10+, these tools allow agents to discover relationships without building complex GraphQL queries.
find_paths: Locates the shortest path between two nodes.find_reachable: Performs impact analysis by finding dependent nodes.
Data Management Tools
node_upsert: Creates or updates nodes on the session branch.propose_changes: Opens aCoreProposedChangeto merge session branch work into the default branch.reset_session_branch: Explicitly clears or switches the active session branch.
Sources: CAPABILITIES.md:20-60, specs/archive/20260604-141223-session-branch-recovery/plan.md:15-20
The Infrahub MCP Server provides a production-ready bridge to infrastructure data by combining the MCP standard with rigorous middleware enforcement and session-based branch isolation. This architecture ensures that AI agents can interact with production systems while maintaining high standards of security and auditability.