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
  • expand (boolean): inline one level of each relationship's peer schema; defaults to the server's INFRAHUB_MCP_SCHEMA_EXPAND_PEERS setting

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

Graph traversal​

Graph traversal walks the live data graph to find how objects connect. It requires Infrahub 1.10 or later. Node arguments — source (both tools) and destination (find_paths only) — accept either a node UUID or a kind-qualified human-friendly ID (for example InfraDevice__atl1-edge1, the form get_nodes returns); an unresolvable human-friendly ID returns an error pointing at get_nodes.

find_paths​

Capabilities​

  • read-only
  • idempotent
  • no destroy

Find the shortest path(s) between two nodes. A count of 0 means no path within max_depth. Prefer this over a hand-built deep GraphQL query when you need to know how two objects are connected.

Parameters​

  • source (string, required): start node — UUID or kind-qualified human-friendly ID
  • destination (string, required): end node — UUID or kind-qualified human-friendly ID
  • branch (string): branch to read from; default is the server's default branch
  • max_depth (integer): maximum relationship hops to explore
  • kind_filter (array of strings): only traverse through nodes of these kinds
  • relationship_filter (array of strings): only follow these schema relationship identifiers

find_reachable​

Capabilities​

  • read-only
  • idempotent
  • no destroy

Find nodes of the given kinds reachable from a source node — impact and dependency analysis.

Parameters​

  • source (string, required): source node — UUID or kind-qualified human-friendly ID
  • target_kinds (array of strings, required): node kinds to search for
  • branch (string): branch to read from; default is the server's default branch
  • max_depth (integer): maximum traversal depth
  • max_results (integer, default: 20): maximum distinct reachable nodes returned
  • shortest_paths_only (boolean, default: true): return only the shortest path to each target

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 authenticated caller, and per MCP session when the client has one. Without credentials or an MCP session, all clients of the server share one session branch. 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 calling client. 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 make it the session branch — 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. A reset or switch applies to every conversation that shares the session branch: all conversations of one authenticated caller that have no MCP session, or all clients without credentials or an MCP 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