> For the complete documentation index, see [llms.txt](https://docs.autommate.com/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autommate.com/userguide/mcp-and-ai-reference/run-an-existing-autom-through-mcp.md).

# Run an existing Hyperflow through MCP

**Direct tool references:** [`automs_run`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/automs-run.md). These contracts were reviewed against the 21 October 2026 Autom Mate New declaration profile. Historical examples retain their original dates; declared capability is not runtime verification. Check [capabilities and version scope](https://docs.autommate.com/userguide/mcp-and-ai-reference/capabilities-and-version-scope.md) for the active connection.

Use automs\_run to execute an existing API- or webhook-triggered Hyperflow. Identify the target, read its input contract and confirm the intended execution first. Keep one idempotency key for that intended operation; a new key is a new run, not a retry of the earlier request.

### Execution contract

| Parameter            | Type                                               | Required | Meaning                                                                                                   |
| -------------------- | -------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `autom_id`           | string                                             | Yes      | ID returned by the current `automs_search`.                                                               |
| `idempotency_key`    | string                                             | Yes      | Fresh key for each intended run; reuse the same key and arguments only when retrying that same operation. |
| `inputs`             | object with string keys and JSON-compatible values | No       | Confirmed values matching the selected Autom's declared input contract.                                   |
| `mode`               | `preview` or `apply`                               | No       | Select the intended phase explicitly; do not assume an omitted value is a safe default.                   |
| `confirmation_token` | string                                             | No       | Token returned by the preview when applying the same confirmed operation.                                 |

Supported trigger types are **API** and **webhook**. No `dry_run`, timeout, callback or deployment-selector field is declared. Use explicit `mode:preview` and `mode:apply` with the returned confirmation token; preview does not execute or verify the business result.

### Execution sequence

{% code collapsedlinecount="10" %}

```mermaid
flowchart TD
    A[User asks to run an existing Autom] --> B[Search by name]
    B --> C{One intended Autom identified?}
    C -- No --> D[Ask the user to choose]
    C -- Yes --> E[Read declared inputs and trigger]
    E --> F{Inputs known and trigger supported?}
    F -- No --> G[Resolve missing information]
    F -- Yes --> H[Confirm action and input values]
    H --> I[Preview with fresh idempotency key]
    I --> P[Apply same confirmed operation and token]
    P --> J[Inspect returned evidence]
    J --> K[Track the specific run if needed]
    K --> L[Report status and verified result separately]
```

{% endcode %}

1. Call `automs_search` using the user's Autom name. Resolve ambiguous matches with the user.
2. Call `automs_get` with the returned `autom_id`. For run preparation, the default `include_flow: false` avoids unnecessary flow detail.
3. Check that the Autom uses an API or webhook trigger.
4. Read the input contract. Confirm values for declared inputs; do not infer masked values or substitute guessed identifiers.
5. Confirm the intended execution with the user before calling the run tool.
6. Generate a fresh `idempotency_key` for the intended run. Preview it with `mode:"preview"`, inspect the effect and follow the returned confirmation requirements. Apply the same target, inputs and key with `mode:"apply"` and the returned `confirmation_token`. Preserve the key and evidence; a retry of the same operation must keep the same key and arguments.
7. Use [run monitoring](https://docs.autommate.com/userguide/mcp-and-ai-reference/track-run-status-and-verify-results.md) to establish what happened.

### Inputs: three different situations

| Observation from `automs_get`             | Agent behavior                                                                                           |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Successful read with `input_contract: []` | No declared inputs are required.                                                                         |
| A non-empty input contract                | Collect values according to the returned definition and validate the intended values with the user.      |
| `inputs_note` without `input_contract`    | Requirements are unknown. Ask for the missing input information; do not send an empty object as a guess. |

The inputs keys belong to the selected Hyperflow’s declared contract. There is no universal input-name list.

### API and webhook responses

For an API-triggered Hyperflow, the tool can return flow output. Read the returned value and any relevant destination evidence to check the requested result.

For a webhook-triggered Hyperflow, the call does not return an operation ID. Use runs\_search with the selected autom\_id to locate the execution. If several runs could match, compare their evidence and report attribution as unresolved instead of choosing the newest arbitrarily.

### If the call times out or the response is unclear

The request may have started an execution before the response was lost. Preserve the original idempotency key and inspect history for the selected Autom, bounded by the observed request time using `created_from`/`created_to`. The declared contract replays the first outcome for the same key and arguments; do not generate a new key to recover a lost response. If the original operation cannot be identified, explain that uncertainty before any new execution.

### Completion message

Report the chosen Hyperflow, run identifier when available, returned status and supported result. State whether execution started, completed or produced a verified business outcome, and identify any remaining uncertainty.

#### Connection, authorization, and retry boundaries

The run uses the signed-in Autom Mate user’s permissions and requires MCP write access plus the relevant product permission. Follow [MCP connection](https://docs.autommate.com/userguide/mcp-and-ai-reference/connect-an-ai-client-with-mcp.md) for authentication and connection setup.

The 21 October profile also declares separate Hyperflow authoring, Service and deployment tools. Their presence does not make this run tool a deployment operation. Inspect the active connection and use the relevant object-specific contract.

After a failed run, assess earlier side effects before an authorized new run. Reusing the same idempotency key and arguments replays the original outcome under the declared contract; a new key can start another execution. Neither is a rollback.
