Tools
The BlitFlow MCP tools and their parameters.
All tools mirror the API contract exactly — parameters are validated against the same schemas.
Tool naming: both servers (hosted and blitflow mcp stdio) expose
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.
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 — kind is optional, the input node declares it |
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 (kind optional, the port declares it) |
Returns { outputs: Record<string, Artifact> }.
artifacts_import
Import a publicly fetchable http(s) URL as an organization-owned
Artifact — the way to feed remote media into
runs_node / runs_create. Pass the returned artifact object unchanged
as a run input.
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | yes | Public http(s) URL. Private/internal destinations are rejected |
org | string | no | Organization slug; omit for the personal organization |
kind | string | no | Override the kind derived from the content type: image, audio, video, or file |
retention | string | no | temporary (default, 30 days) or durable |
Returns { id, artifact, contentType, sizeBytes, expiresAt } — see the
HTTP flow for limits.
artifacts_uploads_prepare / artifacts_uploads_complete
The signed-upload control plane for bytes a programmatic client holds locally:
prepare returns a short-lived direct-upload URL and token constrained to one
pathname, declared content type, and maximum size; after PUTting the bytes
there, complete (with the returned id) verifies the blob and records the
Artifact, idempotently. See the signed-upload flow for
the full steps.
No BlitFlow tool accepts base64, byte arrays, data: URIs, or local file
paths. Never serialize file bytes into tool arguments — import a URL, or drive
the signed-upload flow from your own runtime.
Agent playbook
- Discover —
nodes_listwithq/category, thennodes_getthe candidate. Build inputs strictly from the spec. - Mind spend — runs are charged to the organization's balance with no
per-run cap; prefer the cheapest node that clears the quality bar, and read
usage.costUsdbefore scaling up. - Fetch refs — binary outputs are ref artifacts; download the
refURL for bytes, and reuse persisted refs instead of regenerating. - Media in, by reference — to use an image/audio/video input, first
artifacts_importits URL (or run the signed-upload flow), then pass the returnedartifactunchanged. Never inline bytes ordata:URIs. - Stop on failure — a
run.failed/ error result is terminal. Read the message, fix the inputs, then retry deliberately.