Server and ASGI Application
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 operates as a Python 3.13 application built on FastMCP and Starlette, providing a consistent interface for reading and modifying infrastructure state. The system utilizes an ASGI application wrapper to handle HTTP-level concerns such as authentication passthrough and health monitoring.
Sources: GPT.md:1-5, src/infrahub_mcp/server.py:1-40, dev/knowledge/architecture.md:5-10
Server Architecture and Lifecycle
The server follows a composition pattern where a main FastMCP instance mounts multiple sub-applications for tools, resources, and prompts. This modular approach separates functionality into discrete domains like node operations, schema introspection, and session management.
Initialization Flow
The server initializes through a structured sequence that ensures environment validity before accepting requests.
- Configuration Loading: The system reads
INFRAHUB_MCP_*environment variables into a frozenServerConfigobject. - Auth Provisioning: It creates an OIDC provider if the authentication mode is set to
oidc. - App Construction: The
FastMCPinstance is created with specific versioning and lifespan handlers. - Middleware Attachment: A 17-layer middleware stack is composed once at startup.
- ASGI Wrapping: The core application is wrapped in ASGI middleware for HTTP-specific logic.
Sources: dev/knowledge/architecture.md:7-14, src/infrahub_mcp/server.py:46-77
Server Lifecycle Diagram
The following diagram illustrates the startup and lifespan sequence of the Infrahub MCP server.
ASGI Middleware Layer
The ASGI layer intercepts HTTP requests to handle cross-cutting concerns that exist outside the standard MCP protocol flow. This layer is primarily used when the server is accessed via HTTP (Streamable HTTP) rather than stdio.
Credentials Passthrough
The _CredentialsPassthroughASGI middleware extracts caller credentials from HTTP headers and stores them in a ContextVar. This enables the server to operate under the user's identity rather than a shared service account. It recognizes two primary header shapes:
Bearer <token>: Extracted into a token ContextVar.Basic <base64>: Decoded into username and password ContextVars.
Sources: src/infrahub_mcp/server.py:279-318, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:104-118
OAuth and OIDC Interception
The _OAuthDiscoveryInterceptASGI middleware prevents client-side errors by intercepting OAuth/OIDC discovery probes. It returns well-formed JSON 404 responses for paths like /.well-known/oauth-authorization-server when OIDC is not enabled, preventing syntax errors in AI clients that expect JSON but receive plain text.
Sources: src/infrahub_mcp/server.py:338-360, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:133-138
Operational Endpoints
The server exposes custom HTTP routes for monitoring and container orchestration.
Key API Endpoints
| Endpoint | Method | Purpose | Description |
|---|---|---|---|
/health | GET | Orchestration Probes | Verifies backend connectivity and server health. Returns 503 if Infrahub is unreachable. |
/metrics | GET | Monitoring | Returns Prometheus exposition format or JSON snapshots of latencies, request counts, and cache stats. |
Sources: src/infrahub_mcp/server.py:82-140, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:52-64
Health Check Sequence
The health check behavior changes based on the configured authentication mode to ensure accurate status reporting without leaking credentials.
Sub-Application Mounting
The server mounts specialized sub-applications to organize tools, resources, and prompts. This structure allows for granular control over which features are exposed, such as disabling write tools in read-only mode.
- Tools: Mounts
graphql_mcp,nodes_mcp,session_mcp,schema_tools_mcp, andtraversal_mcp. - Write Operations: The
write_mcpapp is only mounted ifread_onlyis set toFalsein the configuration. - Resources: Mounts
schema_resources_mcpandbranches_resources_mcpto expose Infrahub state as MCP resources. - Prompts: Mounts
prompts_mcpto provide pre-defined system prompts likeinfrahub_agent.
Sources: src/infrahub_mcp/server.py:262-275, dev/knowledge/architecture.md:58-75
Authentication Modes
The server supports four distinct authentication modes, which are validated at startup to ensure a secure boundary between AI agents and infrastructure.
| Auth Mode | Description |
|---|---|
none | Development mode; uses shared credentials from environment variables. |
oidc | Production mode; handles OAuth 2.0 flow via OIDCProxy. |
token-passthrough | Extracts Bearer token from HTTP headers for per-request identity. |
basic-passthrough | Extracts username/password from Basic auth headers for per-request identity. |
Sources: src/infrahub_mcp/server.py:49-62, dev/knowledge/architecture.md:77-87, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:104-124
Summary
The Server and ASGI Application layer provides the operational foundation for the Infrahub MCP Server. It manages the lifecycle of the FastMCP instance, enforces security through multiple authentication modes, and provides the necessary observability endpoints for production deployments. By isolating HTTP-level concerns in ASGI middleware, the server maintains protocol compliance while offering robust operational controls.
Sources: dev/knowledge/architecture.md:5-18, specs/archive/20260421-144953-production-ready-mcp-server/plan.md:15-28