MCP Prompts
Relevant source files
The following files were used as context for generating this wiki page:
MCP Prompts provide parameterized workflow guides and system instructions for AI assistants interacting with Infrahub. These prompts define the operational boundaries, data formats, and standard workflows that an agent must follow to manage infrastructure safely and efficiently.
The project implements these prompts using the FastMCP framework. They serve as self-documenting templates that guide the AI assistant's interaction with the Infrahub platform, covering discovery, read, and write operations.
Sources: src/infrahub_mcp/server.py:165-270, dev/constitution.md:33-35, GPT.md:58-62
Architecture and Implementation
The prompt system is organized into distinct templates registered with the FastMCP server. Each prompt defines a specific role or workflow for the AI agent.
Prompt Registration
Individual prompt modules create their own FastMCP instances. The main server then mounts these instances to aggregate all available prompts.
Sources: dev/guidelines/python.md:27-30, src/infrahub_mcp/server.py:276-277
Role-Based Logic
The server dynamically adjusts prompt content based on the server configuration. For instance, if read_only mode is active, the system prompt explicitly informs the agent that write operations are disabled and hides documentation for write-tagged tools.
Sources: src/infrahub_mcp/server.py:167-175, src/infrahub_mcp/server.py:258-268
The diagram shows how the ServerConfig influences the generation of the system prompt delivered to the AI assistant.
Sources: src/infrahub_mcp/server.py:167-270
Core Prompts
The Infrahub MCP Server exposes several standard prompts to guide agent behavior.
| Prompt Name | Description |
|---|---|
infrahub_agent | The primary system prompt for infrastructure specialists. |
answer_infra_question | A read-only pipeline for answering infrastructure questions. |
make_infra_change | A write-enabled workflow for modifying infrastructure. |
explore_schema | A discovery-focused prompt for exploring the data model. |
Sources: CAPABILITIES.md:276-298, src/infrahub_mcp/server.py:165-270
The System Prompt (infrahub_agent)
The infrahub_agent prompt acts as the primary instruction set for the AI. It covers several critical areas:
- Data Formats: Instructs the agent on TOON (Token-Oriented Object Notation), which reduces token usage by declaring field names once in a header followed by rows of values.
- Discovery Workflow: Mandates that agents read the
infrahub://schemaresource or callget_schema()before performing queries to avoid guessing kind names or filter keys. - Safety Rules: Enforces branch-safe behavior, requiring that the default branch never be modified directly.
- Recovery: Explains that session branches are auto-recovered if they are merged or deleted.
Sources: src/infrahub_mcp/server.py:177-256
Write Workflow and Branch Safety
Prompts instruct agents on the mandatory branch-per-session workflow. All write operations are isolated to session branches created automatically on the first write attempt.
This diagram illustrates the branch-safe workflow enforced by the prompt instructions.
Sources: src/infrahub_mcp/server.py:240-254, dev/constitution.md:65-71
Prompt Content for Writes
If the server is not in read-only mode, the prompt includes detailed instructions for:
node_upsert/node_delete: Managing individual nodes.mutate_graphql: Performing complex writes.propose_changes: Submitting work for human review via a pull request.reset_session_branch: Manually switching or resetting the active session branch.
Sources: src/infrahub_mcp/server.py:230-247
Development Guidelines
When creating or modifying prompts, follow these project-specific rules:
- Type Safety: Functions generating prompts must have full type annotations.
- Docstrings: Every prompt function must have a docstring that serves as the prompt's description in the MCP catalog.
- Placement: Prompts should be defined in
src/infrahub_mcp/prompts/and mounted in the main server lifespan.
Sources: dev/guidelines/python.md:12-14, dev/guidelines/python.md:27-30, GPT.md:56-62
MCP Prompts ensure that AI agents operate within Infrahub's audited, human-approved interface by providing clear instructions on data structures, schema discovery, and branch-safe mutation workflows.