Write Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Write Tool module provides a set of Model Context Protocol (MCP) tools that enable AI agents to modify infrastructure state within Infrahub. It enforces a "Branch-Safe by Default" principle, ensuring that all write operations occur within isolated session branches rather than modifying the default branch directly.
This module works in conjunction with the Session Management logic to automatically provision and recover branches during infrastructure mutations. It supports operations such as node creation, updates, deletions, and GraphQL mutations.
Sources: dev/constitution.md:46-48, GPT.md:12, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:68-70
Architecture and Design Principles
The Write Tool architecture prioritizes safety and auditability through several core mechanisms:
- Write Tagging: All tools capable of modifying state are explicitly tagged with
"write". This allows the server to programmatically block write operations whenread_only=trueis configured. - Branch Isolation: The system automatically creates session branches for writes. It blocks direct writes to the default branch (e.g.,
main) to prevent accidental production impact. - Privileged Mutation Guard: The tool rejects specific GraphQL mutations that attempt to bypass safety gates, such as branch management (
BranchMerge) or schema modifications. - Reactive Recovery: If a write fails because a session branch was merged or deleted, the tool clears the cached session state to allow a fresh branch to be provisioned on the next attempt.
Sources: dev/constitution.md:27-28, dev/constitution.md:55-57, specs/archive/20260604-141223-session-branch-recovery/tasks.md:118-124, src/infrahub_mcp/tools/write.py:317-330
Write Operation Flow
The following diagram illustrates the lifecycle of a write request, from validation to branch resolution and SDK execution.
The diagram shows how the system validates the read-only state and branch health before delegating the mutation to the Infrahub SDK.
Sources: src/infrahub_mcp/tools/write.py, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:68-100
Available Write Tools
The module exposes several distinct tools for different types of infrastructure mutations.
| Tool Name | Description | Key Parameters |
|---|---|---|
node_upsert | Creates or updates a node of a specific kind. | kind, data |
node_delete | Removes a specific node from Infrahub. | kind, id |
mutate_graphql | Executes a raw GraphQL mutation against the session branch. | query, variables |
propose_changes | Creates a proposed change (Pull Request) from the session branch to the target branch. | description, target |
reset_session_branch | Clears or overrides the current session's isolated branch. | branch (optional) |
Sources: src/infrahub_mcp/tools/write.py:73, src/infrahub_mcp/tools/write.py:126, src/infrahub_mcp/tools/write.py:165, specs/archive/20260604-141223-session-branch-recovery/tasks.md:68-75
Proposing Changes
The propose_changes tool acts as the human-in-the-loop review gate. Once an agent has completed modifications in a session branch, this tool is used to initiate the review process within Infrahub.
This sequence demonstrates how session branches are converted into formal proposed changes for review.
Sources: src/infrahub_mcp/tools/write.py:275-306, dev/constitution.md:46-51
Safety Mechanisms
Read-Only Mode (Defense-in-Depth)
The ReadOnlyMiddleware and tool tagging ensure write operations are disabled at multiple layers. When INFRAHUB_MCP_READ_ONLY=true is set, tools tagged with "write" are hidden from discovery and rejected if called by name.
Sources: specs/archive/20260421-144953-production-ready-mcp-server/spec.md:58-66, dev/constitution.md:55-57
Mutation Hardening
To maintain the integrity of the MCP server's management of branches, the mutate_graphql tool implements a recursion-aware scanner to block privileged operations.
# Implementation detail from src/infrahub_mcp/tools/write.py
def _assert_no_privileged_mutations(query: str) -> None:
"""Rejects mutations that bypass branch safety or modify schema."""
# Logic scans field names recursively for:
# - BranchMerge, BranchDelete, BranchCreate
# - SchemaDropdown, SchemaEnum
Sources: specs/archive/20260604-141223-session-branch-recovery/tasks.md:118-124, src/infrahub_mcp/tools/write.py:317-330
Reactive Recovery Logic
If a write operation encounters a GraphQLError indicating that the target branch is read-only (often because it was just merged), the system clears the session's branch cache. This ensures the next write operation will trigger the creation of a new, writable session branch.
Sources: specs/archive/20260604-141223-session-branch-recovery/tasks.md:46-53, src/infrahub_mcp/tools/write.py:335-345
Integration Testing
The write tool is verified through integration tests using infrahub-testcontainers. These tests ensure that:
node_upsertcorrectly creates nodes in a branch.- Writes do not leak into the
mainbranch. - Write operations are rejected when the server is reloaded in
read_only=truemode.
Sources: tests/integration/test_write_tool.py:15-30, specs/001-infrahub-testcontainers/tasks.md:48-52
Summary
The Write Tool provides the necessary interface for AI-driven infrastructure mutations while enforcing strict safety boundaries. By isolating changes to session branches and providing a review-based promotion workflow via propose_changes, it mitigates the risk of direct production impact. The implementation includes proactive status checks and reactive recovery to maintain high availability of the write path during branch lifecycle events.