# Flights

> Create, schedule, run, and monitor Flights — scheduled Python jobs on MotherDuck compute — through the MotherDuck MCP server.

## Included pages

- [get_flight_guide](https://motherduck.com/docs/sql-reference/mcp/flights/get-flight-guide): Load the canonical instructions for authoring, scheduling, running, and troubleshooting MotherDuck Flights.
- [get_flight_viz_guide](https://motherduck.com/docs/sql-reference/mcp/flights/get-flight-viz-guide): Load the Flight Explainer convention, the chart and progress lines that make a Flight's runs viewable step by step.
- [list_flights](https://motherduck.com/docs/sql-reference/mcp/flights/list-flights): List Flights with summary metadata, optionally filtered by keywords.
- [get_flight](https://motherduck.com/docs/sql-reference/mcp/flights/get-flight): Fetch a Flight's metadata and version snapshot by UUID, optionally at a specific historical version.
- [list_flight_versions](https://motherduck.com/docs/sql-reference/mcp/flights/list-flight-versions): List the version history of a Flight, newest first.
- [create_flight](https://motherduck.com/docs/sql-reference/mcp/flights/create-flight): Create a new Flight from Python source code, requirements, and an optional schedule.
- [update_flight](https://motherduck.com/docs/sql-reference/mcp/flights/update-flight): Update a Flight's source, requirements, config, token, secrets, chart, name, or schedule.
- [edit_flight_source](https://motherduck.com/docs/sql-reference/mcp/flights/edit-flight-source): Edit a Flight's source code with one or more find-and-replace operations, producing a new version.
- [delete_flight](https://motherduck.com/docs/sql-reference/mcp/flights/delete-flight): Permanently delete a Flight, its versions, schedule, and run history.
- [run_flight](https://motherduck.com/docs/sql-reference/mcp/flights/run-flight): Trigger an on-demand execution of a Flight using its current version.
- [list_flight_runs](https://motherduck.com/docs/sql-reference/mcp/flights/list-flight-runs): List the execution history of a Flight, newest first.
- [get_flight_logs](https://motherduck.com/docs/sql-reference/mcp/flights/get-flight-run-logs): Fetch the logs and run record for a single Flight run.
- [cancel_flight_run](https://motherduck.com/docs/sql-reference/mcp/flights/cancel-flight-run): Cancel an in-progress Flight run.
- [view_flight_run](https://motherduck.com/docs/sql-reference/mcp/flights/view-flight-run): Open a Flight run in the Flight Explainer, a live step-by-step view of what each step did, inside the AI agent.
- [grant_access](https://motherduck.com/docs/sql-reference/mcp/flights/grant-access): Give users, roles, or your organization access to run a Flight you own, through the MCP server.
- [revoke_access](https://motherduck.com/docs/sql-reference/mcp/flights/revoke-access): Remove users', roles', or your organization's access to run a Flight, through the MCP server.

Source: https://motherduck.com/docs/category/flights

---

## get_flight_guide

Source: https://motherduck.com/docs/sql-reference/mcp/flights/get-flight-guide

> Load the canonical instructions for authoring, scheduling, running, and troubleshooting MotherDuck Flights.

Loads the authoritative guide for working with [Flights](/concepts/compute/flights). Call this tool first whenever the conversation turns to creating, updating, or operating a Flight, before reaching for any other `*_flight*` MCP tool.

## Description

`get_flight_guide` returns a single guide document covering: the anatomy of a Flight, the difference between config and secrets, scheduling, run lifecycle, and common failure patterns. It does not take any arguments.

The human-readable equivalent of this guide lives at the [Flights concept page](/concepts/compute/flights). The guide returned by this tool is what AI agents should consult inside an agent session.

## Input parameters

This tool takes no arguments.

## Output

The tool returns the guide as a plain-text markdown document, mirrored into structured content as:

```json
{
  "text": string  // Markdown content of the guide
}
```

## Organization Flight conventions

When [Guides](/key-tasks/guides/) are enabled, the returned guide includes a "Flight guides" section listing your organization's Flight conventions stored under the reserved `flights` topic. The AI assistant reads the relevant ones with [`get_guide`](/sql-reference/mcp/guides/get-guide) before authoring or operating a Flight.

To save personal Flight preferences for future sessions, ask the assistant to create a Guide with topic `flights` and access `user` through [`create_guide`](/sql-reference/mcp/guides/create-guide). Org-wide Flight conventions use access `organization`.

## Example usage

When the user asks for anything Flight-related, the assistant should call this tool before calling [`create_flight`](../create-flight) or other flight tools:

```text
Create a Flight that ingests Postgres data into MotherDuck hourly.
```

The assistant first calls `get_flight_guide`, reads the guide, and then proceeds to author the Flight.

## Related

- [`create_flight`](../create-flight) — Create a new Flight.
- [`list_flights`](../list-flights) — List the Flights you can see.
- [Flights concept](/concepts/compute/flights) — The human-readable overview.

---

## get_flight_viz_guide

Source: https://motherduck.com/docs/sql-reference/mcp/flights/get-flight-viz-guide

> Load the Flight Explainer convention, the chart and progress lines that make a Flight's runs viewable step by step.

Loads the guide to the [Flight Explainer](/key-tasks/flights/observability/explain-flight-runs) convention: the Mermaid chart a Flight declares and the `@flight-run` and `@flight-log` lines it prints, so its runs can be viewed step by step with per-step status and timing. An AI agent calls it first whenever you ask the agent to visualize, chart, watch, or review a Flight's progress.

## Description

`get_flight_viz_guide` returns the full Flight Explainer guide, or one section of it for a narrow lookup. Your AI agent loads the whole guide when it adds or changes instrumentation, adds fan-out, branches, child Flights, timing, or progress, or interprets a nontrivial run, because those tasks span sections.

The CLI equivalent is [`motherduck flight guide --explainer`](/sql-reference/motherduck-cli/flight/#flight-guide).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `section` | string | No | Load one section only: `chart` (Mermaid declarations, node kinds and meters, labeled edges, child-Flight nodes), `grammar` (`@flight-run` and `@flight-log` events, fields, effects, JSON mode, status roll-up, branches), `emitting` (Python `print` and helper patterns), or `examples` (a worked Flight). Omit to load the whole guide. |

## Output

The tool returns JSON with `success` and the `guide` text. A single section ends with a note on what the excerpt leaves out.

## Example usage

```text
Add a Flight Explainer to the orders_nightly Flight without changing what it does.
```

The AI agent calls `get_flight_viz_guide`, reads the Flight with [`get_flight`](../get-flight), saves the chart and progress lines with [`update_flight`](../update-flight), and opens the next run with [`view_flight_run`](../view-flight-run).

## Related

- [Watch Flight run progress with the Flight Explainer](/key-tasks/flights/observability/explain-flight-runs) — the human-readable version of the convention, with examples.
- [`get_flight_guide`](../get-flight-guide) — The general Flight authoring guide.
- [`view_flight_run`](../view-flight-run) — Open a run in the Flight Explainer.

---

## list_flights

Source: https://motherduck.com/docs/sql-reference/mcp/flights/list-flights

> List Flights with summary metadata, optionally filtered by keywords.

List [Flights](/concepts/compute/flights) the caller can see: Users can see Flights they have created. [Admins](/concepts/security-and-access/roles-and-access-control/) can see Flights they own as well as any Flight in the organization. Each Flight in the response includes its UUID, name, schedule, status, current version, and owner. Optionally filter by keywords matching the Flight name.

## Description

The `list_flights` tool returns Flight summary metadata, not version-specific content. Use [`get_flight`](../get-flight) with the returned `flight_id` to fetch source code, requirements, and config.

The corresponding SQL function is [`MD_LIST_FLIGHTS`](/sql-reference/motherduck-sql-reference/flights/md-list-flights).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `keywords` | string | No | Keywords to filter Flights by name (case-insensitive, all words must match). |
| `owner_only` | boolean | No | Restrict the listing to Flights you own. Meaningful for Admins, who see the whole organization's Flights by default; ignored for other users. |
| `limit` | integer | No | Max results to return (default: 50, max: 50). |
| `offset` | integer | No | Number of Flights to skip, for paging through results. |

## Output schema

```json
{
  "success": boolean,
  "flights": [
    {
      "flight_id": string,             // Flight UUID
      "flight_name": string,
      "created_at": string,            // ISO 8601
      "updated_at": string,            // ISO 8601
      "schedule_cron": string|null,    // Cron expression or null for on-demand
      "status": string,                // Flight status, for example ACTIVE
      "schedule_status": string|null,  // Schedule status, for example ACTIVE
      "current_version": number,
      "owner_name": string|null        // The user who owns the Flight
    }
  ],
  "count": number,
  "totalCount": number,
  "truncated": boolean,                // Present when results were capped
  "message": string,                   // Present when results were capped
  "error": string                      // On failure
}
```

## Example usage

```text
What Flights do I have?
```

The assistant calls the tool with no arguments. To filter:

```json
{ "keywords": "metrics" }
```

An Admin sees the whole organization's Flights by default, with `owner_name` identifying whose each one is. To view your own Flights, use the following to filter results:

```json
{ "owner_only": true }
```

## Related

- [`get_flight`](../get-flight) — Fetch a single Flight's content.
- [`MD_LIST_FLIGHTS`](/sql-reference/motherduck-sql-reference/flights/md-list-flights) — SQL equivalent.

---

## get_flight

Source: https://motherduck.com/docs/sql-reference/mcp/flights/get-flight

> Fetch a Flight's metadata and version snapshot by UUID, optionally at a specific historical version.

Fetch a single [Flight](/concepts/compute/flights). Returns Flight metadata plus the content of a specific version (source code, requirements, config, secret names, token name). Omit `version` for the current version; pass a 1-indexed `version` to inspect history.

## Description

The `get_flight` tool combines metadata and version content into one response, so the agent doesn't need separate calls for "find the Flight" and "read its source." Use it to inspect a Flight before editing, or to read the source that ran for a specific past run.

Users can fetch Flights they have created. [Admins](/concepts/security-and-access/roles-and-access-control/) can fetch Flights they own as well as any Flight in the organization. Only the Flight creator can edit or delete it. Others can run it with a [`run` grant](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight).
The SQL equivalent is [`MD_GET_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-get-flight) plus [`MD_GET_FLIGHT_VERSION`](/sql-reference/motherduck-sql-reference/flights/md-get-flight-version).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `version` | integer | No | 1-indexed version number. Omit for the current version. |

## Output schema

```json
{
  "success": boolean,
  "flight": {
    "flight_id": string,
    "flight_name": string,
    "created_at": string,
    "updated_at": string,
    "schedule_cron": string|null,
    "status": string,
    "schedule_status": string|null,
    "current_version": number,
    "owner_name": string|null,       // The user who owns the Flight
    "version_info": {
      "version_id": string,
      "flight_id": string,
      "version": number,
      "created_at": string,
      "source_code": string,
      "requirements_txt": string|null,
      "config": { "<key>": "<value>" },
      "access_token_name": string,
      "flight_secret_names": string[],
      "metadata": { "chart": string }, // The run chart for the Flight Explainer; {} when none was ever saved, chart "" after it is cleared
      "max_runtime_sec": number      // Per-run timeout in seconds; 0 means none
    }
  },
  "error": string
}
```

## Example usage

Inspect the current Flight:

```json
{ "id": "80000000-0000-0000-0000-000000000001" }
```

Inspect version 2:

```json
{ "id": "80000000-0000-0000-0000-000000000001", "version": 2 }
```

## Related

- [`list_flight_versions`](../list-flight-versions) — Find available version numbers.
- [`list_flight_runs`](../list-flight-runs) — Each run includes the version it ran against.
- [`MD_GET_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-get-flight) — SQL equivalent for current summary.

---

## list_flight_versions

Source: https://motherduck.com/docs/sql-reference/mcp/flights/list-flight-versions

> List the version history of a Flight, newest first.

List every immutable version of a [Flight](/concepts/compute/flights), newest first. Each update to `source_code`, `requirements_txt`, `config`, `access_token_name`, `flight_secret_names`, or the chart in `metadata` produces a fresh version. Sending the same chart again does not. Updates to `name` or `schedule_cron` are metadata-only and do not appear here.

## Description

Use `list_flight_versions` to browse what changed between versions, or to find the version a specific run executed. The corresponding SQL function is [`MD_LIST_FLIGHT_VERSIONS`](/sql-reference/motherduck-sql-reference/flights/md-list-flight-versions).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `limit` | integer | No | Max results to return (default: 50, max: 50). |
| `offset` | integer | No | Number of versions to skip, for paging back through history. |

## Output schema

```json
{
  "success": boolean,
  "versions": [
    {
      "version_id": string,
      "flight_id": string,
      "version": number,
      "created_at": string,
      "access_token_name": string,
      "flight_secret_names": string[],
      "config": { "<key>": "<value>" },
      "max_runtime_sec": number,
      "instance_type": string|null
    }
  ],
  "count": number,
  "error": string
}
```

## Example usage

```json
{ "id": "80000000-0000-0000-0000-000000000001" }
```

## Related

- [`get_flight`](../get-flight) — Fetch one version's full content.
- [`list_flight_runs`](../list-flight-runs) — Runs reference the version they used.
- [`MD_LIST_FLIGHT_VERSIONS`](/sql-reference/motherduck-sql-reference/flights/md-list-flight-versions) — SQL equivalent.

---

## create_flight

Source: https://motherduck.com/docs/sql-reference/mcp/flights/create-flight

> Create a new Flight from Python source code, requirements, and an optional schedule.

Create a new [Flight](/concepts/compute/flights). A Flight is a Python entrypoint plus an optional `requirements.txt` that runs on MotherDuck compute. Optionally provide `access_token_name` to run the Flight as a specific access token; omit it to use the default `MotherDuck Flights` access token. Optionally provide a 5-field cron expression to run on a schedule.

You are responsible for the code you run and the packages it installs. Flights does not scan customer code or dependencies. Avoid untrusted packages, pin dependency versions, and treat dependency installs as a supply-chain risk.

Call [`get_flight_guide`](../get-flight-guide) first if you need the authoring reference.

## Description

`create_flight` is the marquee entry point for the MCP Flights surface. The SQL equivalent is [`MD_CREATE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-create-flight).

The tool uses the same parameter names as [`MD_CREATE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-create-flight): `access_token_name` and `flight_secret_names`.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | Flight name (used in logs and listings). |
| `source_code` | string | Yes | Python source for the Flight. A single-file program, executed as a plain script; end it with `if __name__ == "__main__": main()` to invoke your entrypoint. |
| `access_token_name` | string | No | Label of a MotherDuck access token to run the Flight as. Injected as `MOTHERDUCK_TOKEN` at runtime. Omit it to use the default `MotherDuck Flights` access token. List labels with `SELECT * FROM md_access_tokens();`. |
| `schedule_cron` | string | No | 5-field cron expression in UTC. Omit for on-demand only. |
| `requirements_txt` | string | No | `requirements.txt` contents, one pinned package per line. |
| `config` | object | No | Non-secret key/value pairs surfaced as environment variables. |
| `flight_secret_names` | string[] | No | Names of [Flight secrets](/sql-reference/motherduck-sql-reference/create-secret#flight-secrets) whose key-value pairs are surfaced as environment variables. |
| `metadata` | object | No | Flight control metadata. The only supported key is `chart`: the run chart for the [Flight Explainer](/key-tasks/flights/observability/explain-flight-runs), as raw Mermaid starting at the `flowchart` line. Limited to 64 KiB as UTF-8. See [`get_flight_viz_guide`](../get-flight-viz-guide). |
| `max_runtime_sec` | integer | No | Per-run timeout in seconds. `0` means no timeout. Omit to use your plan's default. A value above your plan's cap is rejected. |
| `instance_type` | string | No | [Instance size](/about-motherduck/billing/flight-sizes/): `F4`, `F16`, or `F32`. Omit to use your plan's default. A size above your plan's cap is rejected. |

## Output schema

```json
{
  "success": boolean,
  "flight": {
    "id": string,
    "name": string,
    "schedule_cron": string|null,
    "current_version": number
  },
  "error": string
}
```

## Example usage

Minimal Flight:

```json
{
  "name": "heartbeat",
  "source_code": "import duckdb\n\ndef main():\n    duckdb.connect('md:').execute('SELECT 1').fetchall()\n    print('ok')\n\nif __name__ == \"__main__\":\n    main()\n",
  "requirements_txt": "duckdb==1.5.3"
}
```

Scheduled Flight with config, running as a specific access token:

```json
{
  "name": "hourly_metrics",
  "source_code": "...",
  "access_token_name": "analytics_token",
  "requirements_txt": "duckdb==1.5.3\nrequests==2.32.4",
  "schedule_cron": "0 * * * *",
  "config": { "REGION": "eu-central-1" }
}
```

## Related

- [`update_flight`](../update-flight) — Modify an existing Flight.
- [`edit_flight_source`](../edit-flight-source) — Surgical source edit.
- [`run_flight`](../run-flight) — Trigger a manual run after creation.
- [`MD_CREATE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-create-flight) — SQL equivalent.

---

## update_flight

Source: https://motherduck.com/docs/sql-reference/mcp/flights/update-flight

> Update a Flight's source, requirements, config, token, secrets, chart, name, or schedule.

Update a [Flight](/concepts/compute/flights). Any subset of `name`, `source_code`, `requirements_txt`, `schedule_cron`, `config`, `access_token_name`, `flight_secret_names`, `max_runtime_sec`, `instance_type`, or `metadata` may be provided.

Updates to `source_code`, `requirements_txt`, `config`, `flight_secret_names`, `access_token_name`, `max_runtime_sec`, `instance_type`, or the chart in `metadata` produce a new `FlightVersion`. Updates to `name` or `schedule_cron` are metadata-only. Sending the chart the Flight already has does not create a version.

You are responsible for the code you run and the packages it installs. Flights does not scan customer code or dependencies. Avoid untrusted packages, pin dependency versions, and treat dependency installs as a supply-chain risk.

## Description

`update_flight` is a PATCH operation: omitted fields are left unchanged. To clear the schedule, pass `schedule_cron` as an empty string; omitting it leaves the schedule unchanged.

`config` and `flight_secret_names` are **full replacements** — to change one entry, send the full map or list with the change applied.

The SQL equivalent is [`MD_UPDATE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-update-flight).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `name` | string | No | Updated Flight name. Metadata-only. |
| `schedule_cron` | string | No | Updated 5-field cron expression (UTC). Pass `""` to clear the schedule. Metadata-only. |
| `source_code` | string | No | Updated Python entrypoint source. Bumps the version. |
| `requirements_txt` | string | No | Updated `requirements.txt` contents. Bumps the version. |
| `config` | object | No | Replacement config map (full replace). Bumps the version. |
| `access_token_name` | string | No | Updated MotherDuck access token label. Bumps the version. |
| `flight_secret_names` | string[] | No | Replacement list of secret names (full replace). Bumps the version. |
| `metadata` | object | No | Flight control metadata. The only supported key is `chart`: the run chart for the [Flight Explainer](/key-tasks/flights/observability/explain-flight-runs), as raw Mermaid. Limited to 64 KiB as UTF-8. Pass `""` to clear the chart. Bumps the version when the chart changes. |
| `max_runtime_sec` | integer | No | Per-run timeout in seconds. `0` means no timeout. A value above your plan's cap is rejected. Bumps the version. |
| `instance_type` | string | No | [Instance size](/about-motherduck/billing/flight-sizes/): `F4`, `F16`, or `F32`. A size above your plan's cap is rejected. Bumps the version. |

## Output schema

```json
{
  "success": boolean,
  "flight": {
    "id": string,
    "name": string,
    "schedule_cron": string|null,
    "current_version": number
  },
  "error": string
}
```

## Example usage

Rename only:

```json
{ "id": "80000000-...", "name": "analytics_hourly_sync" }
```

Update source (bumps version):

```json
{
  "id": "80000000-...",
  "source_code": "def main():\n    print('v2')\n\nif __name__ == \"__main__\":\n    main()\n"
}
```

Clear the schedule:

```json
{ "id": "80000000-...", "schedule_cron": "" }
```

## Related

- [`edit_flight_source`](../edit-flight-source) — Edit source without resending the whole file.
- [`get_flight`](../get-flight) — Read current state before editing.
- [`MD_UPDATE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-update-flight) — SQL equivalent.

---

## edit_flight_source

Source: https://motherduck.com/docs/sql-reference/mcp/flights/edit-flight-source

> Edit a Flight's source code with one or more find-and-replace operations, producing a new version.

Edit a [Flight](/concepts/compute/flights)'s `source_code` by applying one or more text replacements, then save as a new `FlightVersion`. The tool reads the current source, applies the edits in sequence, validates the result, and persists.

You are responsible for the code you run. Flights does not scan customer code. Avoid untrusted code and treat source edits as a security-sensitive change.

Use this when you want to change a small part of a Flight without resending the entire file through [`update_flight`](../update-flight).

## Description

Each edit is a `{old_string, new_string, replace_all?}` object. `old_string` must occur exactly once in the source unless `replace_all` is true. Edits apply sequentially: edit N sees the source after edits 1 through N-1.

No prior `get_flight` call is required — the tool reads the current source itself.

This tool is MCP-only; there is no direct SQL equivalent. To achieve the same outcome in SQL, read the source through [`MD_GET_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-get-flight), modify it client-side, and call [`MD_UPDATE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-update-flight) with the full updated source.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `edits` | array | Yes | List of edit objects (see below). Must contain at least one. |

Each entry in `edits`:

| Field | Type | Required | Description |
|---|---|---|---|
| `old_string` | string | Yes | Exact text to find and replace. Must be unique in the source unless `replace_all` is true. |
| `new_string` | string | Yes | The replacement text. Must differ from `old_string`. |
| `replace_all` | boolean | No | If true, replace every occurrence. Default `false`. |

## Output schema

```json
{
  "success": boolean,
  "flight": {
    "id": string,
    "name": string,
    "current_version": number
  },
  "error": string
}
```

## Example usage

Change one line:

```json
{
  "id": "80000000-...",
  "edits": [
    {
      "old_string": "duckdb==1.5.2",
      "new_string": "duckdb==1.5.3"
    }
  ]
}
```

Rename every occurrence of a variable:

```json
{
  "id": "80000000-...",
  "edits": [
    {
      "old_string": "raw_table",
      "new_string": "raw_events",
      "replace_all": true
    }
  ]
}
```

## Related

- [`update_flight`](../update-flight) — Send a full replacement source.
- [`get_flight`](../get-flight) — Inspect the source before editing.
- [`list_flight_versions`](../list-flight-versions) — See the versions created by edits.

---

## delete_flight

Source: https://motherduck.com/docs/sql-reference/mcp/flights/delete-flight

> Permanently delete a Flight, its versions, schedule, and run history.

Permanently delete a [Flight](/concepts/compute/flights), including all versions, schedule, and run history. This action cannot be undone.

The SQL equivalent is [`MD_DELETE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-delete-flight).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |

## Output schema

```json
{
  "success": boolean,
  "error": string
}
```

## Example usage

```json
{ "id": "80000000-0000-0000-0000-000000000001" }
```

After deletion, calls to other `*_flight*` tools with the same `id` return `does not exist`.

## Related

- [`list_flights`](../list-flights) — Verify the Flight is gone.
- [`MD_DELETE_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-delete-flight) — SQL equivalent.

---

## run_flight

Source: https://motherduck.com/docs/sql-reference/mcp/flights/run-flight

> Trigger an on-demand execution of a Flight using its current version.

Trigger an on-demand execution of a [Flight](/concepts/compute/flights). Returns a Run record immediately; the run is asynchronous and starts in `PENDING` or `RUNNING`. Use [`list_flight_runs`](../list-flight-runs) to poll for completion and [`get_flight_logs`](../get-flight-run-logs) to read the output.

The SQL equivalent is [`MD_RUN_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-run-flight).

## Description

`run_flight` locks the new run to the Flight's current version. Subsequent updates to the Flight do not affect this run; only the next run picks up the updated source.

Pass `config` to override stored config values for a single run. You can override only keys the Flight already defines; the override applies to that run alone and leaves the stored config and version untouched.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `config` | object | No | Per-run config overrides as a JSON object of string key-value pairs. Only keys already defined on the Flight can be set. |

## Output schema

```json
{
  "success": boolean,
  "run": {
    "run_id": string,
    "flight_id": string,
    "flight_name": string,
    "flight_version": number,
    "config": object,         // effective config for this run, including per-run overrides
    "run_number": number,
    "is_scheduled": boolean,  // false for on-demand
    "status": string,         // PENDING | RUNNING
    "created_at": string,
    "started_at": null,       // timing fields are still null when run_flight returns
    "ended_at": null,
    "scheduled_at": string,
    "cancelled_at": null,
    "exit_code": null
  },
  "error": string
}
```

## Example usage

```json
{ "id": "80000000-0000-0000-0000-000000000001" }
```

With a per-run config override:

```json
{ "id": "80000000-0000-0000-0000-000000000001", "config": { "REGION": "eu-central-1" } }
```

## Related

- [`list_flight_runs`](../list-flight-runs) — Watch for completion.
- [`get_flight_logs`](../get-flight-run-logs) — Read stdout/stderr.
- [`cancel_flight_run`](../cancel-flight-run) — Cancel an in-progress run.
- [`MD_RUN_FLIGHT`](/sql-reference/motherduck-sql-reference/flights/md-run-flight) — SQL equivalent.

---

## list_flight_runs

Source: https://motherduck.com/docs/sql-reference/mcp/flights/list-flight-runs

> List the execution history of a Flight, newest first.

List the runs of a [Flight](/concepts/compute/flights), newest first. Each run has a sequential `run_number`, a status (`PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, or `CANCELLED`), timing metadata, and the effective `config` it ran with: the Flight version's stored config merged with any [per-run overrides](../run-flight).

The SQL equivalent is [`MD_LIST_FLIGHT_RUNS`](/sql-reference/motherduck-sql-reference/flights/md-list-flight-runs).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `limit` | integer | No | Max results to return (default: 100, max: 500). |

## Output schema

```json
{
  "success": boolean,
  "flight_id": string,
  "runs": [
    {
      "run_id": string,
      "flight_id": string,
      "flight_name": string,
      "flight_version": number,
      "config": object,         // effective config for the run, including per-run overrides
      "run_number": number,
      "is_scheduled": boolean,
      "status": string,
      "created_at": string,
      "started_at": string,
      "ended_at": string,
      "scheduled_at": string,
      "cancelled_at": string,   // null unless the run was cancelled
      "exit_code": number
    }
  ],
  "count": number,
  "totalCount": number,
  "error": string
}
```

## Example usage

```json
{ "id": "80000000-0000-0000-0000-000000000001", "limit": 10 }
```

## Related

- [`run_flight`](../run-flight) — Trigger an on-demand run.
- [`get_flight_logs`](../get-flight-run-logs) — Read a run's output.
- [`cancel_flight_run`](../cancel-flight-run) — Cancel an in-progress run.
- [`MD_LIST_FLIGHT_RUNS`](/sql-reference/motherduck-sql-reference/flights/md-list-flight-runs) — SQL equivalent.

---

## get_flight_logs

Source: https://motherduck.com/docs/sql-reference/mcp/flights/get-flight-run-logs

> Fetch the logs and run record for a single Flight run.

Fetch the plain-text combined stdout and stderr of a [Flight](/concepts/compute/flights) run, plus the matching `Run` record (status, exit code, timing). The response also reports whether the log was truncated.

The SQL equivalent is [`MD_GET_FLIGHT_LOGS`](/sql-reference/motherduck-sql-reference/flights/md-get-flight-logs) — note that the SQL surface returns only the logs, while this MCP tool also returns the run record.

## Description

Use `get_flight_logs` to interpret a failed run without a follow-up call: status, exit code, and timing arrive in the same response as the log content. For runs with large logs, pass `max_bytes` to cap the response size; the response returns the tail and sets `truncated: true`.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `run_number` | integer | Yes | Sequential run number from [`list_flight_runs`](../list-flight-runs). |
| `limit` | integer | No | Maximum log lines to return. Defaults to 200. |
| `offset` | integer | No | Number of lines to skip, counted from the end `order` reads from. |
| `order` | string | No | `desc` reads from the last log line, `asc` from the first. Defaults to `desc`. |
| `max_bytes` | integer | No | Maximum log bytes to return. Minimum 1024. Truncation keeps the end `order` reads from. |

## Output schema

```json
{
  "success": boolean,
  "flight_id": string,
  "run_number": number,
  "run": {
    "run_id": string,
    "flight_id": string,
    "flight_name": string,
    "flight_version": number,
    "config": object,          // effective config for the run, including per-run overrides
    "run_number": number,
    "is_scheduled": boolean,
    "status": string,          // PENDING | RUNNING | SUCCEEDED | FAILED | CANCELLED
    "created_at": string,
    "started_at": string|null,
    "ended_at": string|null,
    "scheduled_at": string,
    "cancelled_at": string|null,
    "exit_code": number|null
  },
  "logs": string,              // Combined stdout + stderr
  "truncated": boolean,        // True if max_bytes truncated the log
  "original_length": number,   // Full log length in bytes, present when truncated
  "error": string
}
```

## Example usage

Read the last 200 lines of run 42:

```json
{ "id": "80000000-...", "run_number": 42 }
```

Read only the last 4 KB:

```json
{ "id": "80000000-...", "run_number": 42, "max_bytes": 4096 }
```

## Related

- [`list_flight_runs`](../list-flight-runs) — Find the `run_number` to read.
- [`MD_GET_FLIGHT_LOGS`](/sql-reference/motherduck-sql-reference/flights/md-get-flight-logs) — SQL equivalent (logs only).

---

## cancel_flight_run

Source: https://motherduck.com/docs/sql-reference/mcp/flights/cancel-flight-run

> Cancel an in-progress Flight run.

Cancel an in-progress run of a [Flight](/concepts/compute/flights), identified by the Flight UUID and the sequential `run_number` (from [`list_flight_runs`](../list-flight-runs)).

Returns `canceled: true` on a successful transition. Calling on an already-terminal run (`SUCCEEDED`, `FAILED`, `CANCELLED`) or one that doesn't exist returns a tool error.

The SQL equivalent is [`MD_CANCEL_FLIGHT_RUN`](/sql-reference/motherduck-sql-reference/flights/md-cancel-flight-run).

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `run_number` | integer | Yes | Sequential run number to cancel. |

## Output schema

```json
{
  "success": boolean,
  "canceled": boolean,
  "error": string
}
```

## Example usage

```json
{ "id": "80000000-0000-0000-0000-000000000001", "run_number": 42 }
```

## Related

- [`list_flight_runs`](../list-flight-runs) — Find runs that are still in progress.
- [`run_flight`](../run-flight) — Trigger a new run.
- [`MD_CANCEL_FLIGHT_RUN`](/sql-reference/motherduck-sql-reference/flights/md-cancel-flight-run) — SQL equivalent.

---

## view_flight_run

Source: https://motherduck.com/docs/sql-reference/mcp/flights/view-flight-run

> Open a Flight run in the Flight Explainer, a live step-by-step view of what each step did, inside the AI agent.

Open a run of a [Flight](/concepts/compute/flights) in the [Flight Explainer](/key-tasks/flights/observability/explain-flight-runs): the Flight's declared chart as a step-by-step view, each step colored by what the run did, with its timing, rows, effects, and errors.

In clients that support MCP apps, the Flight Explainer opens inline in the conversation and updates while the run executes:

## Description

Use `view_flight_run` instead of [`get_flight_logs`](../get-flight-run-logs) when you want to see how a run went in your preferred AI tool rather than read its raw output. The view also links to the run in the MotherDuck UI.

A Flight that declares a chart and prints `@flight-run` lines is drawn as a diagram. A Flight without a chart opens a run view of its timing, config, and log instead, and the result reports `has_chart: false`. To add a chart, load the convention with [`get_flight_viz_guide`](../get-flight-viz-guide).

The CLI equivalent is [`motherduck flight explain`](/sql-reference/motherduck-cli/flight/#flight-explain), which prints the steps. `--open` also opens the run in the app.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | string (UUID) | Yes | The Flight UUID. |
| `run_number` | integer | No | Sequential run number to open, from [`list_flight_runs`](../list-flight-runs). Omit for the most recent run. |

## Output schema

The text result summarizes the run for the agent. The chart, log, config, and timing go to the Flight Explainer view, not into the conversation.

```json
{
  "success": boolean,
  "flight_id": string,
  "flight_name": string,
  "run_number": number,
  "flight_version": number,
  "status": string,          // Run status, for example SUCCEEDED or FAILED
  "outcome": string|null,    // "ok", "failed", or "cancelled"; null while the run is in progress
  "exit_code": number|null,
  "log_lines": number,       // Log lines read for the view
  "has_chart": boolean,      // false when the run's version declares no chart
  "truncated": boolean       // true when the log was longer than the view reads
}
```

## Example usage

Open the latest run:

```json
{ "id": "80000000-0000-0000-0000-000000000001" }
```

Open run 42:

```json
{ "id": "80000000-0000-0000-0000-000000000001", "run_number": 42 }
```

A typical prompt:

```text
Run the orders_nightly Flight and show me how the run went.
```

The agent calls [`run_flight`](../run-flight), then `view_flight_run` with the returned run number.

## Related

- [Watch Flight run progress with the Flight Explainer](/key-tasks/flights/observability/explain-flight-runs) — add a chart and progress lines to a Flight.
- [`get_flight_viz_guide`](../get-flight-viz-guide) — Load the chart and progress-line convention.
- [`get_flight_logs`](../get-flight-run-logs) — Read a run's raw output.
- [`list_flight_runs`](../list-flight-runs) — Find run numbers.

---

## grant_access

Source: https://motherduck.com/docs/sql-reference/mcp/flights/grant-access

> Give users, roles, or your organization access to run a Flight you own, through the MCP server.

Give users, roles, or your whole organization `run` access to a [Flight](/concepts/compute/flights) you own, for example so viewers can run it from a [Dive app](/key-tasks/dives/run-flights-from-dives). The SQL equivalent is [`GRANT RUN ON FLIGHT`](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight).

## Description

Only a Flight's owner can grant `run` on it; an Admin who tries gets `Only the owner of this Flight can add grants`. A run always uses the owner's token and secrets, whoever starts it. When you ask your AI agent to share a Dive that runs Flights, it recommends which Flights to grant and to whom, and grants only after you confirm.

A user grantee needs the MotherDuck username, not an email address. For a group of people, grant to a role.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `resource_type` | string | Yes | `"flight"`. |
| `id` | string (UUID) | Yes | The Flight UUID. |
| `grantees` | object[] | Yes | 1 to 100 grantees, each `{ "type": "user" \| "role" \| "organization", "name": string }`. Omit `name` for the organization, or pass `null`; any other name for an organization grantee is an error. An unknown name fails the whole call. |
| `permission` | string | No | `"run"`, the only permission a Flight supports and the default. |

## Output schema

On success:

```json
{
  "success": true,
  "resource_type": "flight",
  "id": string,
  "permission": "run",
  "grantees": [{ "type": string, "name": string }]
}
```

`grantees` echoes the grantees you passed. An organization grantee has no `name`.

On failure, only the error:

```json
{
  "success": false,
  "error": string
}
```

## Example usage

```json
{
  "resource_type": "flight",
  "id": "7b1e2c3d-0000-4000-8000-000000000001",
  "grantees": [{ "type": "role", "name": "order_approvers" }]
}
```

A typical prompt:

```text
Let the order_approvers role run the decide_order Flight.
```

## Related

- [`revoke_access`](../revoke-access) — Remove `run` access.
- [`GRANT RUN ON FLIGHT`](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight) — SQL equivalent, plus `SHOW GRANTS ON FLIGHT`.
- [Build Dive apps](/key-tasks/dives/run-flights-from-dives)

---

## revoke_access

Source: https://motherduck.com/docs/sql-reference/mcp/flights/revoke-access

> Remove users', roles', or your organization's access to run a Flight, through the MCP server.

Remove `run` access to a [Flight](/concepts/compute/flights) you own from users, roles, or your whole organization. Organization Admins can also revoke `run` grants on Flights they don't own. The SQL equivalent is [`REVOKE RUN ON FLIGHT`](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight).

## Description

Revoking a grant that doesn't exist succeeds and changes nothing. Other grants on the Flight stay in place.

## Input parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `resource_type` | string | Yes | `"flight"`. |
| `id` | string (UUID) | Yes | The Flight UUID. |
| `grantees` | object[] | Yes | 1 to 100 grantees, each `{ "type": "user" \| "role" \| "organization", "name": string }`. Omit `name` for the organization, or pass `null`; any other name for an organization grantee is an error. An unknown name fails the whole call. |
| `permission` | string | No | `"run"`, the default. |

## Output schema

On success:

```json
{
  "success": true,
  "resource_type": "flight",
  "id": string,
  "permission": "run",
  "grantees": [{ "type": string, "name": string }]
}
```

`grantees` echoes the grantees you passed. An organization grantee has no `name`.

On failure, only the error:

```json
{
  "success": false,
  "error": string
}
```

## Example usage

```json
{
  "resource_type": "flight",
  "id": "7b1e2c3d-0000-4000-8000-000000000001",
  "grantees": [{ "type": "organization" }]
}
```

## Related

- [`grant_access`](../grant-access) — Give `run` access.
- [`REVOKE RUN ON FLIGHT`](/sql-reference/motherduck-sql-reference/flights/grant-run-on-flight) — SQL equivalent.

---