Skip to main content

Infrahub MCP methods

Response formats​

Structured array responses (schema details, node attributes) are encoded in TOON (Token-Oriented Object Notation) to reduce token usage by 33–45% compared to JSON. TOON declares field names once in a header and lists rows as CSV:

items[N]{field1,field2,field3}:
  value1,value2,value3
  value1,value2,value3

Scalar fields use standard key: value notation. Flat string maps (the schema catalog, branch lists) are returned as compact JSON where TOON offers no benefit.

Schema​

get_schema​

Capabilities​

  • read-only
  • idempotent
  • no destroy

Discover available schema kinds or retrieve the full detail for a single kind.

  • Without kind: returns the catalog of all available kinds as compact JSON.
  • With kind: returns the kind's attributes, relationships, and the full set of filter keys accepted by get_nodes (TOON-encoded).

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

Parameters​

  • kind (string): kind to get detail for; omit to list all kinds
  • branch (string): branch to read from; default is the server's default branch

Nodes​

get_nodes​

Capabilities​

  • read-only
  • idempotent
  • no destroy

List nodes of a specific kind — the default read path for typed queries. Supports filtering and pagination. Use get_schema to discover kinds and their filter keys.

Parameters​

  • kind (string, required): kind of the objects to retrieve
  • branch (string): branch name (default: server's default branch)
  • filters (object): attribute/relationship filter map (e.g. {"name__value": "atl1"} or {"site__name__value": "atl1"})
  • partial_match (boolean, default: false): enable substring matches for string filters
  • include_attributes (boolean, default: false): return full attribute values in TOON tabular format instead of just display labels
  • limit (integer, default: 50, min: -1): maximum nodes to return; -1 returns all results
  • offset (integer, default: 0, min: 0): number of results to skip for pagination

The response dict contains nodes, count, total_count, has_more, offset, and limit. has_more is null when the total count query failed and pagination cannot be confirmed.

search_nodes​

Capabilities​

  • read-only
  • idempotent
  • no destroy

Find nodes by partial name. Performs substring matching against the name attribute only (via name__value with partial_match=true). For other attributes, or combining filters, use get_nodes instead.

Parameters​

  • query (string, required): partial name to search for (minimum 1 character)
  • kind (string, required): kind to search within
  • branch (string): branch name
  • limit (integer, default: 10, range: 1–100): maximum results to return

Session​

get_session_info​

Capabilities​

  • read-only
  • idempotent
  • no destroy

Return the current MCP session state. 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 and is named mcp/session-YYYYMMDD-<hex>. Before the first write, session_branch is null and all read tools target the default branch.

GraphQL​

query_graphql​

Capabilities​

  • read-only
  • idempotent
  • no destroy

Execute a read-only GraphQL query against Infrahub. Mutations are rejected at the AST level — use mutate_graphql instead. For straightforward attribute reads, prefer get_nodes or search_nodes.

Parameters​

  • query (string, required): GraphQL query document (mutations rejected)
  • branch (string): branch to execute against; default is the server's default branch

Write operations​

Write tools target the active session branch, auto-created on the first write of a session (mcp/session-YYYYMMDD-<hex>). Use propose_changes to open a review once your changes are ready. Write tools are hidden when the server runs in read-only mode.

The session branch is tracked per session. If it has been merged or deleted, the next write automatically recovers onto a fresh branch — no server restart is needed. Use reset_session_branch to reset or switch branches deliberately.

node_upsert​

Capabilities​

  • write
  • non-idempotent
  • non-destructive

Create or update a node on the active session branch.

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

Parameters​

  • kind (string, required): kind of the node to create or update
  • data (object, required): flat {attribute: value} map; scalar attributes only
  • id (string): UUID of an existing node to update (update mode)
  • hfid (array of string): human-friendly ID segments of an existing node (update mode)

node_delete​

Capabilities​

  • write
  • non-idempotent
  • destructive

Delete a node 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.

Parameters​

  • kind (string, required): kind of the node to delete
  • id (string): UUID of the node to delete
  • hfid (array of string): human-friendly ID segments of the node to delete

Provide either id or hfid — both cannot be omitted.

propose_changes​

Capabilities​

  • write
  • non-idempotent
  • non-destructive

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.

Parameters​

  • title (string, required): title for the proposed change
  • description (string): optional description explaining the motivation
  • destination_branch (string): branch to merge into; defaults to the instance's default branch

mutate_graphql​

Capabilities​

  • write
  • non-idempotent
  • potentially destructive

Execute a GraphQL mutation against Infrahub — use only for complex writes that the typed tools can't express (relationship edits, bulk operations, mutations not covered by node_upsert / node_delete). The mutation always runs on the active session branch; there is no branch override. To target a different branch deliberately, switch the session with reset_session_branch first. Branch-management mutations (BranchMerge, BranchRebase, BranchDelete, …) and schema mutations are rejected — they would bypass session isolation and the review gate.

Parameters​

  • query (string, required): GraphQL mutation to execute on the session branch

reset_session_branch​

Capabilities​

  • write
  • non-idempotent
  • non-destructive

Reset or switch the active session branch for the current session. Call with no arguments to clear the cached branch so the next write creates a fresh one (for example, after merging your work). Pass a branch name to switch this session to it — the branch is created when it does not exist and the name matches the configured branch pattern. The instance default branch and merged or read-only branches are rejected. Affects only the calling session.

A merged or deleted session branch is recovered automatically on the next write; this tool is the explicit override on top of that.

Parameters​

  • branch (string): target branch; omit to reset to a fresh auto-created branch