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 nodes of a specific kind by partial substring — use when you only know part of a value.

Matches the query as a substring against all attributes of the kind via Infrahub's any__value filter with partial_match=True. Works uniformly on concrete kinds (e.g. LocationSite) and abstract/generic kinds (e.g. CoreNode) — agents can ping any kind without first checking whether it has a name attribute.

For a filter on one specific attribute (or combining multiple filters), use get_nodes with an explicit filters dict instead.

Each result is labelled with the node's display_label when present, falling back to its HFID (kind-prefixed) and finally its UUID — so generic-kind results that lack a display_label still return a human-readable identifier rather than a bare UUID.

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 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.

Reset or switch the active session branch for the current MCP session.

Use this to recover or take control of which branch your writes target:

• No branch — clears the cached session branch; the next write auto-creates a fresh one. Useful after you have merged your work and want to start a new change set.

• With branch — points this session at the named branch. If it does not exist and the name matches the configured branch pattern, it is created and reported. The instance default branch and merged/read-only branches are rejected.

Note: a merged or deleted session branch is recovered automatically on the next write — this tool is the explicit override on top of that.

Affects only the calling session; other sessions are unaffected.