Tools
The five Blitflow MCP tools and their parameters.
All tools mirror the API contract exactly — parameters are validated against the same schemas.
Tool naming: the hosted server exposes underscore names (nodes_list) —
contract op names use dots (nodes.list), which some MCP clients can't call
as tool names. In a client like Claude Code the tools surface as
mcp__blitflow__nodes_list etc. The local stdio server registers the raw
dotted names.
nodes_list
List or search the node palette. Returns NodeSpec[].
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | no | Free-text search (id, title, description) |
category | string | no | Filter by category |
limit | integer | no | Max results |
nodes_get
Fetch one node spec by id — its exact input/output ports, defaults, enum
optionValues, and numeric bounds.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Node id, e.g. rd-fast |
Call this before running a node and build inputs from the returned spec. Guessed enum values fail validation — they are not in the model's memory.
workflows_get
Fetch a published workflow version's canonical definition.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Published <org-slug>/<workflow-slug> address (e.g. acme/sprite-pack) or the workflow's UUID |
version | string | no | latest (default), a full semver (2.1.0), or a major (2) |
Returns { id, address, version, sequence, workflow } (address is null
until the workflow's slug is claimed) — see
Versioning.
runs_create
Run a workflow. Provide exactly one of workflow or workflowRef. The
tool consumes the run's event stream internally and returns the terminal
outputs.
| Parameter | Type | Required | Description |
|---|---|---|---|
workflow | object | one of | Inline workflow definition |
workflowRef | string | one of | <id>@<version> reference — a published address like acme/sprite-pack@2.1.0 (preferred) or a workflow UUID like 8f61e451-…@2.1.0 |
inputs | object | no | Artifacts keyed by workflow input name |
maxCostUsd | number | no | Spend cap in USD — set this on every run |
Result: { outputs: Record<string, Artifact> }. If the run fails, the tool
returns the run.failed error — read the message; don't loop.
runs_node
Run a single node by id — no workflow needed. Supports model/llm nodes.
| Parameter | Type | Required | Description |
|---|---|---|---|
node | string | yes | Node id |
inputs | object | yes | Keyed by input port name — scalars for value ports, Artifacts for data ports |
maxCostUsd | number | no | Spend cap in USD |
Returns { outputs: Record<string, Artifact> }.
Agent playbook
- Discover —
nodes_listwithq/category, thennodes_getthe candidate. Build inputs strictly from the spec. - Cap spend — always pass
maxCostUsd; prefer the cheapest node that clears the quality bar. - Fetch refs — binary outputs are ref artifacts; download the
refURL for bytes, and reuse persisted refs instead of regenerating. - Stop on failure — a
run.failed/ error result is terminal. Read the message, fix the inputs, then retry deliberately.