Introduction to Infrahub MCP
Relevant source files
The following files were used as context for generating this wiki page:
Infrahub MCP (Model Context Protocol) Server connects AI assistants and IDE agents to the Infrahub infrastructure data management platform. It allows agents to read and optionally modify infrastructure state through a consistent, audited, and human-approved interface. The server implements the open MCP standard, enabling interoperability with compatible clients like Claude Desktop, VS Code, and Cursor without custom integration code.
Sources: README.md:3-8, GPT.md:3-5, dev/constitution.md:27-30
System Architecture
The Infrahub MCP Server is built using Python 3.13 and the FastMCP framework. It acts as a bridge between AI clients and the Infrahub SDK, enforcing safety boundaries such as branch isolation and read-only modes.
The diagram shows the request flow from the AI client through the MCP server's middleware and tools to the Infrahub backend via the SDK.
Sources: GPT.md:7-9, src/infrahub_mcp/server.py:90-95, dev/constitution.md:44-48
Core Components
The server organizes its functionality into three primary MCP object types:
- Tools: Executable functions that allow agents to query or modify data (e.g.,
get_nodes,node_upsert). - Resources: Structured data exposed via URI templates for schema discovery and branch listing.
- Prompts: Templates that guide AI interactions with Infrahub.
Sources: GPT.md:46-50, CAPABILITIES.md:12-455
Security and Safety Principles
Infrahub MCP operates on a "Branch-Safe by Default" principle. The server prevents direct modification of the default infrastructure branch to ensure stability.
Branch Isolation
Write operations target auto-created session branches (e.g., mcp/session-YYYYMMDD-<hex>). Changes only reach the default branch after a human approves a Proposed Change.
Sources: dev/constitution.md:57-65, README.md:35-37
Middleware Stack
The server employs a 17-layer middleware stack configured at startup. This stack handles logging, caching, authentication, rate limiting, and audit requirements.
Sources: GPT.md:52-57, src/infrahub_mcp/server.py:100-101, dev/constitution.md:118-125
Authentication Modes
The server supports four primary authentication modes to manage identity and access:
| Mode | Description |
|---|---|
none | Development mode using shared environment credentials. |
oidc | Production mode using OpenID Connect JWT validation. |
token-passthrough | Extracts Bearer tokens from client HTTP headers. |
basic-passthrough | Extracts username/password from Basic auth headers. |
Sources: src/infrahub_mcp/server.py:270-275, dev/constitution.md:97-104
Technical Stack and Operations
The project uses modern Python tooling for development and deployment.
- Runtime: Python 3.13, Starlette, Pydantic 2.
- Package Management:
uvis the authoritative manager for dependencies and execution. - SDK Integration: All operations must use the
infrahub-sdk; direct HTTP calls to Infrahub are forbidden. - Observability: The server exposes
/healthand/metrics(Prometheus) endpoints for monitoring.
Sources: GPT.md:7-12, src/infrahub_mcp/server.py:104-125, dev/constitution.md:44-46
Server Initialization Flow
The sequence diagram illustrates the startup and validation sequence required for the server to reach a ready state.
Sources: src/infrahub_mcp/server.py:68-142, dev/constitution.md:90-93
Summary
Infrahub MCP Server provides a secure, standard-compliant gateway for AI agents to interact with infrastructure data. By enforcing branch isolation and utilizing a robust middleware stack, it ensures that AI-driven changes are audited and safe for production environments. Developers interact with the system via uv commands and follow a constitution-governed workflow to maintain high code quality and security standards.
Sources: README.md:3-10, dev/constitution.md:10-25, dev/README.md:1-15