Execute a read-only GraphQL query against Infrahub — use for reads only, never mutations.

Mutations are rejected at the AST level: use mutate_graphql instead (available when write mode is enabled). For simple attribute reads, prefer get_nodes / search_nodes — use GraphQL only when you need relationship traversal, aggregation, or fields not exposed by the typed tools.

To discover available kinds and their attributes, read the infrahub://schema resource. If your client does not support MCP resources, call the get_schema tool instead. For the full GraphQL SDL, read infrahub://graphql-schema.

List nodes of a specific kind — the default read path for typed queries with optional filtering and pagination.

Prefer this over query_graphql when you just need objects of one kind: results come back as display labels (fast, token-cheap) or full attribute dicts (include_attributes=True).

To discover available kinds, read the infrahub://schema resource. If your client does not support MCP resources, call the get_schema tool instead. To discover available filters for a kind, read infrahub://schema/{kind} or call get_schema(kind='...').

Filter keys follow the schema's filter map. Attribute filters use <attr>__value (e.g. {"name__value": "atl1"}) and relationship filters chain via <rel>__<attr>__value (e.g. {"site__name__value": "atl1"}). See infrahub://schema/{kind} for the full list of valid keys.

Use offset and limit to page through large result sets. The response always includes total_count and has_more so you know when to stop.

Find a node of a specific kind by partial name — use when you only know part of the name.

Matches substrings against the name attribute only (via name__value with partial_match=True). For matching on other attributes, or for combining multiple filters, use get_nodes with an explicit filters dict instead.

To discover available kinds, read the infrahub://schema resource. If your client does not support MCP resources, call the get_schema tool instead.

Return the current MCP session state — call before writes to know which branch they target.

Reports the active session branch (if any) and the Infrahub instance address. A session branch is lazily auto-created on the first write tool call (node_upsert / node_delete / mutate_graphql) and is named mcp/session-YYYYMMDD-<hex>. Before that first write, session_branch is None and all read tools target the default branch.

Typical uses:

• Confirm which branch a proposed change would merge from.

• Decide whether a write is about to open a new session branch.

• Display the active branch to the user.

Returns: Dict with session_branch (str or null), infrahub_address, and has_session_branch.

Discover available schema kinds — call this first when you don't know what kinds or filters exist.

Without a kind, returns the catalog of all kinds (compact JSON). With a kind, returns its attributes, relationships, and the full set of filter keys accepted by get_nodes (TOON-encoded for token efficiency).

Prefer reading the infrahub://schema resource if your client supports MCP resources — this tool provides the same data for clients that don't.

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.

Delete a node in Infrahub on the active session branch.

The deletion is applied to the session branch only and is not visible on the default branch until a proposed change is merged. To discover available kinds, read the infrahub://schema resource. If your client does not support MCP resources, call the get_schema tool instead.

Open a proposed change (pull request) from the active session branch to the default branch.

Creates a CoreProposedChange in Infrahub so a human can review, approve, and merge the changes made during this session. The session branch remains active after calling this — you can continue making changes.

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 targets the session branch by default, which is auto-created on the first write of the session (mcp/session-YYYYMMDD-<hex>).

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.