Tool Listing

Noukai exposes 61 MCP tools for programmatic flow management.

Read Tools

Inspect flows, blocks, and operation history.

list_flows

List all flows in a project with summary info: ID, name, slug, block count, and whether steps exist. Does not include block details — use get_flow or hydrate_project for that.

get_flow

Get full flow detail: metadata, annotated steps tree (with block names and processor types inline), and all block details including prompts, schemas, and configs.

get_flow_structure

Get just the annotated steps tree for a flow — lightweight. Returns the tree with block names and processor types inline, plus block count. Use this when you only need topology, not full block details.

get_block

Get a single block's full detail: prompt, model, schemas, config, processor config, and notes. For code blocks, also returns a runtime_context field with the generated wrapper signature, sandbox rules, and parameter bindings. Use when you need to inspect or modify one specific block.

get_operation_history

Get recent operation history for a flow from the oplog. Returns operation type, sequence number, timestamp, request payload, and result. Useful for understanding what changes were made recently.

hydrate_project

Fetch complete project data: all flows with their blocks (including prompts, schemas, configs), checkpoints, versions, object models, and test cases. Call this first to understand a project's current state.

---

Structural Tools

Add, remove, move, and organize blocks in the flow tree.

add_block

Add a new processing block to a flow. Two modes: (1) Sibling-relative — use target_id + direction to insert relative to an existing block (preferred). (2) Parent-absolute — use parent_id + position for exact placement. If the flow is empty, omit both to create the first block. For processor_type='code': the prompt field is the function BODY only (Python). The runtime wraps it in def _block(initial, ...input_schema_fields):. No imports, no function definition. Must return a dict. See https://docs.noukai.dev/docs/mcp-reference/block-runtime-contract.

remove_block

Remove a block from a flow. If the block's parent container has only one child after removal, the container is automatically unwrapped.

move_block

Move a block (or container) to a new position in the flow tree.

duplicate_block

Copy a block to a new position with new IDs. Defaults to immediately after the original.

wrap_in_container

Wrap one or more adjacent sibling nodes in a new container.

unwrap_container

Remove a container and promote its children to the container's parent.

wrap_in_loop

Wrap one or more adjacent sibling nodes in a loop that iterates over an array field.

unwrap_loop

Remove a loop and promote its children to the loop's parent.

reorder_children

Reorder the children of a container or loop. The new order must contain exactly the same child IDs.

rename_block

Rename a block's display name.

change_processor_type

Change a block's processor type (llm, passthrough, or code).

---

Lifecycle Tools

Create and delete flows.

create_flow

Create a new empty flow in a project. This is the first step when building a new pipeline.

delete_flow

Delete a flow and all its blocks, checkpoints, and versions (soft-delete). This is destructive.

---

Content Tools

Update block prompts, schemas, configs, and flow metadata.

update_block_draft

Update a block's prompt text (full replacement, not a diff). For code blocks: content is the function BODY only (Python) — the runtime wraps it in def _block(initial, ...):. No imports, no function def, must return a dict. See https://docs.noukai.dev/docs/mcp-reference/block-runtime-contract. Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics. For multi-field edits, prefer update_block (one round-trip, one version bump).

update_block_config

Update a block's model and configuration. At least one of model, config, or processor_config must be provided — omitted fields remain unchanged. Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics. For multi-field edits that also touch draft / notes / schemas, prefer update_block (one round-trip, one version bump).

update_block_input_schema

Replace a block's input schema (full replacement). For code blocks: field names become the function parameters (after initial). Changing this changes the wrapper signature. Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics. For multi-field edits, prefer update_block.

update_block_output_schema

Replace a block's output schema (full replacement). For code blocks: field names define the expected return dict keys. Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics. For multi-field edits, prefer update_block.

update_block_notes

Replace a block's notes text (full replacement). Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics. For multi-field edits, prefer update_block.

update_flow_meta

Update a flow's metadata. At least one of name, description, flow_settings, or notes must be provided — omitted fields remain unchanged. Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics.

update_flow_global_input

Replace a flow's global input schema (full replacement). Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics.

