Quickstart Guide

Relevant source files

The following files were used as context for generating this wiki page:

• GPT.md
• dev/README.md
• dev/constitution.md
• pyproject.toml
• src/infrahub_mcp/server.py
• specs/archive/20260421-144953-production-ready-mcp-server/spec.md

This guide provides the essential steps for setting up, configuring, and operating the Infrahub MCP Server. The server connects AI assistants to Infrahub using the Model Context Protocol (MCP), allowing agents to read and modify infrastructure state through a secure, audited interface.

Sources: GPT.md:3-5, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:9-10

Initial Setup

The Infrahub MCP Server uses uv for dependency management and Python 3.13 as the runtime environment.

Prerequisites

1. Python 3.13+: Ensure your environment meets the minimum version requirement.
2. uv: Install the uv package manager for dependency resolution.
3. Docker: Required for running the integration test suite.

Sources: pyproject.toml:5-7, GPT.md:7-12, specs/001-infrahub-testcontainers/plan.md:33-35

Installation Steps

1. Clone the repository and sync dependencies:

   uv sync
   

2. Install pre-commit hooks:

   uv run pre-commit install
   

Sources: GPT.md:32-34, GPT.md:47

Development Workflow

The project enforces strict quality gates through the invoke task runner and pytest.

Essential Commands

Command	Description
uv run pytest	Runs the full unit test suite.
uv run pytest -m integration	Runs integration tests against a real Infrahub container.
uv run invoke format	Auto-formats code using ruff.
uv run invoke lint	Runs all linters (ruff, mypy, pylint, yamllint).
uv run pre-commit run	Runs ruff and rumdl on staged files and mypy on src/.

Sources: GPT.md:36-47, pyproject.toml:34-36

Quality Gates

All code must pass these specific gates before being merged into the stable branch:

1. Dependencies: uv sync must be up to date.
2. Linting: Zero errors from ruff and mypy.
3. Testing: All unit and (if applicable) integration tests must pass.
4. Documentation: rumdl check must pass for Markdown files.

Sources: dev/constitution.md:144-150

Configuration

The server is configured via INFRAHUB_MCP_* environment variables, which are validated at startup using Pydantic.

Required Environment Variables

If you are not using passthrough authentication, you must set the following:

• INFRAHUB_ADDRESS: The URL of the Infrahub instance (e.g., http://localhost:8000).
• INFRAHUB_API_TOKEN: The API token for authentication.
• OR INFRAHUB_USERNAME and INFRAHUB_PASSWORD.

Sources: src/infrahub_mcp/server.py:53-73, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:245-249

Authentication Modes

The server supports four primary authentication modes:

Mode	Description
none	Used for development; relies on shared environment credentials.
oidc	Production mode using OpenID Connect for JWT validation.
token-passthrough	Extracts Bearer tokens from HTTP headers for SDK calls.
basic-passthrough	Extracts Basic auth credentials for per-request SDK clients.

Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:188-195, src/infrahub_mcp/server.py:240-256

Server Architecture

The server architecture follows a layered approach, composed at startup.

The diagram shows the request flow from an AI client through the transport and middleware layers to the Infrahub SDK.
Sources: src/infrahub_mcp/server.py:84-121, GPT.md:85-90, dev/constitution.md:45-55

Branching and Safety

To prevent accidental data corruption, all write operations are isolated by default.

1. Read-Only Mode: Set INFRAHUB_MCP_READ_ONLY=true to hide and disable all tools tagged "write".
2. Session Branches: Write operations target an auto-created session branch (e.g., mcp/session-20260421-a3f2).
3. Propose Changes: Use the propose_changes tool to create a reviewable PR in Infrahub to merge session data into the default branch.

Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:144-162, dev/constitution.md:60-70

Changelog Management

The project uses towncrier to manage changes and prevent merge conflicts in CHANGELOG.md.

1. Create a news fragment for every PR:

   uv run towncrier create -c "Description of change" <issue_number>.<type>.md
   

2. Fragment Types: security, removed, deprecated, added, changed, fixed, housekeeping.
3. Draft Preview:

   uv run towncrier build --draft --version X.Y.Z
   

Sources: GPT.md:57-70, pyproject.toml:167-205

This Quickstart Guide provides the foundation for interacting with the Infrahub MCP Server. For detailed architectural decisions, refer to the ADR index. For specific coding standards, see the Python guidelines.

Sources: dev/README.md:15-22