# Create and edit custom nodes

> Read current node rules and source policy, author controlled packages, guard attached script edits with source hashes, and test behavior separately from saves.

Source: https://kaitoi.io/docs/core/mcp-custom-nodes/
Section: Kaitoi Core / MCP
Written for: Developers and AI clients authoring custom nodes through MCP.
Last reviewed: 2026-10-24

---

MCP custom-node authoring uses the current node contract and controlled
package paths. It does not give the AI client unrestricted filesystem or
backend access. Available source tools depend on scopes, capabilities and
the server's tool profile.

## Review code together with its interface


Inspect the existing custom node and editable source, then make a bounded change with the returned revision guards. Match declared inputs, outputs and controls to the computation. Save, reread and validate before preparing execution. A successful save is not evidence that the node ran. Inspect errors before changing code or requesting another run.

The illustrative diff replaces addition with multiplication. A symbolic source hash H1 and numeric editor revision 7 must both still match; changed source H2 or revision 8 requires comparison. Hash labels are symbolic, not values to submit.

*Figure: A custom node needs a valid contract as well as valid source.*

## Read rules before generating code

Use `list_knowledge_docs`, `search_knowledge`, and `get_knowledge_doc` for
bounded authoring guidance. Read `node_development_rules` and
`get_node_source_policy` before choosing imports, dependencies or helpers.
Follow paging/sections and returned knowledge revisions when the document
is larger than the current response.

Ordinary nodes use comment-based metadata, a top-level `run()` function,
and an output dictionary keyed by declared output names. Use exact supported
injectable names. `validate_node_script(script_content)` checks the script's
discovery/schema contract; it does not prove executed media or correct behavior.
See [Writing custom nodes](/docs/core/custom-nodes/) for the Python reference.

## Work in controlled user packages

Headless authoring can use listed `read_file`, `write_file`, and `update_file`
tools for supported user-node paths. `get_node_code`, `list_package_files`,
and `read_package_file` inspect the actual implementation and assets. Confirm
whether a change should overwrite the identified source or create a separate
package. A node type or instance label is not an arbitrary filesystem path.

Inspect the returned path and validation after a save, then discover and place
the node separately if needed. A saved file is not a successful run, and a
new graph instance is not a private copy of shared source.

## Edit the live Studio script deliberately

In an attached session, `studio_files` with `operation:"get_current_script"`
reads the actual selected editor buffer. Its history and supported file views
are also explicit operations; do not silently substitute a disk file when
the intended editor buffer is unavailable.

`studio_files_action` uses a request such as
`{operation:"update_current_script",path,expected_source_sha256,content}`
with the explicit `studio_session` and current `expected_revision`. Obtain
both the source hash and revision from current reads. A newer hash/revision
must not be pasted onto stale replacement content without comparison.

## Keep the authoring stages distinct

**Read:** inspect current authoring rules, source policy and actual source.
**Replace:** attached edits need path, expected_source_sha256 and current
editor revision; storage and editor adoption can have separate outcomes.
**Test:** static validation and saved code are not execution evidence. Use
small known/boundary/failure cases and inspect real outputs.

## Inspect and test after a change

Read save and adoption receipts separately when storage and the editor have
partial outcomes. After uncertainty, inspect the original action before
repeating a source overwrite. Keep a known-good source copy and preserve pin
names/types unless the interface change is intentional.

Test a small known input, a boundary case and a clear failure case only with
the required execution authority. Review implementation warnings and actual
output files; static validation is not a render or a completeness proof.
See [Run approvals](/docs/core/mcp-execution/) and
[Results](/docs/core/mcp-results/).