Skip to main content

Build Claude artifacts with live MotherDuck data

Build a Claude Cowork dashboard that queries MotherDuck on open or Refresh, using your Claude connector.

Prerequisites​

This guide covers Cowork artifacts introduced on August 19, 2026, not the earlier live artifacts system.

The example uses sample_data.nyc.taxi. If sample_data is missing, follow the sample datasets guide to restore the share for your region.

Create a connected artifact​

  1. In Claude Cowork, select Artifacts from the sidebar, then New artifact.

  2. Describe the table, metrics, filters, and refresh behavior:

    Build a NYC taxi dashboard backed by the MotherDuck connector.
    Query sample_data.nyc.taxi with the read-only query tool at runtime.
    Show the query timestamp, trip count, average total amount, average trip
    distance, and a chart grouped by passenger count. Add passenger-count
    filters and a Refresh button. Call MotherDuck when the artifact opens and
    when the user refreshes it. Do not embed query results in the source or
    save them in shared artifact storage.
    Return current_timestamp from the same query as the metrics and display it.
    Include loading, empty, and error states. Do not poll in the background.

  3. Review the source and SQL. Confirm that metrics come from query, not embedded values.

  4. Open the artifact. Claude shows the connectors and tools it requests.

  5. Leave the MotherDuck query tool enabled, and select Continue. Don't grant query_rw for this read-only dashboard.

Claude saves each viewer's tool approval. Tools requiring approval before every action aren't available to artifacts. See read-only access options.

Verify the live connection​

  1. Open the artifact and record the displayed query timestamp.
  2. Select Refresh and confirm that the timestamp changes after the query finishes.
  3. Change a filter. The timestamp should change if it queries MotherDuck, but not if it filters already-loaded rows.
  4. Close and reopen the artifact. Confirm that it queries MotherDuck again.

Use MotherDuck's current_timestamp, not a browser-generated timestamp, to verify database requests.

If a query fails, check the viewer's connection, tool permissions, table access, and SQL. Keep the last successful result visible with the error beside Refresh.

Share the artifact​

Artifacts that use connected apps can only be shared within your Claude organization. On Team and Enterprise plans, open Share, choose the audience, and select the version to share. Pro and Max plans don't offer organization sharing. See Claude's sharing options.

Each viewer approves the artifact's tools and uses their own MotherDuck connection. A query fails if that viewer can't access the database or table.

Stored data has separate sharing rules

Embedded results and shared artifact storage can expose data to viewers who can't query the original table. Remove data the audience shouldn't see before sharing. Never store an access token in the artifact.

Test with viewers who have different table permissions. Check both query results and stored content for unintended access.

Add writes only when needed​

Verify that your connector and organization policies let the artifact use query_rw. Test an insert and a targeted update in a test database, then check the rows from another MotherDuck client.

If the tool is available:

  • Offer fixed actions such as Add note or Mark reviewed.
  • Validate identifiers, lengths, allowed values, and date ranges before building SQL.
  • Show the target row and ask for confirmation before writing.
  • Return the affected row identifier and read the row again to update the display.

A confirmation dialog isn't a database permission boundary. The viewer's MotherDuck permissions must also limit the data they can change. If query_rw isn't available to the artifact, keep writes in the conversation or an application backend.

Control refreshes and compute use​

Use aggregate queries, bounded date ranges, and explicit Apply or Refresh controls. Avoid polling or querying after every keystroke unless the workflow needs it.

A completed request doesn't mean the Duckling has stopped. The hosted MCP server can reuse database instances, and other clients can use the same account. Check query history, the Duckling overview, and the cooldown configuration to inspect compute activity.

The Claude connector uses OAuth, not read scaling tokens. For concurrent reads across a pool of Ducklings, use a backend that accepts read scaling tokens.

  • OpenAI Sites: Build a hosted application with server-side MotherDuck access.
  • MotherDuck Dives: Keep the visualization in your MotherDuck workspace with versioning, sharing, and embedding.