GraphQL Tool
Relevant source files
The following files were used as context for generating this wiki page:
The GraphQL Tool provides a direct interface for executing GraphQL queries and mutations against an Infrahub instance. It allows AI assistants and standard MCP clients to perform complex data retrieval and infrastructure state modifications that are not covered by specialized typed tools.
This component acts as a gateway for advanced operations, supporting relationship traversal, aggregations, and bulk updates. It strictly adheres to the Infrahub SDK for all API communications and enforces branch safety by isolating write operations to session branches.
Sources: CAPABILITIES.md, dev/constitution.md:23-28, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:202-211
Architecture and Interaction Flow
The GraphQL Tool sits within the MCP server's tool layer. It receives GraphQL strings from the client, identifies whether the operation is a query or mutation, and routes it through the Infrahub SDK.
The diagram shows how the tool distinguishes between read-only queries and state-changing mutations, routing them to appropriate SDK methods.
Sources: src/infrahub_mcp/tools/gql.py, dev/constitution.md:29-33
Core Implementation Details
The system separates GraphQL execution into two primary functions: query_graphql for read operations and mutate_graphql for write operations.
Execution Functions
| Function | Purpose | Input Parameters | Safety Mechanism |
|---|---|---|---|
query_graphql | Executes read-only queries. | query (str), branch (str/null) | AST validation rejects mutations. |
mutate_graphql | Executes state-changing mutations. | query (str) | Isolated to active session branch. |
Sources: CAPABILITIES.md, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:202-211
Read Operations (Query)
The query_graphql tool is the primary method for relationship traversal and complex data retrieval. It requires a query string and an optional branch target. If no branch is specified, the system defaults to the main branch.
# Illustrative example of the query interface requirement
def query_graphql(
query: str,
branch: str | None = None,
) -> str:
"""Execute a read-only GraphQL query against Infrahub."""
...
Sources: src/infrahub_mcp/tools/gql.py, CAPABILITIES.md
Write Operations (Mutation)
The mutate_graphql tool handles complex writes, relationship edits, and bulk operations. Unlike queries, mutations always target the active session branch. This branch is named using the pattern mcp/session-YYYYMMDD-<hex>. Changes only reach the default branch when a user approves a proposed change.
Sources: CAPABILITIES.md, dev/constitution.md:41-47, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:202-211
Security and Constraints
The GraphQL Tool enforces several security boundaries to prevent unauthorized or accidental infrastructure changes:
- SDK Mandatory: The tool MUST use
infrahub-sdk. Direct HTTP calls to the Infrahub API are forbidden. - AST Validation: Read-only tools validate queries at the Abstract Syntax Tree (AST) level to ensure mutations are rejected.
- Tagging: All write operations are explicitly tagged with
"write". - Read-Only Mode: If the server is configured with
read_only=true, themutate_graphqltool is hidden from the tool catalog and its execution is blocked byReadOnlyMiddleware. - Branch Isolation: Writes are forbidden from modifying the default branch directly.
Sources: dev/constitution.md:23-50, specs/archive/20260421-144953-production-ready-mcp-server/spec.md:244-246
Integration and Testing
Integration tests verify the tool's behavior against live Infrahub environments. Tests ensure that valid queries return data and that mutations land on the correct branches.
The flow demonstrates the standard integration testing lifecycle for the GraphQL tool, ensuring branch safety and data integrity.
Sources: tests/integration/test_graphql_tool.py, specs/001-infrahub-testcontainers/tasks.md:65-72
Summary
The GraphQL Tool provides the most flexible way to interact with Infrahub data. By balancing this flexibility with strict AST validation, SDK-only integration, and mandatory session branching, the system ensures that AI-driven infrastructure management remains audited and safe.