update_flow_trigger

Replace a flow's trigger configuration (full replacement). Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics.

---

Block Checkpoint Tools

Save and manage block-level prompt snapshots. Distinct from eval checkpoints, which snapshot a judge body — see Eval Tools.

create_block_checkpoint

Save the current BLOCK PROMPT as a named checkpoint (snapshot). Useful for tracking prompt iterations. Not to be confused with create_eval_checkpoint, which snapshots an eval's judge body.

delete_block_checkpoint

Delete a block-prompt checkpoint from a block. Not to be confused with delete_eval_checkpoint.

---

Eval Tools

Author reusable judges (the project eval library), attach them to flows/blocks/test cases as bindings, and snapshot judge bodies as eval checkpoints. Library and eval-checkpoint tools are project-scoped; binding tools are flow-scoped.

list_evals

List a project's eval definitions (the reusable judge library), their bindings (where each judge is attached), and their checkpoints. Read content_version from here before calling update_eval or update_eval_binding. Optional flow_id filters BINDINGS only — definitions and checkpoints are project-level and always returned in full. Backed by project hydration, so this is a relatively heavy call.

create_eval

Create a reusable eval DEFINITION (a judge) in the project library. This does NOT attach it to anything — call attach_eval afterwards to bind it to a flow, block, or test case. judge_prompt and judge_model are required non-empty for every judge_type, including 'code'.

update_eval

Update an eval DEFINITION in the project library. At least one definition field must be supplied. Binding-only fields (severity, activation, sort_order, expected) are a category error here — use update_eval_binding for those.

delete_eval

Soft-delete an eval DEFINITION from the project library. Fails while the eval still has live bindings — call detach_eval on each binding first.

attach_eval

Attach a library eval to a flow, creating a binding. scope='pipeline' judges the whole flow output, 'block' judges one step (requires step_id), 'test-case' judges a saved test case (requires test_case_id, and is the only scope that accepts expected).

update_eval_binding

Retune a binding's per-attachment overrides (severity, activation, mode, gate/heal params, expected, ordering). At least one must be supplied. Definition fields (judge_prompt, judge_model, ...) belong to update_eval, not here.

detach_eval

Detach a binding, removing the judge from that flow location. The library eval DEFINITION is untouched and stays reusable.

create_eval_checkpoint

Snapshot a library eval's judge body (type, prompt, code, model, provider, pass criteria) as an immutable checkpoint. This is the EVAL analogue of create_block_checkpoint — that one snapshots a block prompt and is flow-scoped; this one snapshots a judge and is project-scoped.

delete_eval_checkpoint

Soft-delete an eval checkpoint. Not to be confused with delete_block_checkpoint.

set_active_eval_checkpoint

Pin a library eval to one of its checkpoints, so the judge runs from the frozen snapshot instead of the live definition. Pass checkpoint_id=null (or omit it) to deactivate and fall back to the live definition.

---

Versioning Tools

Publish immutable versions and set production.

publish_version

Publish the current flow state as an immutable version. Freezes the tree structure and all block states.

set_production_version

Set which published version is the production version used when the flow is invoked via API.

---

Object Model Tools

Manage reusable schema types at the project level.

create_object_model

Create a reusable schema type at the project level. Object models define structured data shapes that blocks can reference.

update_object_model

Update an existing object model's name, description, or fields. At least one field must be provided.

delete_object_model

Delete an object model from the project.

---

Test Case Tools

Create and manage test cases for flows and blocks.

create_test_case

Create a new test case in a flow. Test cases can be flow-scoped or block-scoped.

update_test_case

Update a test case's name, input data, or sort order. At least one field must be provided.

delete_test_case

Soft-delete a test case.

duplicate_test_case

Duplicate a test case. The server mints the new ID and resolves a non-colliding name.

reorder_test_cases

Reorder test cases within a flow and scope. Pass an ordered list of test case IDs; sort_order is set from list position.

---

Other Tools

list_projects

