---
sidebar_position: 10.5
title: view_dive
description: Render a MotherDuck Dive as a live, interactive MCP app inside the host client.
feature_stage: preview
---

Render a [Dive](/key-tasks/ai-and-motherduck/dives) 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.

Use [`list_dives`](../list-dives) to find a Dive's ID before calling `view_dive`.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dive_id` | string (UUID) | Yes | The unique identifier of the Dive to render. |
| `required_resources` | array of `{ url, alias? }` | No | Override the Dive's source-declared `REQUIRED_DATABASES` for this preview. |
| `initial_state` | object | No | Seed 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

```json
[
  {
    "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`](../update-dive) instead.

### `initial_state` shape

```json
{
  "<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.

## Example usage

**Open a Dive in the host's dive viewer:**

```text
Open my revenue trends Dive
```

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

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

**Preview a Dive against a specific database:**

```text
Show me the customer analytics Dive against the staging share
```

```json
{
  "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:**

```text
Show me the sales overview Dive filtered to EMEA, last quarter
```

```json
{
  "dive_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "initial_state": {
    "region": "emea",
    "dateRange": { "start": "2026-01-01", "end": "2026-03-31" }
  }
}
```

## Data exports from the dive viewer

The MCP dive viewer supports data export through the Dive's [`exportAs`](/sql-reference/motherduck-sql-reference/ai-functions/dives/use-sql-query/#export-query-results) 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.

## Related resources

- [Creating visualizations with Dives](/key-tasks/ai-and-motherduck/dives/)
- [Embedding Dives in your web application](/key-tasks/ai-and-motherduck/dives/embedding-dives/) — the embed-session equivalents of `required_resources` and `initial_state`


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

Payload:

```json
{
  "page_path": "/sql-reference/mcp/view-dive/",
  "page_title": "view_dive",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed payloads, and `429` when rate-limited.