Tools

View as Markdown

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.
• ok is the contract. Success payloads carry ok: true. Recoverable failures come back in-band as {ok: false, error_type, message, hint} with the MCP isError flag 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 pipeline parameter takes the pipeline JSON itself (a {"pipeline": {...}} wrapper is auto-unwrapped). File paths are rejected — the client reads its own .pipe file and sends the contents.

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; note appears 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 from list_components.
• Returns: the engine's whole service definition at top level, plus ok: true and, 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 from list_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 profile instead of inside it) are reported with a hint explaining 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 of configured, available (needs setup — no matching variables found), or unconfirmed (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} — setup carries 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 own validator — the same rules use() applies, so there is no client-side drift — plus one check the engine's pipeline path does not cover: every component must name a provider the engine has a service for.

• Parameters: pipeline (object, required).
• Returns: {ok, errors: [], warnings: []} — ok is true only when there are no errors.

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, default text); lane_out (string, optional, defaults to lane_in); class_type (string, optional, defaults to lane_in).
• Returns: {ok, name, provider, files, next_steps} — files maps local_nodes/__init__.py (the parent package marker) and local_nodes/<name>/... paths to file contents. Write every returned path: without the marker local_nodes is not a package and the engine cannot import local_nodes.<name>.
• Notable: lanes and class_type are 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 an engine started with --node_path. 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?} — result only when inputs was passed. Keep projectId and source: they key the replay tools.
• Notable: if the initial send times out, the error hint still reports the token so you can monitor the 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 (no inputs).
• Returns: {ok, task_token, upload_url, dropper_url, projectId, source}. upload_url accepts programmatic multipart POSTs; dropper_url is 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 a BadRequest instead 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 returns Unavailable without looking at the paths. To get files into a pipeline on a deployed engine (including RocketRide Cloud), use run_dropper_pipe and its upload_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: state is an integer enum (0 none, 1 starting, 2 initializing, 3 running, 4 stopping, 5 completed, 6 cancelled); state_label is the readable form. Long-lived pipelines (webhook sources) legitimately sit at running forever — a timeout then returns the current snapshot with terminal: false, which is not an error.

list_running_pipelines

List the running pipelines on the connected server.

• Parameters: none.
• Returns: {ok, tasks, count} — task tokens, names, and state, ready to feed monitor, send_data, or terminate. 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:

1. deploy_add the pipeline (optionally with deploy_to to do step 2 in the same call).
2. deploy_to_team with artifact.version from step 1. The same call promotes a version to another team or rolls back to an older one.
3. deploy_set_schedule for 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 carry name and project_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.version is the new version number — plus deployment when deploy_to was given.
• Notable: every call registers a new version, so it is not idempotent — after a timeout, call deploy_versions before 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, over projectId, pipelineName, teamId); filters (object, e.g. {"state": "enabled"}); sort (array of {field, dir}; default updatedAt descending).
• Returns: {ok, deployments, count, total, page, pageSize} — count is the rows on this page, total every 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 carries version, 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 new state.

deploy_remove

Soft-remove a team's deployment. It leaves listings and stops running; 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} with state: "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 previous nextCursor); 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 chapter beginSeq from log_chapters).
• Returns: {ok, traces, open, context, note?} — traces are finished journeys, open are still in flight; each summary carries beginSeq, 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 from log_traces).
• Returns: {ok, beginSeq, summary, events, context}.
• Errors: a trace below the retention horizon returns {ok: false, error_type: 'TraceExpired', ...}.