Skip to main content

Tools

View as Markdown

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.
  • Every tool carries annotations. readOnlyHint, destructiveHint and openWorldHint are explicit on all 33 tools (32 on a deployed engine, where send_files is 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, and validate_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; 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 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: []} — ok is true only when there are no errors. A rejection (ok: false) sets the MCP isError flag 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, 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 nodes/<name>/... paths to file contents.
  • 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 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?} — 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. Once monitor reports 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 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 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} 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', ...}.

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.

ToolreadOnlyHintdestructiveHintopenWorldHintReason
list_componentstruefalsefalseReads the engine catalog and the caller's variable names; writes nothing; bounded to this engine and account.
describe_componenttruefalsefalseReads one service definition and its credential readiness; writes nothing.
resolve_configtruefalsefalseComputes the merged config the engine would load for a component; nothing is saved.
validate_pipelinefalsetruetrueWhole-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_pipelinetruefalsefalseParses caller-supplied pipeline JSON with best-effort catalog lookups; nothing is saved or run.
run_pipelinefalsetruetrueStarts a billable task whose nodes run caller-defined logic that can write, delete or send data to any service the pipeline names.
run_dropper_pipefalsetruetrueStarts a billable task and returns public upload URLs; the pipeline's nodes can reach any external service it names.
send_datafalsetruetrueFeeds data into a running pipeline; processing can write, delete or send externally as the pipeline defines.
terminatefalsetruefalseCancels a running task, which counts as destructive; bounded to the tasks the caller is authorized to control on this engine.
send_filesfalsetruetrueUploads files from the engine host into a running pipeline (local engines only); the pipeline's effects are open-ended.
store_readtruefalsefalseReads one file from the caller's own account store.
store_listtruefalsefalseLists entries in the caller's own account store.
store_stattruefalsefalseReads file or directory metadata from the caller's own account store.
store_get_urltruefalsefalseSigns 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_templatefalsetruefalseWrites .templates/<id>.json in the caller's store and overwrites an existing template with the same id.
load_templatetruefalsefalseReads a saved template from the caller's own store.
deploy_addfalsetruefalseRegisters 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_listtruefalsefalseReads the deployment records the caller may see.
deploy_statustruefalsefalseReads one team deployment record.
deploy_versionstruefalsefalseReads a project's registered versions.
deploy_to_teamfalsetruefalseReplaces the team's live version pointer (promotion or rollback), revives a removed deployment and re-arms its unpaused schedules; private registry.
deploy_set_schedulefalsetruefalseReplaces or clears one source's cron schedule, cancelling scheduled runs or arming new metered ones; private registry.
deploy_enablefalsetruefalseRe-arms the deployment's unpaused schedules, which start metered runs that cannot be undone; private registry.
deploy_disablefalsetruefalseCancels every future scheduled run of the deployment (the kill switch); private registry.
deploy_removefalsetruefalseSoft-removes the deployment and cancels its scheduled runs; versions and history are kept; private registry.
monitortruefalsefalsePolls task status; only the server's in-memory token bookkeeping changes when the task completes.
list_running_pipelinestruefalsefalseLists the running tasks the caller is permitted to see on this engine.
log_chapterstruefalsefalseReads persisted run-log metadata.
log_readtruefalsefalseReads a bounded page of persisted run-log events.
log_tracestruefalsefalseReads trace summaries from the persisted run log.
log_tracetruefalsefalseReads one trace's events from the persisted run log.
scaffold_nodetruefalsefalseRenders node file contents for the caller to write; the server writes nothing.
list_integrationstruefalsefalseReports credential setup status by variable name; values never transit MCP; nothing is stored.