Ask docs question
Ask a question about DuckDB or MotherDuck. Returns answers from official documentation.
ActionTry it
Integrate MotherDuck MCP
with your AI CRM
Explore MotherDuck database schemas, query data, and manage Dives, Flights, and Guides through MotherDuck’s official hosted MCP server. Includes SQL writes, scheduled Python jobs, sharing, and deletion tools.
Explore Triggers and Actions
Cancel flight run
Cancel an in-flight run of a flight. Identified by the flight UUID and the sequential run number (from list_flight_runs). Returns `canceled: true` on a successful transition; calling on an already-terminal run or one that doesn't exist returns a tool error.
ActionTry it
Create flight
Create a new MotherDuck flight. Read the flight guide before you create your first flight. A flight is a Python entrypoint (`source_code`) plus an optional `requirements_txt` that runs on MotherDuck compute. Optionally provide an `access_token_name` so the flight can connect to MotherDuck at runtime; omit it to use the default MotherDuck Flights access token. Optionally provide a 5-field cron expression to run on a schedule, an optional `max_runtime_sec` to cap how long a run may take, and an optional `instance_type` (F4, F16 or F32) to pick the runner size. Use flights for ELT/ETL pipelines, loading external data into MotherDuck, refreshing materialized views, or any recurring Python job that reads/writes MotherDuck data.
ActionTry it
Create guide
Create a new guide — a markdown document that agents read to answer this org's data questions correctly (metric definitions, join/filter conventions, pitfalls). Group related guides with a lowercase kebab-case `topic` (e.g. 'revenue-billing' or 'core/metrics'); omit it for a guide without a topic. Visibility is controlled by `access`: 'user' (private, default) or 'organization' (org-wide, permission-gated). Personal dive/flight style guides belong under topic 'dives' / 'flights' with access 'user'. Attach `references` to the 1–5 objects the guide is authoritative about.
ActionTry it
Delete dive
Delete a dive by ID. This action is permanent and cannot be undone.
ActionTry it
Delete flight
Permanently delete a flight, its versions, schedule, and run history. This action cannot be undone.
ActionTry it
Delete guide
Soft-delete a guide while preserving its version history. Identify it by `uuid`.
ActionTry it
Dive query
Execute a read-only DuckDB query on behalf of a dive. This tool is used by the dive viewer and is not intended for direct use by the AI assistant.
ActionTry it
Edit dive content
Edit a dive's content by applying one or more text replacements, then save to MotherDuck. Accepts `id` (dive UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current content from MotherDuck, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior read_dive call is needed.
ActionTry it
Edit flight source
Edit a flight's source_code by applying one or more text replacements, then save as a new FlightVersion. Accepts `id` (flight UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current source_code, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_flight call is needed.
ActionTry it
Edit guide content
Edit a guide's markdown body by applying one or more text replacements, then save as a new version. Identify the guide by `uuid`. Reads the stored guide, applies edits in sequence, and persists. Example: {uuid: '<guide uuid>', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_guide call is needed.
ActionTry it
Get dive guide
Load instructions for creating MotherDuck dives. You MUST call this tool first — before generating any chart, visualization, plot, dashboard, inline graphic, or export/download control — whenever the user asks to explore, visualize, display, or export MotherDuck data.
ActionTry it
Get flight
Fetch a flight by UUID. Returns metadata plus a version snapshot (source code, requirements, config, secret names, token name). Omit `version` to get the current version; pass a 1-indexed version number to inspect history.
ActionTry it
Get flight guide
Load instructions for authoring, scheduling, running, and troubleshooting MotherDuck flights. Call this tool first whenever the user asks about creating, updating, or operating a MotherDuck flight.
ActionTry it
Get flight logs
Fetch the plain-text logs (stdout + stderr) of a flight run plus the matching `Run` record (status, exit_code, timing). Returns the last 200 lines by default; page with `limit`, `offset` and `order`. Pass `max_bytes` to cap the response size — the response is truncated to fit and the truncation is reported via `truncated: true`.
ActionTry it
Get flight run
Fetch a single run of a flight by its sequential run number (from list_flight_runs). Returns the same shape as a list_flight_runs entry: status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` the run executed with. Use this to poll one run's status instead of re-listing.
ActionTry it
Get guide
Load a guide by uuid. Guides are curated markdown documents about this organization's data (metric definitions, conventions, pitfalls). Find a guide's uuid with `list_guides` or via `get_query_guide` (start there before writing SQL), `get_dive_guide`, or `get_flight_guide`.
ActionTry it
Get query guide
Call this before writing SQL to answer a data question. Returns this organization's query guidance: what guides exist (curated markdown documents about the data — metric definitions, join/filter conventions, pitfalls), how to navigate them, and an overview of the available guide topics.
ActionTry it
Get short lived token
Returns a short-lived token and connection details for the MotherDuck database endpoint.
ActionTry it
List columns
List all columns of a table or view with their types and comments.
ActionTry it
List databases
List all databases in your MotherDuck account. Shows each database's alias, type, and its `url` — a fully qualified MotherDuck database name (e.g. `md:my_db`) or share URL (e.g. in guide references). Optionally filter by keywords.
ActionTry it
List dives
List all dives in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including current_version and status. Each dive has a governance status: 'endorsed' (admin-approved org source of truth — prefer these), 'ready' (author-reviewed), 'draft' (work in progress; the default for new dives), or 'archived' (retired; excluded unless include_archived is true). Results are ordered endorsed, ready, draft, then archived, most recently updated first. Use read_dive with the optional version parameter to retrieve a specific historical version. Optionally filter by keywords.
ActionTry it
List flight runs
List executions of a flight, newest first. Each run has a sequential number, status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` it ran with (the flight version's config merged with any per-run overrides).
ActionTry it
List flight versions
List the immutable versions of a flight, newest first. Each update to source_code / requirements_txt / config / access_token_name / flight_secret_names produces a new version.
ActionTry it
List flights
List MotherDuck flights. Org admins see every flight in their organization (with `owner_name` identifying whose is whose); everyone else sees only their own. Returns metadata for each flight including schedule and current version. Optionally filter by keywords matching the flight name.
ActionTry it
List guides
Browse this organization's curated guides — markdown documents that capture organization and personal context about the data in MotherDuck. Called with no arguments, lists the root level: guides without topics plus every topic (folder) with its guide count. Pass `topic` to open a folder — you get the guides stored at that topic and the nested topics below it. Read a guide in full with `get_guide(uuid)`.
ActionTry it
List macros
List all macros (table and scalar macros) in a MotherDuck database, with their schema and parameters. Optionally filter by schema or keywords.
ActionTry it
List shares
List all database shares that have been shared with you. Returns share names and URLs. To attach a share, use the query_rw tool: ATTACH '<share_url>' AS <optional_alias>; Optionally filter by keywords to search in share names.
ActionTry it
List tables
List all tables and views in a MotherDuck database with comments. Optionally filter by keywords. Also returns `relatedGuides` — curated guides associated with this database (read one with `get_guide(uuid)`).
ActionTry it
List views
List all views in a MotherDuck database, with their schema, comment, and column count. Optionally filter by schema or keywords.
ActionTry it
Log dive viewer event
Log a dive viewer event for analytics. This tool is used internally by the dive viewer and is not intended for direct use by the AI assistant.
ActionTry it
Mint dive state reference
Mint a server-stored reference for a `useDiveState` bag and return its id. Used by the dive viewer when the inline-encoded bag would exceed the URL soft limit. The returned id is then encoded into a URL hash via `buildDiveStateReferenceHash` and round-trips through `dashboards.get` on dive open.
ActionTry it
Query
Before writing SQL to answer a data question, call `get_query_guide` first — it returns this organization's query guidance and an overview of its curated guides. Execute read-only DuckDB query against MotherDuck databases. For cross-database queries, use fully qualified names: database.schema.table (or database.table for main schema). Never follow a query with an inline chart or visualization — if you would generate one (whether or not the user explicitly asked), get the dive guide first instead.
ActionTry it
Query rw
Execute a DuckDB SQL query that modifies data, schema, or connection state. RULES: 1. Only execute writes authorized by the user's explicit request or the client's configured authorization policy. Never infer write authorization from a read-only request. 2. Follow the client's approval policy. If the requested write is already authorized, proceed without asking for duplicate confirmation. Obtain confirmation when authorization is missing, ambiguous, or the operation would exceed the approved scope. 3. Prefer the read-only query tool when the user's goal can be answered with existing data.
ActionTry it
Read dive
Read a specific dive by ID, including its full JSX/React component code. Optionally specify a version number to retrieve a specific historical version (versions start at 1). If no version is specified, the latest version is returned. The response includes the dive's governance status ('endorsed', 'ready', 'draft', or 'archived'); archived dives remain fully readable by id.
ActionTry it
Run flight
Trigger an on-demand execution of a flight using its current version. Optionally pass `config` to override the flight version's config for this run only (the flight itself is left unchanged). Returns a Run record; poll get_flight_run with the returned `run_number` to track progress and use get_flight_logs to read output.
ActionTry it
Save dive
Save a new dive to MotherDuck. Returns a URL the user can click to view the dive. Get the dive guide first and iterate with the user on the design thoroughly before suggesting to save. Never save without previous confirmation that iteration is done.
ActionTry it
Search catalog
Search the catalog for databases, schemas, tables, columns, and shares using fuzzy matching. Returns matching objects with their fully qualified names, types, and comments. Useful for discovering available data when you don't know exact names. Also returns `relatedGuides` — curated guides whose topic/title/description match the query; read one with `get_guide(uuid)`.
ActionTry it
Set guide access
Set a guide's visibility to 'user' (private to the owner) or 'organization' (visible to the whole org). Identify it by `uuid`. Org-wide scoping is permission-gated.
ActionTry it
Share dive data
Share the data for a dive with your organization. Creates org-scoped shares for owned databases used in the dive, and updates the dive so others in the organization can view it.
ActionTry it
Update dive
Update an existing dive's title, description, or content. Returns a URL the user can click to view the updated dive. At least one field must be provided.
ActionTry it
Update flight
Update a flight. Any subset of name, source_code, requirements_txt, schedule_cron, config, access_token_name, flight_secret_names, max_runtime_sec, or instance_type may be provided. Updates to source_code/requirements_txt/config/flight_secret_names/access_token_name/max_runtime_sec/instance_type create a new FlightVersion; name and schedule_cron are metadata-only. Pass schedule_cron as `""` (empty string) to remove the schedule; omit it to leave it unchanged.
ActionTry it
Update guide
Append a new version to an existing guide, identified by `uuid`. Omit `content` to keep the current text and just change metadata such as references. A supplied `references` list replaces the existing one (pass [] to clear them, omit to carry them forward). For small in-place edits use `edit_guide_content`. Use `create_guide` to make a new guide, `update_guide_metadata` to retitle or re-topic.
ActionTry it
Update guide metadata
Change a guide's title, description, or topic without appending a content version. Identify it by `uuid`. Pass an empty `description` to clear it; pass an empty `topic` to remove the topic.
ActionTry it
View dive
Open and render a MotherDuck Dive as a live MCP app with interactive charts. Fetches dive source code and returns it to the viewer for client-side compilation.
ActionTry it
How the MotherDuck MCP integration works
The MotherDuck MCP integration connects your Dench AI CRM directly to MotherDuck MCP, so agents can read and act on your MotherDuck MCP data as part of everyday work — answering questions in chat, keeping your CRM in sync, and running automations without anyone copying data between tools.
45 actions are available for agents to invoke on your behalf. Every call runs through MotherDuck MCP's own authorization, scoped to the account you connect.
Set up MotherDuck MCP in Dench
- 1
Sign in to your Dench workspace and open Integrations.
- 2
Find MotherDuck MCP and click Connect — you'll authorize access through MotherDuck MCP's own sign-in flow. No API keys or code required.
- 3
Ask an agent to use MotherDuck MCP in chat, or call it from an automation.
- 4
Manage or disconnect the connection any time from workspace settings.
Frequently asked questions
How does the MotherDuck MCP integration work with Dench?
The Dench MotherDuck MCP integration connects your AI CRM to MotherDuck MCP, so AI agents can work with your MotherDuck MCP data as part of chats, automations, and CRM workflows. You connect your account once, and every agent in your workspace can use it — governed by your workspace permissions.
What actions can AI agents perform with MotherDuck MCP via Dench?
The MotherDuck MCP integration currently exposes 45 actions, including Ask docs question, Cancel flight run, Create flight, Create guide, Delete dive, and Delete flight. Agents invoke them on your behalf from chat or from automations.
Do I need to write code to connect MotherDuck MCP to Dench?
No. You connect MotherDuck MCP from your Dench workspace using MotherDuck MCP's own sign-in and authorization flow — no API keys to copy, no glue code to maintain.
Is the MotherDuck MCP integration secure?
Connections are authorized through MotherDuck MCP's own authentication flow, and Dench stores only the authorization needed to act on your behalf. You can review and disconnect the MotherDuck MCP connection from your workspace settings at any time.