Introducing Flights: agent-native data pipelines in MotherDuckJoin the livestream

Skip to main content

view_dive

Render a Dive as an interactive MCP app inside hosts that support the dive viewer. The tool fetches the Dive's source code and metadata from MotherDuck; the host's dive viewer compiles and renders it client-side.

Description​

The view_dive tool opens a Dive in the host's MCP dive viewer, where the agent and the user can interact with live data. Optional inputs let you preview the same Dive against different databases or with a specific starting UI state without re-saving the Dive.

The tool also returns dive_app_url — a chat-side link the agent can offer to open the same Dive in app.motherduck.com. When initial_state is supplied, it rides along in the URL so the linked-to Dive opens at the same configured view as the inline preview.

Use list_dives to find a Dive's ID before calling view_dive.

Input parameters​

ParameterTypeRequiredDescription
dive_idstring (UUID)YesThe unique identifier of the Dive to render.
required_resourcesarray of { url, alias? }NoOverride the Dive's source-declared REQUIRED_DATABASES for this preview.
initial_stateobjectNoSeed the Dive's initial UI state for this preview. Keys match those used by the useDiveState hook inside the Dive's code. Values must be JSON-serializable.

required_resources shape​

[
  {
    "url": "md:_share/<database>/<share_uuid>",
    "alias": "<local_alias>"
  }
]

url accepts a share URL (md:_share/<database>/<share_uuid>) or an owned database identifier (md:<database_name>). alias defaults to the database name from the URL when omitted.

When supplied, required_resources replaces the Dive's source-declared REQUIRED_DATABASES for the preview. Use it when the user wants to render a Dive against a specific share or embed configuration. For a permanent change to the Dive's target databases, edit the source and use update_dive instead.

initial_state shape​

{
  "<state_key>": <json_value>,
  "<another_key>": <json_value>
}

Each key matches a useDiveState(key, ...) call inside the Dive's source. Interactive changes during the preview do not round-trip back to the MCP host; pass another initial_state on the next call if you want to start from the new state. Do not use initial_state for ephemeral UI state (input drafts, dialog open/close) — those use plain useState inside the Dive.

Output schema​

{
  "success": boolean,
  "dive_id": string,             // UUID of the rendered Dive
  "title": string,               // Dive title
  "source": string,              // Full JSX/React component source
  "current_version": number,     // Latest version number for the Dive
  "dive_app_url": string,        // Chat-side link to open the Dive in app.motherduck.com
  "initial_state": object,       // Echoed back when supplied in the request
  "required_resources": array,   // Echoed back when supplied in the request
  "error": string                // Error message (on failure)
}

When initial_state is supplied, dive_app_url carries it in the URL fragment, so clicking the link opens the Dive at the same starting view as the inline preview. required_resources is not carried in dive_app_url: clicking the link opens the Dive against its source-declared REQUIRED_DATABASES, not the override. Use the embed session API if you need the override to survive into the linked-to Dive.

Example usage​

Open a Dive in the host's dive viewer:

Open my revenue trends Dive

The agent calls the tool with the Dive's ID:

{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Preview a Dive against a specific database:

Show me the customer analytics Dive against the staging share
{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "required_resources": [
    {
      "url": "md:_share/staging_data/9f4a2b8c-1234-5678-90ab-cdef01234567",
      "alias": "customer_analytics"
    }
  ]
}

Preview a Dive in a specific UI state:

Show me the sales overview Dive filtered to EMEA, last quarter
{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "initial_state": {
    "region": "emea",
    "dateRange": { "start": "2026-01-01", "end": "2026-03-31" }
  }
}

Success response example​

{
  "success": true,
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Monthly Revenue Trends",
  "source": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\n\nexport default function Dive() {\n  // ...\n}",
  "current_version": 3,
  "dive_app_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890/monthly-revenue-trends#state=eyJyZWdpb24iOiJlbWVhIn0",
  "initial_state": {
    "region": "emea"
  }
}

Error response example​

{
  "success": false,
  "error": "Dive 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found"
}

Data exports from the dive viewer​

The MCP dive viewer supports data export through the Dive's exportAs buttons. When a user starts an export, the dive viewer generates the file (CSV, Parquet, or XLSX) from the browser DuckDB connection:

  • Hosts that support file downloads receive the completed file directly through the MCP downloadFile capability.
  • Hosts that do not support downloadFile show a fallback dialog with a link back to the Dive in MotherDuck so the user can export there.

Exports do not require any additional view_dive parameters; they're enabled by the Dive's source code.