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.
feedback_create
Submit minimized text feedback through the same contract as HTTP and the CLI.
Required fields: submissionKey (UUID), source (mcp), category (bug or
feedback) and comment (1–8,000 characters). Optional fields: org (organization
slug), reproduction, expected and actual (up to 2,000 characters each).
No attachment, transcript or raw-log fields are accepted.
The manage scope controls stdio tool exposure and invocation. All member roles
may submit feedback; the server derives identity and organization access.
The result contains only { id, createdAt }. Reuse the submission UUID for a
retry. Ten new reports per rolling minute are allowed per principal, and stored
reports become eligible for daily deletion after ninety days.
Never reveal sensitive data in feedback. Anonymize the report before submitting: replace names, emails, organization/customer identifiers and private paths with neutral placeholders. Remove API keys, tokens, passwords, cookies, authorization headers, environment variables, private prompts/assets and customer data. Include only the minimum reproduction steps and sanitized error details. Do not attach transcripts, files, screenshots or raw logs automatically. If a report cannot be made safe, omit the sensitive detail and describe the failure generally.
Known-pattern redaction cannot recognize every private fact; review the minimized text.