Tools
The server exposes 33 tools — 32 on a deployed engine, where send_files
is not offered (see its entry). This page is the full reference; the
overview has the one-table summary.
How every tool behaves
- One result, two encodings. Every tool returns a JSON object, serialized
once and delivered both as the text content and as
structuredContent— they can never diverge. okis the contract. Success payloads carryok: true. Recoverable failures come back in-band as{ok: false, error_type, message, hint}with the MCPisErrorflag set:BadRequest(bad or missing arguments),Timeout(one engine call ran past its budget — the hint says how to recover),NotFound/TraceExpired(log tools),Unavailable(a local-engine-only tool called on a deployed engine),UnknownTool. Hard failures (lost engine connection, auth) surface as MCP protocol errors with the original message preserved.- Timeouts. Read-side engine calls are budgeted at 30 seconds; the
execution tools (
run_pipeline,run_dropper_pipe,send_data,send_files,terminate) get 120 seconds per engine call. - Per-caller identity. Tools act as the account behind your credential — your store, your deployments, your environment variables, your run logs.
- Pipelines are inline-only. Every
pipelineparameter takes the pipeline JSON itself (a{"pipeline": {...}}wrapper is auto-unwrapped). File paths are rejected — the client reads its own.pipefile and sends the contents. - Every tool carries annotations.
readOnlyHint,destructiveHintandopenWorldHintare explicit on all 33 tools (32 on a deployed engine, wheresend_filesis not offered); the table under Annotations gives each value and its reason. Five tools are open-world: the four execution tools, because a pipeline's nodes run whatever the pipeline defines, andvalidate_pipeline, because its single-component form runs the provider's configuration probe.
Discover components
list_components
List the components ready to use right now: every engine service definition,
minus credentialed integrations that are not fully configured (call
list_integrations to see those and how to finish their
setup).
- Parameters: none.
- Returns:
{ok, components: [{name, category, summary, wiring?}], note?}.wiring(a config-path →${ENV_VAR}map) appears only for configured credentialed integrations;noteappears when unconfigured integrations were omitted.
describe_component
Return one component's full service definition — metadata, lanes, and config schema — plus a credential-readiness block when the component is a credentialed integration.
- Parameters:
name(string, required) — a component name fromlist_components. - Returns: the engine's whole service definition at top level, plus
ok: trueand, for integrations,credentials: {status, missing, candidates, wiring | setup}.
resolve_config
Show what a component config resolves to at load — the engine applies profile
and default merging, so the .pipe rarely says what the node actually
receives.
- Parameters:
provider(string, required) — a provider fromlist_components;config(object, optional) — the component's config block, omitted for pure defaults. - Returns: the resolved config the node would receive, plus
ok: true. - Notable: keys the resolver discarded (for example a key written beside
profileinstead of inside it) are reported with ahintexplaining where to move them — a silent drop a schema cannot express.
list_integrations
Report credential setup status for integrations — the discovery counterpart to
list_components, which hides unready ones. Only integrations with a matching
node on the connected engine are listed.
- Parameters:
name(string, optional) — request full field detail for one integration. - Returns (bare call):
{ok, integrations: [{name, title, status, missing_count}], note}with status one ofconfigured,available(needs setup — no matching variables found), orunconfirmed(candidate variables found for you to confirm, or the variable read failed). - Returns (with
name):{ok, name, title, fields, caller_variables, status, missing, candidates, wiring | setup}—setupcarries the suggested variable names, instructions to relay to the user, and a docs link. - Notable: only environment-variable names are read and reported —
values never transit MCP. Wiring values are emitted as
${VAR}placeholder strings for use in a pipeline config.
Author pipelines
validate_pipeline
Validate an inline pipeline with the engine's validator. It checks what use()
checks, then checks a whole pipeline against the services it names: every
provider is a service on this engine, every control entry names a class of the
node it calls, and every input lane is one the upstream node produces and this
node takes. A node with no lanes, such as a tool, is not checked for the lanes it
takes, and a "*" in a node's lanes matches any lane. use() does not run
those last checks, so a pipeline that fails them can still start.
The single-component form {version, component} that the node editor sends is
accepted too. It checks the component's provider but skips the control and lane
checks, which need the whole pipeline. It is not static: the engine instantiates
the provider and runs its configuration probe, which for LLM nodes sends a small
completion request to the configured endpoint and for stores connects to the
configured database. Validate whole pipelines unless you want that probe.
- Parameters:
pipeline(object, required). - Returns:
{ok, errors: [], warnings: []}—okis true only when there are no errors. A rejection (ok: false) sets the MCPisErrorflag but is not the shared error envelope.
describe_pipeline
Statically parse an inline pipeline into its components, enriched with a best-effort engine lookup per provider (title, category).
- Parameters:
pipeline(object, required). - Returns:
{ok, source, components: [{id, provider, title, classType, inputs}]}. - Notable: lookups share one 30-second budget; providers the engine cannot resolve fall back to the pipeline's own metadata instead of failing the parse.
scaffold_node
Emit a local node skeleton that loads on the first try, with the manifest keys and file layout the engine requires. It returns files to write — it writes nothing itself.
- Parameters:
name(string, required) — a lowercase Python identifier;lane_in(string, optional, defaulttext);lane_out(string, optional, defaults tolane_in);class_type(string, optional, defaults tolane_in). - Returns:
{ok, name, provider, files, next_steps}—filesmapsnodes/<name>/...paths to file contents. - Notable: lanes and
class_typeare validated against the connected engine's live catalog, so the allowed sets never drift from what is actually in service. - Scope: a local node runs only on the engine whose
nodes/directory holds it. RocketRide Cloud loads none, and store review rejects pipelines that use one, so an app headed for the store stays on catalog nodes.
save_template
Save an inline pipeline as a reusable template under an id (stored in your
account file store at .templates/<id>.json).
- Parameters:
template_id(string, required);pipeline(object, required). - Returns:
{ok, template_id}.
load_template
Load a previously saved pipeline template.
- Parameters:
template_id(string, required). - Returns:
{ok, template_id, pipeline}.
Run pipelines
The three start/send tools share these optional start parameters: ttl
(integer — task TTL in seconds, 0 = no timeout), use_existing (boolean —
reuse an already-running task), source (string — source label), threads
(integer), and pipelineTraceLevel (none | metadata | summary | full).
Runs default to summary tracing so the replay tools
have content.
run_pipeline
Start a pipeline from an inline definition, returning a task_token;
optionally send data in the same call and get the result back synchronously.
- Parameters:
pipeline(object, required);inputs(string, optional — data to send immediately after start); plus the shared start parameters. - Returns:
{ok, task_token, projectId, source, result?}—resultonly wheninputswas passed. KeepprojectIdandsource: they key the replay tools. - Notable: if the initial send times out, the error hint still reports the
token so you can
monitorthe task instead of losing it.
run_dropper_pipe
Start a pipeline and get two self-contained URLs for sending file bytes over a separate HTTP channel (bytes cannot ride an MCP tool call).
- Parameters:
pipeline(object, required); plus the shared start parameters (noinputs). - Returns:
{ok, task_token, upload_url, dropper_url, projectId, source}.upload_urlaccepts programmatic multipart POSTs;dropper_urlis a browser page where a person can drag and drop files into the running pipeline. - Notable: the URLs embed only the task's public key (
pk_); the control token never appears in a URL. If the pipeline has no data-ingress source, the task is cleaned up and the call fails with aBadRequestinstead of leaving an orphaned run. In MCP Apps hosts the result renders as the file-dropper widget.
send_data
Send data to a running task and return its result.
- Parameters:
task_token(string, required);input(string, required). - Returns:
{ok, result}.
send_files
Upload files from the engine host's local filesystem to a running task by token.
- Availability: local engines only — the engine binds a loopback host
(
localhost,127.0.0.1,::1), so the engine host is your own machine. Any other bind neither lists the tool nor runs it: a call by name returnsUnavailablewithout looking at the paths. To get files into a pipeline on a deployed engine (including RocketRide Cloud), userun_dropper_pipeand itsupload_url. - Parameters:
task_token(string, required);files(array of paths on the engine host's filesystem, at least one, required). - Returns:
{ok, result}— per-file upload results (status, timing, processing results).
terminate
Terminate a running task by token — also the way to stop a runaway run.
- Parameters:
task_token(string, required). - Returns:
{ok, terminated}.
Watch what's running
monitor
Poll a task until it reaches a terminal state or the timeout elapses, then return a status snapshot. This is bounded polling, not an event stream — it always returns within the timeout.
- Parameters:
task_token(string, required);timeout(number, optional, default 30, clamped to 0–300 seconds);interval(number, optional, default 1, minimum 0.25 seconds). - Returns:
{ok, task_token, state, state_label, completed, terminal, status, counts: {completedCount, failedCount, totalCount}, errors, warnings, polls, poll_timed_out?}. - Notable:
stateis an integer enum (0 none, 1 starting, 2 initializing, 3 running, 4 stopping, 5 completed, 6 cancelled);state_labelis the readable form. Long-lived pipelines (webhook sources) legitimately sit atrunningforever — a timeout then returns the current snapshot withterminal: false, which is not an error. Oncemonitorreports a terminal state, the server drops the token from its own task registry; that is in-memory bookkeeping, not a change to the task.
list_running_pipelines
List the running pipelines on the connected server.
- Parameters: none.
- Returns:
{ok, tasks, count}— task tokens, names, and status, ready to feedmonitor,send_data, orterminate. In MCP Apps hosts the result renders as the pipelines-table widget.
Read the file store
All four tools resolve store-relative paths on the engine, scoped to your account's file store.
store_read
Read a text file from the store.
- Parameters:
path(string, required). - Returns:
{ok, path, content}.
store_list
List the entries under a store directory.
- Parameters:
path(string, optional — defaults to the store root). - Returns:
{ok, path, listing}.
store_stat
Get metadata for a store file or directory.
- Parameters:
path(string, required). - Returns:
{ok, path, stat}— existence, type, size, modified time.
store_get_url
Get a time-limited signed download URL for a store file — the out-of-band
counterpart to store_read for large or binary files.
- Parameters:
path(string, required);expires_in(integer ≥ 1, optional, default 3600 seconds);download_name(string, optional — filename the browser saves as). - Returns:
{ok, path, url, expires_in}.
Manage deployments
Deployments follow the teams-as-environments model. deploy_add registers a
pipeline as the next immutable, numbered version of its project in your
organization's registry; nothing runs yet. deploy_to_team then points a
team (the environment, such as Staging or Production) at a version, and
everything after that acts on one team's deployment, addressed by
project_id + team_id. A typical sequence:
deploy_addthe pipeline (optionally withdeploy_toto do step 2 in the same call).deploy_to_teamwithartifact.versionfrom step 1. The same call promotes a version to another team or rolls back to an older one.deploy_set_schedulefor each source that should run on a cron.
project_id is the pipeline's project_id (projectId on deploy_list
rows). team_id is teamId on a deploy_list row, or "@me" for your
personal space. Every tool here returns records as the engine sends them,
with camelCase fields (projectId, teamId, version, state, schedules).
deploy_add
Register an inline pipeline as the next version of its project.
- Parameters:
pipeline(object, required — must carrynameandproject_id);comment(string, optional — a "what changed" note kept with the version);deploy_to(string, optional — a team id to point at the new version in the same call). - Returns:
{ok, artifact}—artifact.versionis the new version number — plusdeploymentwhendeploy_towas given. - Notable: every call registers a new version, so it is not idempotent —
after a timeout, call
deploy_versionsbefore retrying.
deploy_list
List the team deployments you can see: your teams and your personal space, or the whole organization for an org admin. One row per project per team.
- Parameters: all optional —
team_id(string, restrict to one team);page(integer ≥ 1);page_size(integer ≥ 1, server default 50, max 100);search(string, overprojectId,pipelineName,teamId);filters(object, e.g.{"state": "enabled"});sort(array of{field, dir}; defaultupdatedAtdescending). - Returns:
{ok, deployments, count, total, page, pageSize}—countis the rows on this page,totalevery match.
deploy_status
One team's deployment of a project: version, state, per-source schedules, and who deployed it when.
- Parameters:
project_id(string, required);team_id(string, required). - Returns:
{ok, deployment}.
deploy_versions
A project's registered versions, newest first — the versions deploy_to_team
can point a team at.
- Parameters:
project_id(string, required);page,page_size(integers, optional). - Returns:
{ok, project_id, versions, count, total, page, pageSize}— each row carriesversion,pipelineName,comment,publishedAt,publishedBy.
deploy_to_team
Point a team at a registered version: first deploy, promotion, and rollback are all this call. Deploying to a removed deployment revives it.
- Parameters:
project_id(string, required);version(integer, required);team_id(string, required). - Returns:
{ok, deployment}.
deploy_set_schedule
Set or clear the cron schedule of one source on a team's deployment.
- Parameters:
project_id(string, required);source_id(string, required — a source component of the deployed version);schedule(string, required — a 5-field cron expression, or"manual"to clear it);team_id(string, required);ttl(integer seconds, optional — a fixed run window; omit to run until the pipeline finishes). - Returns:
{ok, deployment}. - Notable: the team must already be deployed (
deploy_to_team), and schedules fire only while the deployment is enabled.
deploy_enable / deploy_disable
Turn a team's deployment back on, or off. Disabling is the kill switch: schedules stop firing and manual runs are refused until it is enabled again.
- Parameters:
project_id(string, required);team_id(string, required). - Returns:
{ok, deployment}with the newstate.
deploy_remove
Soft-remove a team's deployment. It leaves listings and its schedules stop
firing; running tasks are not terminated (use terminate for that). Its
versions and audit history are kept, and deploy_to_team revives it.
- Parameters:
project_id(string, required);team_id(string, required). - Returns:
{ok, deployment}withstate: "removed".
Replay past runs
The run-log (DVR) tools are keyed by projectId + source — the values
run_pipeline/run_dropper_pipe return — never by task token, so they work
for runs that have already finished. All four accept teamId (string,
optional) to address a team's deploy continuum instead of your own dev stream.
Retention: runs are evicted after 7 days (dev) / 30 days (deploy), or earlier
under storage caps. Runs recorded with pipelineTraceLevel: 'none' still have
chapters and console output but empty traces.
log_chapters
List the recorded runs (chapters) for a pipeline — begin/end times, outcome,
and each chapter's beginSeq. Works for past and live runs.
- Parameters:
projectId,source(strings, required);teamId(string, optional). - Returns:
{ok, chapters, horizonSeq}.
log_read
Read raw run-log events, cursor-paged.
- Parameters: the key parameters;
fromSeq(integer, optional — sequence to start from);cursor(integer, optional — from a previousnextCursor);maxEvents(integer, optional, default and maximum 200);types(array of strings, optional — event-type filter, e.g.["output"]for console lines only). - Returns:
{ok, events, nextCursor, truncatedAtSeq}. - Notable: pages are additionally capped at 1 MiB.
log_traces
List per-object trace summaries — one per file or document that traveled the pipeline — for the latest run or a specific past run.
- Parameters: the key parameters;
n(integer, optional, default 20, clamped 1–100);chapterBeginSeq(integer, optional — address a specific past run by its chapterbeginSeqfromlog_chapters). - Returns:
{ok, traces, open, context, note?}—tracesare finished journeys,openare still in flight; each summary carriesbeginSeq, the permanent trace id. In MCP Apps hosts the result renders in the trace-viewer widget.
log_trace
Fetch one object's full begin-to-end journey: every component enter/leave with lane data, plus node narration.
- Parameters: the key parameters;
beginSeq(integer, required — a trace id fromlog_traces). - Returns:
{ok, beginSeq, summary, events, context}. - Errors: a trace below the retention horizon returns
{ok: false, error_type: 'TraceExpired', ...}.
Annotations
Every tool declares all three MCP annotations explicitly. Each value holds for every input form the tool accepts, including optional modes. Hosts use these hints to decide when to ask for confirmation; they do not change what a tool does.
| Tool | readOnlyHint | destructiveHint | openWorldHint | Reason |
|---|---|---|---|---|
list_components | true | false | false | Reads the engine catalog and the caller's variable names; writes nothing; bounded to this engine and account. |
describe_component | true | false | false | Reads one service definition and its credential readiness; writes nothing. |
resolve_config | true | false | false | Computes the merged config the engine would load for a component; nothing is saved. |
validate_pipeline | false | true | true | Whole-pipeline validation is a static engine check, but the accepted single-component form {version, component} runs that provider's own configuration probe inside the engine: LLM nodes send a small completion request to the configured endpoint, a charge that cannot be undone, and store nodes connect to the configured database with the supplied credentials. Destinations are caller-configured, so the tool is open-world. No run is started and nothing is saved. |
describe_pipeline | true | false | false | Parses caller-supplied pipeline JSON with best-effort catalog lookups; nothing is saved or run. |
run_pipeline | false | true | true | Starts a billable task whose nodes run caller-defined logic that can write, delete or send data to any service the pipeline names. |
run_dropper_pipe | false | true | true | Starts a billable task and returns public upload URLs; the pipeline's nodes can reach any external service it names. |
send_data | false | true | true | Feeds data into a running pipeline; processing can write, delete or send externally as the pipeline defines. |
terminate | false | true | false | Cancels a running task, which counts as destructive; bounded to the tasks the caller is authorized to control on this engine. |
send_files | false | true | true | Uploads files from the engine host into a running pipeline (local engines only); the pipeline's effects are open-ended. |
store_read | true | false | false | Reads one file from the caller's own account store. |
store_list | true | false | false | Lists entries in the caller's own account store. |
store_stat | true | false | false | Reads file or directory metadata from the caller's own account store. |
store_get_url | true | false | false | Signs a time-limited download URL for a file in the caller's store; nothing is stored or changed, though the URL is a bearer capability. |
save_template | false | true | false | Writes .templates/<id>.json in the caller's store and overwrites an existing template with the same id. |
load_template | true | false | false | Reads a saved template from the caller's own store. |
deploy_add | false | true | false | Registers a new immutable version (additive), but the optional deploy_to replaces the team's live pointer and re-arms its unpaused schedules; private org registry. |
deploy_list | true | false | false | Reads the deployment records the caller may see. |
deploy_status | true | false | false | Reads one team deployment record. |
deploy_versions | true | false | false | Reads a project's registered versions. |
deploy_to_team | false | true | false | Replaces the team's live version pointer (promotion or rollback), revives a removed deployment and re-arms its unpaused schedules; private registry. |
deploy_set_schedule | false | true | false | Replaces or clears one source's cron schedule, cancelling scheduled runs or arming new metered ones; private registry. |
deploy_enable | false | true | false | Re-arms the deployment's unpaused schedules, which start metered runs that cannot be undone; private registry. |
deploy_disable | false | true | false | Cancels every future scheduled run of the deployment (the kill switch); private registry. |
deploy_remove | false | true | false | Soft-removes the deployment and cancels its scheduled runs; versions and history are kept; private registry. |
monitor | true | false | false | Polls task status; only the server's in-memory token bookkeeping changes when the task completes. |
list_running_pipelines | true | false | false | Lists the running tasks the caller is permitted to see on this engine. |
log_chapters | true | false | false | Reads persisted run-log metadata. |
log_read | true | false | false | Reads a bounded page of persisted run-log events. |
log_traces | true | false | false | Reads trace summaries from the persisted run log. |
log_trace | true | false | false | Reads one trace's events from the persisted run log. |
scaffold_node | true | false | false | Renders node file contents for the caller to write; the server writes nothing. |
list_integrations | true | false | false | Reports credential setup status by variable name; values never transit MCP; nothing is stored. |