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.

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 targets the session branch by default.

Parameters​

  • query (string, required): GraphQL mutation to execute
  • branch (string): branch to execute against; defaults to the session branch