Skip to main content
Glama
opsmill

infrahub-mcp

Official
by opsmill
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Node Upsert

node_upsert

Create or update a node in Infrahub on the active session branch. Supply id or hfid to update; omit both to create. Use propose_changes to open a review.

Instructions

Create or update a node in Infrahub on the active session branch.

The session branch is auto-created on the first write of the session (mcp/session-YYYYMMDD-<hex>). Use propose_changes to open a review once your changes are ready. To discover available kinds and attributes, read the infrahub://schema resource. If your client does not support MCP resources, call the get_schema tool instead.

  • Create: omit both id and hfid.

  • Update: supply either id or hfid to identify the target node.

Only scalar attribute fields are accepted in data. To set relationship fields, use mutate_graphql with an appropriate GraphQL mutation.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoUUID of an existing node to update. Omit to create a new node.
dataYesFlat {attribute: value} map. See infrahub://schema/{kind} for valid names. Scalar attributes only; use mutate_graphql for relationships.
hfidNoHuman-friendly ID of an existing node to update, as a list of string segments. Omit to create a new node.
kindYesKind of the node to create or update. Check infrahub://schema.

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. First observedv1.1.5

TDQS

A4.6/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the write/non-destructive profile is already structured. The description adds real contextual behavior beyond that: a session branch is auto-created on the first write with a concrete naming pattern, and changes require propose_changes to enter review. It does not describe error/validation behavior or what the call returns, so it falls short of a 5.

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

Conciseness5/5

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

Front-loaded with the core verb and scope, then usage flow, then discovery, then the two create/update bullets. Bullets and code spans make it scannable, and every sentence carries operational information – no filler or restatement of the name.

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

Completeness4/5

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

For a mutation tool with no output schema, the description covers the essentials: write target, session branch semantics, create vs update identification, and the escape hatch to mutate_graphql. It still omits the shape of the success response and failure modes (e.g., schema validation errors, id/hfid both supplied), leaving a small gap.

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%, so the baseline is 3; the schema already documents id, hfid, data and kind individually. The description still adds meaning beyond the schema by framing id and hfid as mutually alternative identifiers for update (the schema documents each in isolation but not the either/or relationship) and by reinforcing the scalar-only constraint on data.

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?

The opening sentence gives a specific verb (create or update) and resource (node in Infrahub), and immediately localizes the operation to the active session branch. It further distinguishes the two modes and names the sibling (mutate_graphql) reserved for relationship fields, so an agent can separate this from query_graphql/mutate_graphql without opening a 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?

Explicit decision rules are provided: omit id and hfid to create, supply either to update. It also routes to alternatives with conditions – propose_changes once changes are ready, mutate_graphql for relationships, and the infrahub://schema resource or get_schema tool for discovery. Nothing about when/when-not is left to inference.

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