> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# 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](/connect/mcp/http/) 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](#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`](#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](#replay-past-runs)
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](#replay-past-runs).
- **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](/connect/mcp/http/resources-and-widgets#widgets).

### 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](/connect/mcp/http/resources-and-widgets#widgets).

## 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](/connect/mcp/http/resources-and-widgets#widgets).

### 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.

| 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. |