List all projects accessible to the authenticated user. Returns each project's UUID (id), name, slug, description, and organization details. Call this first when the user references a project by name to resolve it to a project_id for other tools (list_flows, hydrate_project, create_flow, etc.).

get_test_run_trace

Get the full trace for a test run: run summary plus per-step details including input/output snapshots, token counts, model used, cost, and error context. Use the runId returned by run_test_case to inspect what each block received and produced — essential for debugging test failures.

get_step_trace

Get the trace for a single step within a test run. Returns detailed input/output snapshots, token usage, model, cost, and error context for the step. Use attempt='all' to see retry history or a specific attempt number.

run_test_case

Execute a test case and return results. Runs the test against the current draft state of the flow, streaming block-by-block execution internally and returning a summary with per-step outputs, token usage, and pass/fail status. Blocks until the run completes (may take 30-120s for multi-block pipelines).

run_all_tests

Run all test cases for a flow and return aggregated results. Lists test cases matching the given flow_id (and optional scope/block_id filters), executes each sequentially, and returns a summary with total/passed/failed counts and per-test results. Individual test failures don't abort the batch.

run_flow

Execute a flow end-to-end ad-hoc with inline inputs and return an aggregated result. Use this for exploratory pipeline iteration: try different inputs against a flow without polluting list_test_cases with throwaway test cases. Does NOT save a test case; for repeatable assertions use create_test_case + run_test_case. Result shape matches run_test_case — runId, status, durationMs, steps[], totalPromptTokens, totalCompletionTokens, totalCostUsd. Pass the returned runId to get_test_run_trace(runId) for the full trace.

run_block

Execute a single block ad-hoc with inline inputs and return an aggregated result. Use this for inner-loop iteration: when get_test_run_trace points at a divergent block, run_block lets you verify a prompt or schema edit on that block in one call — cheaper than re-running the full pipeline via run_all_tests. Does NOT save a test case; for repeatable assertions use create_test_case + run_test_case. Returns output, tokens_in/out, cost_usd, latency_ms, model_used, version_used, plus a flow_run_id you can pass to get_step_trace(flow_run_id, step_id) for the full trace.

list_test_cases

List test cases. Provide flow_id (lists all tests in that flow), flow_id + step_id (lists tests for that block within that flow), or step_id alone (lists tests for that block across every flow you have access to). Optional scope filter ('pipeline'|'block'|'loop') narrows results. Use this to discover existing tests before creating duplicates or to find tests to re-run after editing a block. step_id is the tree-node id on a block — the id field on each block node returned by get_flow_structure, or the step_id field on get_block.

update_block

Atomically update any combination of a block's mutable fields in one call: draft, notes, model, config, processor_config, input_schema, output_schema. Server applies all changes in a single transaction with one version bump and one oplog entry — preferred over chaining the single-field tools (update_block_draft, update_block_config, etc.) which produce one version bump and one oplog entry each. At least one mutable field must be provided. Optimistic concurrency — see the base_version parameter for omit-vs-supply semantics.

get_pipeline_authoring_guide

IMPORTANT: the server does NOT match intent to patterns/recipes — YOU read the returned summaries and decide which apply. intent is passthrough only. Call this tool FIRST whenever the user wants to create, edit, or refactor a pipeline. Returns: the structured workflow (clarify → propose design → scaffold → test → iterate → report), the safety + model rules, and the full pattern/recipe summary list. Drill into specific items with get_pipeline_pattern(name) or get_pipeline_recipe(name). Content tailoring happens via mode (create/edit/refactor), not via intent.

get_pipeline_pattern

Return the full body and metadata of a single pattern by its machine-readable name (e.g. 'single-block', 'sequential-decomposition'). Names come from the patterns list returned by get_pipeline_authoring_guide.

get_pipeline_recipe

Return the full body, block_template, and edge_case_categories of a single recipe by name (e.g. 'essay-feedback', 'dictionary-lookup'). Names come from the recipes list returned by get_pipeline_authoring_guide. The block_template field is structured: each item has name/type/purpose/prompt_skeleton/recommended_model/output_schema — exactly the shape you need to call add_block / update_block_draft / update_block_output_schema.