Skip to main content
Glama
opsmill

infrahub-mcp

Official
by opsmill
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Mutate Graphql

mutate_graphql
Destructive

Execute GraphQL mutations on the active Infrahub session branch for relationship edits, bulk operations, or write shapes the typed tools cannot express.

Instructions

Execute a GraphQL mutation against Infrahub — use only for complex writes that typed tools can't express.

Prefer node_upsert (create/update scalar attributes) or node_delete (remove a node) for straightforward changes; they validate against the schema and produce clearer audit entries. Reach for mutate_graphql when you need relationship edits, bulk operations, or any mutation shape not covered by the typed tools. For reads, use query_graphql.

The mutation always runs on the active session branch (auto-created on the first write of the session, mcp/session-YYYYMMDD-<hex>). There is no branch override — writes are isolated to the session, and changes reach the default branch only through propose_changes and human review. To target a different branch deliberately, switch the session with reset_session_branch first. Branch- and schema-management mutations are rejected.

To discover available kinds and their attributes, read the infrahub://schema resource or call the get_schema tool. For the full GraphQL SDL, read infrahub://graphql-schema.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryYesGraphQL mutation to execute on the active session branch.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.0
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null
  2. Changed2 schema fields changedv1.1.6
    • removedInput schema / properties / branch
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "description": "Branch to execute the mutation against. Defaults to the auto-created session branch (recommended). Override only when targeting a specific non-default branch."
-}
    • changedInput schema / properties / query / description
      Previous value: -"GraphQL mutation to execute."New value: +"GraphQL mutation to execute on the active session branch."
  3. First observedv1.1.5

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: explains writes run on the auto-created session branch (mcp/session-YYYYMMDD-<hex>), that there is no branch override, that changes only reach the default branch via propose_changes plus human review, and that branch- and schema-management mutations are rejected. This is exactly the mutation-safety context an agent needs and that destructiveHint alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose, then alternatives, then the branching model, then discovery resources — a logical order with little filler. It is on the long side and the discovery pointers to infrahub://schema and infrahub://graphql-schema could arguably be trimmed, but each block carries actionable content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter mutation tool with no output schema and annotations covering only the safety profile, the description supplies the missing operational model: branch isolation, promotion path, rejection rules, and how to discover valid mutation shapes. Nothing an agent needs to call this correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single query parameter is already documented as targeting the active session branch, so the baseline is 3. The description adds real semantic constraints on what may be placed in that string — relationship edits, bulk ops, and no branch/schema-management mutations — which meaningfully narrows valid inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (execute a GraphQL mutation) and resource (Infrahub), and immediately scopes it as the escape hatch for complex writes typed tools cannot express. It names the siblings it is not (node_upsert, node_delete, query_graphql), so the agent can route without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use (relationship edits, bulk operations, uncovered mutation shapes), when-not-to (straightforward create/update/delete), and the exact alternatives for each case, plus a redirect to query_graphql for reads. Includes a prerequisite path (reset_session_branch) for targeting another branch.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools