# Build and edit graphs and blocks

> Discover node schemas, edit the intended graph with revision guards, use grouped block and canvas tools, and keep validation, saving and execution separate.

Source: https://kaitoi.io/docs/core/mcp-workflows/
Section: Kaitoi Core / MCP
Written for: Anyone who has connected an AI client to Kaitoi.
Prerequisites: The Kaitoi tools available in the current client conversation
Last reviewed: 2026-10-24

---

Use the tools currently listed by your Kaitoi server. Decide first whether
you are editing the headless working graph or an explicitly attached Studio
tab; see [Connect an AI client](/docs/core/mcp/) and
[Live Studio sessions](/docs/core/mcp-studio/).

## Review the connection before and after an edit


The example adds a connection between two existing nodes while leaving other graph content alone. Inspect node schemas and actual pin identifiers before connecting them. Submit the change against the observed revision, validate and reread the result. On a conflict, inspect the new state instead of blindly replaying the old mutation. Editing the graph does not execute it.

The source image and empty Resize Image result area remain unchanged when the wire appears. The wire joins the named image output to inputImage; the downstream result stays absent because connecting is not execution.

*Figure: Use current node identities, pins and revision guards.*

## Discover types, then identify instances

Use `search_nodes` with a focused query and small `max_results`. Request
`fields:["title","inputs","outputs"]` when you need pins. This searches
Kaitoi's catalog, not the web. Do not substitute a guessed type or display
title for the returned operation identifier.

Read `get_graph_state` for placed nodes and connections. Follow
`page.nextCursor` and preserve returned paging versions/snapshot context.
`get_node_info(node_id, fields:["inputs","outputs"])` inspects an actual
instance's pins. An instance ID, node type, label and script path are different
identities.

## Make a narrow graph change

`add_node` takes `node_type` and optional title, position and inputs.
`update_node` changes the identified instance's input values. `connect_nodes`
uses exact `from_node`, `from_output`, `to_node`, `to_input`; the corresponding
disconnect and delete tools are distinct mutations. Read the current schema
before depending on a write.

Attached mutations also need the explicit `studio_session` and current
`expected_revision`. After each accepted change, inspect its receipt and
refresh relevant state. `validate_graph` is a structural check, not execution
or proof of useful media. Save and run are separate operations.

## Work with blocks or containers

`get_studio_blocks` reads blocks or stripes in the attached editor. Use the
grouped `studio_blocks_action` tool with `command:{action,arguments}` for
`add_existing_node_as_block`, `move_block`, or `reorder_blocks`. Adding an
existing node as a block does not create or execute another node. Keep the
original revision while paging.

Canvas containers and supported panel operations use `studio_canvas_action`
with its closed command schema. Do not call an action string as if it were
a standalone public MCP tool. A container is visual organization, not an
execution shortcut.

## Choose the next operation explicitly

**Discover:** read exact types, instance IDs and pins, including bounded-page
continuations. **Edit:** mutate the intended graph; attached changes use the
current handle and editor revision. **Next:** validate, save, and execute are
distinct operations. Grouped block/canvas action names are not standalone
tools. Omitted values have dedicated readers instead of requiring a rerun.

## Read omitted values without repeating work

For omitted graph values, use `get_graph_value` with `node_id`, the returned
`expected_version`, path and offsets. Follow `nextOffset` and nested omission
paths; a short summary is not proof the underlying value is empty.

Use [Project tools](/docs/core/mcp-projects/) to persist work and
[Execution tools](/docs/core/mcp-execution/) to run with the appropriate quote,
consent and idempotency binding. Ask the agent to report edits, validation,
save, execution and output inspection as separate outcomes.