# MotherDuck Documentation - MCP Server

> Connect AI assistants to MotherDuck using the remote (fully managed) or local (fully customizable) MCP server

> MotherDuck is a serverless cloud data warehouse built on DuckDB.
It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics.

## Key capabilities

- **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses)
- **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session
- **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language
- **Data Sharing**: Share databases and query results with team members and external users
- **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI
- **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more
- **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation

## Agent guidance

If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation.

For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows.

To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question.

## Account setup for agents

If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request.

`POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`.

Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership.

Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup.

## Child contexts

- [Core tools full context](https://motherduck.com/docs/sql-reference/mcp/core/llms-full.txt): Query your databases, explore schemas and shares, search the catalog, and ask documentation questions through the MotherDuck MCP server. (10 pages; 30,186 bytes; ~7,544 tokens). [Index](https://motherduck.com/docs/sql-reference/mcp/core/llms.txt).
- [Dives full context](https://motherduck.com/docs/sql-reference/mcp/dives/llms-full.txt): Create, read, update, share, and render Dives — interactive data visualizations — through the MotherDuck MCP server. (8 pages; 33,363 bytes; ~8,338 tokens). [Index](https://motherduck.com/docs/sql-reference/mcp/dives/llms.txt).
- [Flights full context](https://motherduck.com/docs/sql-reference/mcp/flights/llms-full.txt): Create, schedule, run, and monitor Flights — scheduled Python jobs on MotherDuck compute — through the MotherDuck MCP server. (12 pages; 31,243 bytes; ~7,791 tokens). [Index](https://motherduck.com/docs/sql-reference/mcp/flights/llms.txt).
- [Guides full context](https://motherduck.com/docs/sql-reference/mcp/guides/llms-full.txt): Create, read, update, and manage Guides — markdown documents that capture your organization's metric definitions, join conventions, and domain context so AI agents write accurate SQL — through the MotherDuck MCP server. (9 pages; 33,290 bytes; ~8,291 tokens). [Index](https://motherduck.com/docs/sql-reference/mcp/guides/llms.txt).

## Included documentation

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

# MotherDuck MCP server


> Connect AI assistants to MotherDuck using the remote (fully managed) or local (fully customizable) MCP server

MotherDuck offers a **remote MCP server** (fully managed, read-write) and a [**local MCP server**](#local-mcp-server) (fully customizable, self-hosted) that let AI assistants query and explore your MotherDuck databases using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).

:::info[Connection URL]
The remote MCP server is hosted at `https://api.motherduck.com/mcp`. Most clients connect through OAuth automatically; clients that need a manual configuration use this URL with an HTTP transport.
:::

For step-by-step setup instructions for all supported clients (Claude, ChatGPT, Cursor, Claude Code, and others), see [Connect to the MotherDuck MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/).

## Server capabilities

With the remote MCP server, your agent can:
- Execute read-only and read-write SQL against your databases
- Explore database schemas, tables, and columns
- Attach and detach [shares](/key-tasks/sharing-data/sharing-overview)
- Ask questions about DuckDB and MotherDuck documentation
- Create and manage [Dives](/key-tasks/dives) (interactive data visualizations)
- Render Dives inline in supported clients with the Dive Viewer MCP App, so you iterate against live data instead of a sample-data preview
- Create, schedule, run, and monitor [Flights](/concepts/flights) (scheduled Python jobs on MotherDuck compute)
- Read and write [Guides](/key-tasks/guides/) — markdown documents that capture your org's metric definitions, join conventions, and domain context, so agents produce accurate SQL without repetitive prompting

For clients that [support MCP instructions](https://modelcontextprotocol.io/clients#feature-support-matrix), the remote MCP server provides detailed [query guidelines](https://app.motherduck.com/assets/docs/mcp_server_instructions.md) to help AI assistants write effective DuckDB SQL. Learn more about [using the MotherDuck MCP server](/key-tasks/ai-and-motherduck/mcp-workflows).

### Regional availability

The remote MCP server is available in all MotherDuck regions. Requests are routed to the MCP server closest to where the client runs:

- **Desktop clients** (Cursor, Claude Code): Routed based on your physical location
- **Web-based agents** (Claude.ai, ChatGPT): Routed based on the agent provider's server location

Your data is always processed in your MotherDuck organization's region. However, query results transit through the remote MCP server. If you have strict data residency requirements, ensure your MCP client runs within your region.

### Restricting to read-only access

The remote MCP server exposes both read-only and read-write tools. To restrict your AI assistant to read-only access, see [Restricting to read-only access](/key-tasks/ai-and-motherduck/securing-read-only-access/).

## Local MCP server

For local DuckDB databases, custom configurations, or self-hosted scenarios, use the **local MCP server** ([mcp-server-motherduck](https://github.com/motherduckdb/mcp-server-motherduck)). For a comparison of remote vs local and when to use each, see the [setup guide](/key-tasks/ai-and-motherduck/mcp-setup/#remote-vs-local-mcp-server).

[📦 **Local MCP Server GitHub Repository** – Self-host the open-source MCP server for DuckDB and MotherDuck](https://github.com/motherduckdb/mcp-server-motherduck)

## Related resources

- [Connect to the MCP Server](/key-tasks/ai-and-motherduck/mcp-setup/) - Setup instructions for all supported AI clients
- [MCP Workflows Guide](/key-tasks/ai-and-motherduck/mcp-workflows) - Tips and workflows for using the MotherDuck MCP server
- [Building Analytics Agents](/key-tasks/ai-and-motherduck/building-analytics-agents) - Guide to building AI agents with MotherDuck
- [MCP Specification (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18) - Official protocol documentation

## Tool reference

The remote MCP server's tools are grouped by what they operate on: **core tools** for querying databases, exploring schemas and shares, and asking documentation questions; **Dive tools** for creating and managing [Dives](/key-tasks/dives); **Flight tools** for creating, scheduling, and monitoring [Flights](/concepts/flights); and **Guide tools** for creating and managing [Guides](/key-tasks/guides/).

## Included pages

- [Core tools](https://motherduck.com/docs/category/core-tools): Query your databases, explore schemas and shares, search the catalog, and ask documentation questions through the MotherDuck MCP server.
- [Dives](https://motherduck.com/docs/category/dives): Create, read, update, share, and render Dives — interactive data visualizations — through the MotherDuck MCP server.
- [Flights](https://motherduck.com/docs/category/flights): Create, schedule, run, and monitor Flights — scheduled Python jobs on MotherDuck compute — through the MotherDuck MCP server.
- [Guides](https://motherduck.com/docs/category/guides): Create, read, update, and manage Guides — markdown documents that capture your organization's metric definitions, join conventions, and domain context so AI agents write accurate SQL — through the MotherDuck MCP server.

---

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

# list_databases


> List all databases in your MotherDuck account

List all databases in your MotherDuck account with their names and types.

## Description

The `list_databases` tool returns all databases accessible to your MotherDuck account, including both owned databases and attached shared databases. This is useful for discovering what data is available before running queries.

## Input parameters

This tool takes no input parameters.

## Output schema

```json
{
  "success": boolean,
  "databases": [                 // List of databases (on success)
    {
      "alias": string,           // Database name/alias
      "is_attached": boolean,    // Whether the database is currently attached
      "type": string             // Database type (e.g., "motherduck", "memory")
    }
  ],
  "error": string                // Error message (on failure)
}
```

## Example usage

**List available databases:**

```text
What databases do I have access to?
```

The AI assistant will call the tool with no parameters.

## Success response example

```json
{
  "success": true,
  "databases": [
    {
      "alias": "my_db",
      "is_attached": true,
      "type": "motherduck"
    },
    {
      "alias": "analytics",
      "is_attached": true,
      "type": "motherduck"
    },
    {
      "alias": "shared_sales_data",
      "is_attached": true,
      "type": "motherduck"
    }
  ]
}
```

---

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

# list_shares


> List database shares that have been shared with you

List all database [shares](/key-tasks/sharing-data/sharing-overview) that have been shared with you.

## Description

The `list_shares` tool returns all database shares that have been shared with you by other users. Each share includes its name and URL, which can be used to attach the share as a database using the `query` tool.

To attach a share, execute: `ATTACH '<share_url>' AS my_alias;`

To detach a share: `DETACH <database_alias>;`

## Input parameters

This tool takes no input parameters.

## Output schema

```json
{
  "success": boolean,
  "shares": [                    // List of shares (on success)
    {
      "name": string,            // Share name
      "url": string              // Share URL for attaching
    }
  ],
  "error": string                // Error message (on failure)
}
```

## Example usage

**List available shares:**

```text
What shares have been shared with me?
```

The AI assistant will call the tool with no parameters.

**Attach a share after listing:**

```text
Attach the sales_data share so I can query it
```

After getting the share URL from `list_shares`, the AI will use the `query` tool:

```json
{
  "database": "my_db",
  "sql": "ATTACH 'md:_share/org123/sales_data' AS sales_data"
}
```

## Success response example

```json
{
  "success": true,
  "shares": [
    {
      "name": "sales_data",
      "url": "md:_share/org123/sales_data"
    },
    {
      "name": "product_catalog",
      "url": "md:_share/org456/product_catalog"
    },
    {
      "name": "analytics_benchmark",
      "url": "md:_share/org789/analytics_benchmark"
    }
  ]
}
```

## Empty response example

When no shares have been shared with you:

```json
{
  "success": true,
  "shares": []
}
```

## Related

- [Sharing Overview](/key-tasks/sharing-data/sharing-overview) - Learn about MotherDuck's data sharing capabilities
- [Managing Shares](/key-tasks/sharing-data/managing-shares) - How to create and manage shares

---

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

# list_tables


> List tables and views in a MotherDuck database

List all tables and views in a MotherDuck database with their comments.

## Description

The `list_tables` tool returns all tables and views in a specified database, including their schema, type (table or view), and any comments that have been added. You can optionally filter by schema.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database name to list tables from |
| `schema` | string | No | Schema name to filter by (defaults to all schemas) |

## Output schema

```json
{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema filter used ("all" if not specified)
  "tables": [                    // List of tables and views (on success)
    {
      "schema": string,          // Schema name
      "name": string,            // Table or view name
      "type": "table" | "view",  // Object type
      "comment": string | null   // Table/view comment if set
    }
  ],
  "tableCount": number,          // Number of tables
  "viewCount": number,           // Number of views
  "error": string                // Error message (on failure)
}
```

## Example usage

**List all tables in a database:**

```text
Show me all tables in my_database
```

The AI assistant will call the tool with:

```json
{
  "database": "my_database"
}
```

**List tables in a specific schema:**

```text
What tables are in the staging schema of analytics_db?
```

```json
{
  "database": "analytics_db",
  "schema": "staging"
}
```

## Success response example

```json
{
  "success": true,
  "database": "my_database",
  "schema": "all",
  "tables": [
    {
      "schema": "main",
      "name": "customers",
      "type": "table",
      "comment": "Customer master data"
    },
    {
      "schema": "main",
      "name": "orders",
      "type": "table",
      "comment": "Order transactions"
    },
    {
      "schema": "main",
      "name": "monthly_sales",
      "type": "view",
      "comment": "Aggregated monthly sales view"
    },
    {
      "schema": "staging",
      "name": "raw_events",
      "type": "table",
      "comment": null
    }
  ],
  "tableCount": 3,
  "viewCount": 1
}
```

## Error response example

```json
{
  "success": false,
  "error": "Catalog Error: Database \"nonexistent_db\" does not exist"
}
```

---

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

# list_columns


> List columns of a table or view with types and comments

List all columns of a table or view with their types and comments.

## Description

The `list_columns` tool returns detailed column information for a specified table or view, including data types, nullability, and any comments. This is useful for understanding table structure before writing queries.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `table` | string | Yes | Table or view name |
| `database` | string | Yes | Database name |
| `schema` | string | No | Schema name (defaults to `main`) |

## Output schema

```json
{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema name
  "table": string,               // Table or view name
  "objectType": "table" | "view", // Whether it's a table or view
  "columns": [                   // List of columns (on success)
    {
      "name": string,            // Column name
      "type": string,            // Data type
      "nullable": boolean,       // Whether nulls are allowed
      "comment": string | null   // Column comment if set
    }
  ],
  "columnCount": number,         // Number of columns
  "error": string                // Error message (on failure)
}
```

## Example usage

**Get columns for a table:**

```text
What columns does the customers table have in my_database?
```

The AI assistant will call the tool with:

```json
{
  "table": "customers",
  "database": "my_database"
}
```

**Get columns in a specific schema:**

```text
Show me the schema of staging.raw_events in analytics_db
```

```json
{
  "table": "raw_events",
  "database": "analytics_db",
  "schema": "staging"
}
```

## Success response example

```json
{
  "success": true,
  "database": "my_database",
  "schema": "main",
  "table": "customers",
  "objectType": "table",
  "columns": [
    {
      "name": "id",
      "type": "INTEGER",
      "nullable": false,
      "comment": "Primary key"
    },
    {
      "name": "email",
      "type": "VARCHAR",
      "nullable": false,
      "comment": "Customer email address"
    },
    {
      "name": "name",
      "type": "VARCHAR",
      "nullable": true,
      "comment": "Full name"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "nullable": false,
      "comment": null
    },
    {
      "name": "metadata",
      "type": "JSON",
      "nullable": true,
      "comment": "Additional customer attributes"
    }
  ],
  "columnCount": 5
}
```

## Error response example

```json
{
  "success": false,
  "error": "Catalog Error: Table \"nonexistent_table\" does not exist"
}
```

---

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

# list_views


> List views in a MotherDuck database with schema, comment, and column count

List all views in a MotherDuck database with their schema, comment, and column count.

## Description

The `list_views` tool returns the views in a specified database, including their schema, any comments, and the number of columns. You can optionally filter by schema or keywords. To inspect a view's columns in detail, follow up with [`list_columns`](../list-columns).

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database name to list views from |
| `schema` | string | No | Schema name (defaults to all schemas) |
| `keywords` | string | No | Filter views by name or comment (case-insensitive, any word can match) |
| `limit` | number | No | Maximum results to return (default: 100, maximum: 500) |

## Output schema

```json
{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema filter used ("all" if not specified)
  "views": [                     // List of views (on success)
    {
      "schema": string,          // Schema name
      "name": string,            // View name
      "comment": string | null,  // View comment if set
      "column_count": number     // Number of columns
    }
  ],
  "count": number,               // Number of views returned
  "totalCount": number,          // Total number of matching views
  "truncated": boolean,          // Present when results were cut to fit the limit
  "error": string                // Error message (on failure)
}
```

## Example usage

**List all views in a database:**

```text
What views does my_database have?
```

The AI assistant will call the tool with:

```json
{
  "database": "my_database"
}
```

**Filter by schema and keywords:**

```json
{
  "database": "analytics_db",
  "schema": "reporting",
  "keywords": "monthly revenue"
}
```

## Success response example

```json
{
  "success": true,
  "database": "analytics_db",
  "schema": "reporting",
  "views": [
    {
      "schema": "reporting",
      "name": "monthly_revenue",
      "comment": "Revenue aggregated by calendar month",
      "column_count": 4
    }
  ],
  "count": 1,
  "totalCount": 1
}
```

## Related

- [`list_tables`](../list-tables) — List tables and views with their comments.
- [`list_columns`](../list-columns) — Inspect a view's columns and types.
- [`list_macros`](../list-macros) — List macros in a database.

---

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

# list_macros


> List table and scalar macros in a MotherDuck database with their parameters

List all macros (table and scalar macros) in a MotherDuck database with their schema and parameters.

## Description

The `list_macros` tool returns the macros defined in a specified database, including their schema, type, and parameter names. You can optionally filter by schema or keywords. Macros encapsulate reusable SQL logic; knowing which ones exist helps the AI assistant reuse them instead of rebuilding the logic in every query.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database name to list macros from |
| `schema` | string | No | Schema name (defaults to all schemas) |
| `keywords` | string | No | Filter macros by name (case-insensitive, any word can match) |
| `limit` | number | No | Maximum results to return (default: 100, maximum: 500) |

## Output schema

```json
{
  "success": boolean,
  "database": string,            // Database name
  "schema": string,              // Schema filter used ("all" if not specified)
  "macros": [                    // List of macros (on success)
    {
      "schema": string,          // Schema name
      "name": string,            // Macro name
      "type": string,            // Macro type
      "parameters": [string]     // Parameter names
    }
  ],
  "count": number,               // Number of macros returned
  "totalCount": number,          // Total number of matching macros
  "truncated": boolean,          // Present when results were cut to fit the limit
  "error": string                // Error message (on failure)
}
```

## Example usage

**List all macros in a database:**

```text
Are there any reusable macros in analytics_db?
```

The AI assistant will call the tool with:

```json
{
  "database": "analytics_db"
}
```

**Filter by keywords:**

```json
{
  "database": "analytics_db",
  "keywords": "fiscal"
}
```

## Success response example

```json
{
  "success": true,
  "database": "analytics_db",
  "schema": "all",
  "macros": [
    {
      "schema": "main",
      "name": "fiscal_quarter",
      "type": "macro",
      "parameters": ["date_col"]
    }
  ],
  "count": 1,
  "totalCount": 1
}
```

## Related

- [`list_views`](../list-views) — List views in a database.
- [`list_tables`](../list-tables) — List tables and views with their comments.
- [`query`](../query) — Run a query that uses a macro.

---

Source: https://motherduck.com/docs/sql-reference/mcp/core/search-catalog

# search_catalog


> Fuzzy search across databases, schemas, tables, columns, and shares

Search the catalog for databases, schemas, tables, columns, and shares using fuzzy matching.

## Description

The `search_catalog` tool performs fuzzy search across your entire MotherDuck catalog. It finds matching objects by name using partial matching, supporting underscores, dots, and multi-word queries. This is useful for discovering available data when you don't know exact names.

The search uses Jaro-Winkler similarity scoring and returns results ranked by relevance. Results are limited per category to provide a balanced view across different object types.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search term to find in object names (supports partial matching, underscores, dots) |
| `object_types` | string[] | No | Filter results to specific types: `"database"`, `"schema"`, `"table"`, `"column"`, `"share"` |

## Output schema

```json
{
  "success": boolean,
  "query": string,               // Search query used
  "resultCount": number,         // Total results found
  "results": [                   // Search results (on success)
    {
      "type": "database" | "schema" | "table" | "column" | "share",
      "name": string,            // Object name
      "fullyQualifiedName": string, // Full path (e.g., "db.schema.table.column")
      "database": string | null, // Database (null for shares)
      "schema": string | null,   // Schema (null for databases/shares)
      "table": string | null,    // Table (only for columns)
      "dataType": string | null, // Data type (columns) or URL (shares)
      "comment": string | null,  // Object comment if set
      "relevanceScore": number   // Match score 0-1 (higher is better)
    }
  ],
  "error": string,               // Error message (on failure)
  "errorType": string            // Error type (on failure)
}
```

## Result limits

Results are limited per object type to provide balanced coverage:
- Shares: 10 results
- Columns: 40 results
- Tables: 30 results
- Schemas: 20 results
- Databases: 20 results

Maximum total results: 100

## Example usage

**Search for tables with "sales" in the name:**

```text
Find all tables related to sales data
```

The AI assistant will call the tool with:

```json
{
  "query": "sales"
}
```

**Search only for columns:**

```text
Find columns containing "email"
```

```json
{
  "query": "email",
  "object_types": ["column"]
}
```

**Search with qualified name:**

```text
Find anything matching analytics.events
```

```json
{
  "query": "analytics.events"
}
```

## Success response example

```json
{
  "success": true,
  "query": "sales",
  "resultCount": 8,
  "results": [
    {
      "type": "table",
      "name": "sales_data",
      "fullyQualifiedName": "analytics.main.sales_data",
      "database": "analytics",
      "schema": "main",
      "table": null,
      "dataType": null,
      "comment": "Daily sales transactions",
      "relevanceScore": 0.95
    },
    {
      "type": "table",
      "name": "monthly_sales",
      "fullyQualifiedName": "analytics.main.monthly_sales",
      "database": "analytics",
      "schema": "main",
      "table": null,
      "dataType": null,
      "comment": null,
      "relevanceScore": 0.89
    },
    {
      "type": "column",
      "name": "total_sales",
      "fullyQualifiedName": "analytics.main.revenue.total_sales",
      "database": "analytics",
      "schema": "main",
      "table": "revenue",
      "dataType": "DECIMAL(18,2)",
      "comment": "Total sales amount",
      "relevanceScore": 0.87
    },
    {
      "type": "share",
      "name": "regional_sales_share",
      "fullyQualifiedName": "regional_sales_share",
      "database": "regional_sales_share",
      "schema": null,
      "table": null,
      "dataType": "md:_share/org123/regional_sales_share",
      "comment": null,
      "relevanceScore": 0.82
    }
  ]
}
```

## Error response example

```json
{
  "success": false,
  "error": "Search query cannot be empty",
  "errorType": "ValidationError"
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/core/query

# query


> Execute SQL queries against MotherDuck databases

Execute **read-only** SQL queries against MotherDuck databases.

## Description

The `query` tool executes SQL queries against your MotherDuck databases. For cross-database queries, use fully qualified names: `database.schema.table` (or `database.table` for the main schema).

`query` is for read-only SQL. Operations that modify data, schema, or account settings, or trigger side effects, are rejected. For SQL that can change data or schema, use [`query_rw`](/sql-reference/mcp/core/query-rw/).

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database name to query |
| `sql` | string | Yes | DuckDB SQL query to execute |

## Output schema

```json
{
  "success": boolean,
  "columns": string[],           // Column names (on success)
  "columnTypes": string[],       // Column types (on success)
  "rows": any[][],               // Query results (on success)
  "rowCount": number,            // Number of rows returned (on success)
  "error": string,               // Error message (on failure)
  "errorType": string            // Error type (on failure)
}
```

## Limits

- **Result limit:** Maximum 2,048 rows and 50,000 characters. Results exceeding these limits will be truncated with a truncation message.
- **Query timeout:** 55 seconds, to stay within common client timeouts. Queries exceeding this limit will be cancelled server-side and the tool will respond with an error message.

## Example usage

**Simple query:**

```text
Query the top 5 customers by total orders from my_database
```

The AI assistant will call the tool with:

```json
{
  "database": "my_database",
  "sql": "SELECT customer_name, COUNT(*) as order_count FROM orders GROUP BY customer_name ORDER BY order_count DESC LIMIT 5"
}
```

**Cross-database query:**

```text
Join the users table from auth_db with orders from sales_db
```

```json
{
  "database": "auth_db",
  "sql": "SELECT u.name, o.order_id, o.amount FROM auth_db.main.users u JOIN sales_db.main.orders o ON u.id = o.user_id LIMIT 100"
}
```

## Success response example

```json
{
  "success": true,
  "columns": ["customer_name", "order_count"],
  "columnTypes": ["VARCHAR", "BIGINT"],
  "rows": [
    ["Acme Corp", 150],
    ["TechStart Inc", 89],
    ["Global Services", 72]
  ],
  "rowCount": 3
}
```

## Error response example

```json
{
  "success": false,
  "error": "Query is not read-only",
  "errorType": "ForbiddenQueryError"
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/core/query-rw

# query_rw


> Execute SQL queries that can modify data or schema in MotherDuck

Execute SQL queries that can modify data or schema in MotherDuck.

## Description

The `query_rw` tool executes SQL against your MotherDuck databases, including operations that change data or schema. For cross-database queries, use fully qualified names: `database.schema.table` (or `database.table` for the main schema).

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | No | Database context for the query. Required when the statement targets database objects. Optional for account-level operations. |
| `sql` | string | Yes | DuckDB SQL statement to execute |

## Output schema

Same as [`query`](/sql-reference/mcp/core/query/):

```json
{
  "success": boolean,
  "columns": string[],           // Column names (on success)
  "columnTypes": string[],       // Column types (on success)
  "rows": any[][],               // Query results (on success)
  "rowCount": number,            // Number of rows returned (on success)
  "error": string,               // Error message (on failure)
  "errorType": string            // Error type (on failure)
}
```

## Limits

- **Result limit:** Maximum 2,048 rows and 50,000 characters. Results exceeding these limits will be truncated with a truncation message.
- **Query timeout:** 55 seconds. Queries exceeding this limit will be cancelled server-side and the tool will respond with an error message.

## Example usage

**Insert rows:**

```text
Insert a new customer 'Acme Corp' with id 100 into my_database.customers
```

```json
{
  "database": "my_database",
  "sql": "INSERT INTO customers (id, name) VALUES (100, 'Acme Corp')"
}
```

**Update and delete:**

```text
In my_database, set status to 'shipped' for all orders in the orders table where status is 'pending', then delete the old log entries from audit_log
```

The AI assistant can call `query_rw` with the appropriate UPDATE and DELETE statements (or multiple calls if the client requires one statement per call).

**Create table:**

```text
Create a table my_database.main.events with columns id (BIGINT), name (VARCHAR), created_at (TIMESTAMP)
```

```json
{
  "database": "my_database",
  "sql": "CREATE TABLE main.events (id BIGINT, name VARCHAR, created_at TIMESTAMP)"
}
```

**Account-level operations (database optional):**

```text
Create a new database called reporting
```

```json
{
  "sql": "CREATE DATABASE reporting"
}
```

For account-level operations, omit `database` and pass only `sql`.

:::tip[Read-only access]
To restrict the MCP server so the AI can only read data, see [Restricting to read-only access](/key-tasks/ai-and-motherduck/securing-read-only-access/).
:::

---

Source: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question

# ask_docs_question


> Ask questions about DuckDB or MotherDuck documentation

Ask a question about DuckDB or MotherDuck and get answers from official documentation.

## Description

The `ask_docs_question` tool queries the official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, best practices, and more. This is useful when you need help with DuckDB-specific SQL syntax or MotherDuck features.

The tool uses MotherDuck's documentation assistant to provide accurate answers based on official documentation sources.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | Yes | Question about DuckDB or MotherDuck |

## Output schema

```json
{
  "success": boolean,
  "question": string,            // Original question (on success)
  "answer": string,              // Documentation-based answer (on success)
  "sources": string,             // Source references (optional, on success)
  "error": string                // Error message (on failure)
}
```

## Example usage

**Ask about DuckDB syntax:**

```text
How do I use window functions in DuckDB?
```

The AI assistant will call the tool with:

```json
{
  "question": "How do I use window functions in DuckDB?"
}
```

**Ask about MotherDuck features:**

```text
How do I create a share in MotherDuck?
```

```json
{
  "question": "How do I create a share in MotherDuck?"
}
```

**Ask about data types:**

```text
What's the difference between LIST and ARRAY types in DuckDB?
```

```json
{
  "question": "What's the difference between LIST and ARRAY types in DuckDB?"
}
```

## Success response example

```json
{
  "success": true,
  "question": "How do I use window functions in DuckDB?",
  "answer": "Window functions in DuckDB allow you to perform calculations across a set of rows related to the current row. Here's how to use them:\n\n**Basic syntax:**\n```sql\nSELECT \n  column,\n  SUM(value) OVER (PARTITION BY category ORDER BY date) as running_total\nFROM table_name;\n```\n\n**Common window functions:**\n- `ROW_NUMBER()` - assigns unique row numbers\n- `RANK()` and `DENSE_RANK()` - ranking with/without gaps\n- `LAG()` and `LEAD()` - access previous/next rows\n- `FIRST_VALUE()` and `LAST_VALUE()` - first/last value in window\n\n**Using QUALIFY:**\nDuckDB supports the QUALIFY clause to filter window function results:\n```sql\nSELECT *\nFROM sales\nQUALIFY ROW_NUMBER() OVER (PARTITION BY region ORDER BY amount DESC) = 1;\n```\n\nThis returns only the top sale per region.",
  "sources": "https://duckdb.org/docs/sql/window_functions"
}
```

## Tips for good questions

- Be specific about what you want to know
- Include context about what you're trying to accomplish
- Mention specific functions or features if known

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/get-dive-guide

# get_dive_guide
> Load instructions for creating MotherDuck Dives
Load instructions for creating MotherDuck [Dives](/docs/key-tasks/dives). Call this before creating or saving dives.

## Description

The `get_dive_guide` tool returns comprehensive instructions on how to write MotherDuck Dives—interactive React data apps that query live MotherDuck data. It provides guidance on the [`useSQLQuery` hook](/sql-reference/motherduck-sql-reference/dives/use-sql-query), data type conversions, available libraries, and design system. The guide content is tailored to the AI client you are using.

Call this tool before using [`save_dive`](../save-dive) or [`update_dive`](../update-dive) to ensure the generated code follows the correct format.

:::note
Dives are available on all MotherDuck plans at no additional charge.
:::

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client` | string | Yes | The AI client being used: `"claude"`, `"chatgpt"`, `"claude_cowork"`, `"claude_code"`, or `"other"` |

### Client options

| Client | Use case |
|--------|----------|
| `claude` | Claude web or desktop chat |
| `chatgpt` | ChatGPT (OpenAI) |
| `claude_cowork` | Claude Cowork |
| `claude_code` | Claude Code, Cursor, and other IDE integrations with local filesystem access |
| `other` | Any other AI client or custom integration |

## Organization Dive conventions

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

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

## Output schema

```json
{
  "success": boolean,
  "guide": string,              // Dive guide content (on success) or upgrade message
  "client": string,             // The client that was used (on success)
  "reason": string,             // "upgrade_required" (when plan doesn't support Dives)
  "plan": string,               // Current plan name (when upgrade required)
  "error": string               // Error message (on failure)
}
```

On success, `guide` contains the client-specific instructions for building Dives.

## Example usage

**Build a new Dive from Claude:**

```text
Create a Dive showing monthly revenue trends for my sales database
```

The AI assistant will first call `get_dive_guide` to load the instructions:

```json
{
  "client": "claude"
}
```

**Build a Dive from ChatGPT:**

```text
Create a Dive with a bar chart of customer signups by region
```

```json
{
  "client": "chatgpt"
}
```

**Build a Dive from Claude Code:**

```text
Create a Dive showing daily active users over the past 90 days
```

```json
{
  "client": "claude_code"
}
```

---

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

# list_dives
> List all Dives in your MotherDuck workspace
List all owned [Dives](/docs/key-tasks/dives) in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including `current_version` (the latest version number, 1-indexed) and the [status](/docs/key-tasks/dives/dive-statuses) for each Dive. Results are ordered from most to least trusted status (Endorsed, Ready, Draft, then Archived), with the latest updates first, and Archived Dives are excluded unless requested. Use [`read_dive`](../read-dive) with the optional `version` parameter to retrieve a specific historical version. Optionally filter by keywords to search in title and description.

## Description

The `list_dives` tool returns a list of all Dives in your MotherDuck workspace. Each Dive includes its ID, title, description, owner, version history, and timestamps. Use this to discover existing Dives before reading, updating, or deleting them.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `keywords` | string | No | Keywords to filter dives by title or description (case-insensitive, all words must match) |
| `include_archived` | boolean | No | Include Archived Dives in the results. Defaults to `false`. Archived Dives remain readable with `read_dive`. |

## Output schema

```json
{
  "success": boolean,
  "dives": [                     // Array of dives (on success)
    {
      "id": string,              // Unique identifier (UUID)
      "title": string,           // Dive title
      "description": string,     // Dive description
      "owner_name": string,      // Name of the Dive owner
      "current_version": number, // Latest version number (1-indexed)
      "created_at": string,      // ISO 8601 creation timestamp
      "updated_at": string,      // ISO 8601 last update timestamp
      "status": string,          // "draft", "ready", "endorsed", or "archived"
      "status_changed_at": string,          // ISO 8601 timestamp; null until the status is set
      "status_applies_to_version": number   // Version the status was set against; null until set
    }
  ],
  "count": number,               // Number of dives returned
  "totalCount": number,          // Total number of matching dives
  "truncated": boolean,          // Whether the results were truncated
  "message": string,             // Truncation message (when truncated)
  "error": string                // Error message (on failure)
}
```

## Example usage

**List all Dives:**

```text
What Dives do I have in my workspace?
```

The AI assistant will call the tool with no parameters.

**Filter Dives by keywords:**

```text
Show me my revenue-related Dives
```

The AI assistant will call the tool with keywords:

```json
{
  "keywords": "revenue"
}
```

**Include Archived Dives:**

```text
List all my Dives, including archived ones
```

The AI assistant will call the tool with:

```json
{
  "include_archived": true
}
```

**Find a specific Dive to update:**

```text
Show me my existing Dives so I can update the revenue dashboard
```

## Success response example

```json
{
  "success": true,
  "dives": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Monthly Revenue Trends",
      "description": "Line chart showing revenue by month with category breakdown",
      "owner_name": "alice",
      "current_version": 3,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:45:00Z",
      "status": "endorsed",
      "status_changed_at": "2025-01-21T08:00:00Z",
      "status_applies_to_version": 3
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "title": "Customer Signups by Region",
      "description": "Bar chart of customer signups grouped by region",
      "owner_name": "bob",
      "current_version": 1,
      "created_at": "2025-01-18T09:00:00Z",
      "updated_at": "2025-01-18T09:00:00Z",
      "status": "draft",
      "status_changed_at": null,
      "status_applies_to_version": null
    }
  ],
  "count": 2,
  "totalCount": 2
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/read-dive

# read_dive
> Read a specific Dive by ID, including its full component code
Read a specific [Dive](/docs/key-tasks/dives) 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.

## Description

The `read_dive` tool retrieves a Dive's complete details, including its title, description, [status](/docs/key-tasks/dives/dive-statuses), timestamps, and the full React component source code. Use this to inspect an existing Dive before updating it, or to understand how a Dive is built. Archived Dives are always readable by ID, even though they're excluded from [`list_dives`](../list-dives) by default.

Use [`list_dives`](../list-dives) first to find the Dive ID and its `current_version`.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the Dive to read |
| `version` | number | No | Version number to retrieve (1-indexed). Defaults to the latest version. |

## Output schema

```json
{
  "success": boolean,
  "dive": {                      // Dive object (on success)
    "id": string,                // Unique identifier (UUID)
    "title": string,             // Dive title
    "description": string,       // Dive description
    "content": string,           // Full JSX/React component code
    "current_version": number,   // Current version number
    "created_at": string,        // ISO 8601 creation timestamp
    "updated_at": string,        // ISO 8601 last update timestamp
    "status": string,            // "draft", "ready", "endorsed", or "archived"
    "status_changed_at": string,          // ISO 8601 timestamp; null until the status is set
    "status_applies_to_version": number   // Version the status was set against; null until set
  },
  "error": string                // Error message (on failure)
}
```

## Example usage

**Read a Dive to inspect its code:**

```text
Show me the code for my revenue trends Dive
```

The AI assistant will call the tool with the Dive's ID:

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

**Read a specific version of a Dive:**

```text
Show me version 1 of my revenue trends Dive
```

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 1
}
```

**Read a Dive before updating it:**

```text
I want to modify my customer signups Dive—can you show me what it looks like?
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "description": "Line chart showing revenue by month",
    "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\n\nexport default function Dive() {\n  const { data, isLoading } = useSQLQuery(`SELECT ...`);\n  // ...\n}",
    "current_version": 3,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:45:00Z"
  }
}
```

## Error response example

```json
{
  "success": false,
  "error": "Dive with ID 'invalid-uuid' not found"
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/view-dive

# view_dive
> Render a MotherDuck Dive as a live, interactive MCP app inside the host client.
Render a [Dive](/key-tasks/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.

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`](../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.

## Output schema

```json
{
  "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](/key-tasks/dives/embedding-dives/#override-required-databases) if you need the override to survive into the linked-to 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" }
  }
}
```

## Success response example

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

```json
{
  "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`](/sql-reference/motherduck-sql-reference/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/dives/)
- [Embedding Dives in your web application](/key-tasks/dives/embedding-dives/) — the embed-session equivalents of `required_resources` and `initial_state`

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/save-dive

# save_dive
> Save a new Dive to your MotherDuck workspace
Save a new [Dive](/docs/key-tasks/dives) to MotherDuck. Returns a URL to the Dive in MotherDuck as a link that the user can click to view the Dive.

## Description

The `save_dive` tool creates a new Dive in your MotherDuck workspace. It accepts a title, optional description, and the JSX/React component code. Before saving, the tool validates the code to check for common issues like invalid SQL queries or missing exports.

After saving, the tool analyzes which databases the Dive queries. If any referenced databases are not yet shared with your organization, it prompts you to use [`share_dive_data`](../share-dive-data) so others in your organization can view the Dive.

Call [`get_dive_guide`](../get-dive-guide) first to learn the required JSX/React format.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | The title of the Dive |
| `description` | string | No | A brief description of the Dive |
| `content` | string | Yes | The JSX/React component code for the Dive |

## Output schema

```json
{
  "success": boolean,
  "dive": {                        // Created dive info (on success)
    "id": string,                  // Unique identifier (UUID)
    "title": string,               // Dive title
    "description": string | null   // Dive description
  },
  "dive_url": string,              // URL to view the Dive (on success)
  "warnings": string[],            // Validation warnings (if any)
  "database_warnings": string[],   // Warnings from database analysis (if any)
  "unshared_databases": string[],  // Database names not yet shared with the org (if any)
  "next_steps": string[],          // Ordered instructions for the AI to follow after saving
  "error": string,                 // Error message (on failure)
  "validationErrors": [            // Validation errors (on failure)
    {
      "type": string,              // Error type
      "message": string,           // Error description
      "details": string            // Additional details
    }
  ]
}
```

## Example usage

**Create a new Dive:**

```text
Create a Dive showing monthly revenue trends for my analytics database
```

The AI assistant will first call [`get_dive_guide`](../get-dive-guide) to load the instructions, then call `save_dive`:

```json
{
  "title": "Monthly Revenue Trends",
  "description": "Line chart showing revenue by month with year-over-year comparison",
  "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\nimport { LineChart, Line, XAxis, YAxis, Tooltip, ResponsiveContainer } from \"recharts\";\n\nexport default function Dive() {\n  const { data, isLoading, isError, error } = useSQLQuery(`\n    SELECT DATE_TRUNC('month', order_date) as month, SUM(revenue) as revenue\n    FROM analytics.sales\n    GROUP BY 1 ORDER BY 1\n  `);\n  // ... component code\n}"
}
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "description": "Line chart showing revenue by month with year-over-year comparison"
  },
  "dive_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "unshared_databases": ["analytics"],
  "next_steps": [
    "Regenerate the dive preview artifact with the updated banner...",
    "Show the dive to the user in chat as a markdown hyperlink: [Monthly Revenue Trends](https://app.motherduck.com/dives/a1b2c3d4-...)",
    "The dive references databases not yet shared with the organization: analytics. Ask the user if they want to share them."
  ]
}
```

## Validation error response example

```json
{
  "success": false,
  "error": "Dive validation failed",
  "validationErrors": [
    {
      "type": "SQL_ERROR",
      "message": "Query validation failed: Table 'analytics.nonexistent_table' not found",
      "details": "SELECT * FROM analytics.nonexistent_table"
    }
  ],
  "hint": "Please fix the errors above and try again."
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/update-dive

# update_dive
> Update an existing Dive's title, description, or content
Update an existing [Dive's](/docs/key-tasks/dives) title, description, or content. Returns a URL to the Dive in MotherDuck as a link the user can click to view the updated Dive.

## Description

The `update_dive` tool modifies an existing Dive in your MotherDuck workspace. You can update the title, description, content (React component code), or any combination. At least one field must be provided.

When updating content, the tool validates the new code before saving, just like [`save_dive`](../save-dive). It also analyzes which databases the Dive queries and reports any unshared databases.

Use [`list_dives`](../list-dives) to find the Dive ID, and [`read_dive`](../read-dive) to inspect the current code before modifying it.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the Dive to update |
| `title` | string | No | New title for the Dive |
| `description` | string | No | New description for the Dive |
| `content` | string | No | New JSX/React component code |

At least one of `title`, `description`, or `content` must be provided.

## Output schema

```json
{
  "success": boolean,
  "dive": {                        // Updated dive info (on success)
    "id": string                   // Dive identifier
  },
  "dive_url": string,              // URL to view the Dive (on success)
  "warnings": string[],            // Validation warnings (if any)
  "database_warnings": string[],   // Warnings from database analysis (if any)
  "unshared_databases": string[],  // Database names not yet shared with the org (if any)
  "next_steps": string[],          // Ordered instructions for the AI to follow after updating
  "error": string,                 // Error message (on failure)
  "validationErrors": [            // Validation errors (on failure)
    {
      "type": string,
      "message": string,
      "details": string
    }
  ]
}
```

## Example usage

**Update a Dive's content:**

```text
Add a region filter to my revenue trends Dive
```

The AI assistant will call `read_dive` to get the current code, modify it, then call `update_dive`:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "import { useSQLQuery } from \"@motherduck/react-sql-query\";\n// ... updated component with region filter\n"
}
```

**Update just the title and description:**

```text
Rename my revenue Dive to "Q1 Revenue Dashboard"
```

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Q1 Revenue Dashboard",
  "description": "Revenue trends filtered to Q1 2025"
}
```

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "dive_url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "next_steps": [
    "Regenerate the dive preview artifact with the updated banner...",
    "Show the dive to the user in chat as a markdown hyperlink using the dive title: [dive title](https://app.motherduck.com/dives/a1b2c3d4-...)"
  ]
}
```

## Error response example

```json
{
  "success": false,
  "error": "At least one of title, description, or content must be provided"
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/share-dive-data

# share_dive_data
> Share the data for a Dive with your organization
Share the data for a [Dive](/docs/key-tasks/dives) with your organization. Creates org-scoped shares for owned databases used in the Dive, so others in the organization can view it.

## Description

The `share_dive_data` tool makes a Dive's underlying data accessible to your organization. When a Dive queries databases that you own but haven't shared, other users in your organization won't be able to view the Dive. This tool creates shares for those databases and updates the Dive to reference the shared versions.

The tool:

1. Verifies you own the Dive
2. Analyzes the Dive's SQL queries to find referenced databases
3. Creates org-scoped shares for any databases that aren't already shared
4. Updates the Dive to use the shared database references

Use this after [`save_dive`](../save-dive) or [`update_dive`](../update-dive) when you want your team to be able to view a Dive that queries your private databases.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `diveId` | string | Yes | The unique identifier (UUID) of the Dive to share data for |

## Output schema

```json
{
  "success": boolean,
  "dive": {                      // Dive info (on success)
    "id": string,                // Dive identifier
    "title": string,             // Dive title
    "version": number            // New version number after update
  },
  "shares": [                    // Shares created (on success)
    {
      "database": string,        // Database name
      "shareName": string,       // Share name
      "shareUrl": string,        // Share URL for the database
      "created": boolean         // Whether the share was newly created
    }
  ],
  "requiredDatabases": [         // All databases referenced by the Dive
    {
      "type": string,            // "share" or "database"
      "path": string,            // Share URL or database path
      "alias": string            // Database alias name
    }
  ],
  "url": string,                 // URL to view the Dive (on success)
  "message": string,             // Status message (on success)
  "warnings": string[],          // Warnings from analysis or sharing (if any)
  "error": string                // Error message (on failure)
}
```

## Example usage

**Share a Dive's data after saving:**

```text
Share the data for my revenue Dive with the rest of my team
```

The AI assistant will call the tool with the Dive's ID:

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

**Respond to a sharing prompt after save:**

After calling [`save_dive`](../save-dive), the tool may suggest sharing unshared databases. The AI assistant will call `share_dive_data` to make the data accessible:

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

## Success response example

```json
{
  "success": true,
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Monthly Revenue Trends",
    "version": 4
  },
  "shares": [
    {
      "database": "analytics",
      "shareName": "analytics",
      "shareUrl": "md:_share/analytics/a1b2c3d4-...",
      "created": true
    }
  ],
  "requiredDatabases": [
    {
      "type": "share",
      "path": "md:_share/analytics/a1b2c3d4-...",
      "alias": "analytics"
    }
  ],
  "url": "https://app.motherduck.com/dives/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Created 1 share(s). Dive updated with share URLs."
}
```

## Nothing to share response example

When all referenced databases are already shared:

```json
{
  "success": true,
  "message": "All referenced databases are already shared. No action needed.",
  "shares": [],
  "requiredDatabases": [
    {
      "type": "share",
      "path": "md:_share/analytics/a1b2c3d4-...",
      "alias": "analytics"
    }
  ],
  "dive": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "version": 3
  }
}
```

## Error response example

```json
{
  "success": false,
  "error": "You don't own this dive or it doesn't exist"
}
```

---

Source: https://motherduck.com/docs/sql-reference/mcp/dives/delete-dive

# delete_dive
> Permanently delete a Dive by ID
Delete a [Dive](/docs/key-tasks/dives) by ID. This action is permanent and cannot be undone.

## Description

The `delete_dive` tool permanently removes a Dive from your MotherDuck workspace. Once deleted, the Dive cannot be recovered.

Use [`list_dives`](../list-dives) to find the Dive ID before deleting.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The unique identifier (UUID) of the Dive to delete |

## Output schema

```json
{
  "success": boolean,
  "message": string,             // Status message (on success)
  "error": string                // Error message (on failure)
}
```

## Example usage

**Delete a Dive:**

```text
Delete the old revenue Dive I no longer need
```

The AI assistant will call `list_dives` to find the Dive, confirm with the user, then call `delete_dive`:

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

## Success response example

```json
{
  "success": true,
  "message": "Dive 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' deleted successfully."
}
```

## Error response example

```json
{
  "success": false,
  "error": "Dive with id 'invalid-uuid' not found"
}
```

---

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

# get_flight_guide
> Load the canonical instructions for authoring, scheduling, running, and troubleshooting MotherDuck Flights.
Loads the authoritative guide for working with [Flights](/concepts/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/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/flights) — The human-readable overview.

---

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

# list_flights
> List Flights with summary metadata, optionally filtered by keywords.
List [Flights](/concepts/flights) the caller can see: Users can see Flights they have created. [Admins](/concepts/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.

---

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

# get_flight
> Fetch a Flight's metadata and version snapshot by UUID, optionally at a specific historical version.
Fetch a single [Flight](/concepts/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 assistant does not 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/roles-and-access-control/) can fetch Flights they own as well as any Flight in the organization. The ability to edit, run, and delete a Flight is restricted to the Flight creator.
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[],
      "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.

---

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

# list_flight_versions
> List the version history of a Flight, newest first.
List every immutable version of a [Flight](/concepts/flights), newest first. Each update to `source_code`, `requirements_txt`, `config`, `md_token_name`, or `md_secret_names` produces a fresh version. 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: 100, max: 500). |

## Output schema

```json
{
  "success": boolean,
  "versions": [
    {
      "version": number,
      "source_code": string,
      "requirements_txt": string,
      "md_token_name": string,
      "md_secret_names": string[],
      "config": { "<key>": "<value>" },
      "created_at": string
    }
  ],
  "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.

---

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

# create_flight
> Create a new Flight from Python source code, requirements, and an optional schedule.
Create a new [Flight](/concepts/flights). A Flight is a Python entrypoint plus an optional `requirements.txt` that runs on MotherDuck compute. Optionally provide `md_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 parameter names on the MCP tool keep the `md_*` prefix (for example, `md_token_name`, `md_secret_names`); the equivalent SQL function uses unprefixed names (`access_token_name`, `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. |
| `md_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. |
| `md_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. |

## 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": "...",
  "md_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.

---

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

# update_flight
> Update a Flight's source, requirements, config, token, secrets, name, or schedule.
Update a [Flight](/concepts/flights). Any subset of `name`, `source_code`, `requirements_txt`, `schedule_cron`, `config`, `md_token_name`, or `md_secret_names` may be provided.

Updates to `source_code`, `requirements_txt`, `config`, `md_secret_names`, or `md_token_name` produce a new `FlightVersion`. Updates to `name` or `schedule_cron` are metadata-only.

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 `md_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. |
| `md_token_name` | string | No | Updated MotherDuck access token label. Bumps the version. |
| `md_secret_names` | string[] | No | Replacement list of secret names (full replace). 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.

---

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

# 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/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.

---

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

# delete_flight
> Permanently delete a Flight, its versions, schedule, and run history.
Permanently delete a [Flight](/concepts/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.

---

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

# run_flight
> Trigger an on-demand execution of a Flight using its current version.
Trigger an on-demand execution of a [Flight](/concepts/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_run_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_run_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.

---

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

# list_flight_runs
> List the execution history of a Flight, newest first.
List the runs of a [Flight](/concepts/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_run_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.

---

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

# 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/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_run_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). |
| `max_bytes` | integer | No | Maximum log bytes to return. Minimum 1024. Truncation returns the tail. |

## 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 full logs for 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).

---

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

# cancel_flight_run
> Cancel an in-progress Flight run.
Cancel an in-progress run of a [Flight](/concepts/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.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/get-query-guide

# get_query_guide
> Load your organization's query guidance and an overview of available Guides before writing SQL
Loads your organization's query guidance: what [Guides](/key-tasks/guides/) exist, how to navigate them, and an overview of the available Guide topics. Call this before writing SQL to answer a data question.

## Description

The `get_query_guide` tool is the entry point into the Guide layer for querying. It returns orientation on how to use and navigate Guides plus an unfolded overview of your organization's topics and root-level Guides — every topic with its Guide count, then the Guides without a topic with title, description, access level, and UUID.

The reserved `dives` and `flights` topics are omitted here; they have their own entry points ([`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) and [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide)).

## Input parameters

This tool takes no arguments.

## Output

The tool returns the Guide as a plain-text document: navigation instructions followed by the topic overview. The response is mirrored into structured content as:

```json
{
  "text": string  // Navigation instructions plus the topic overview
}
```

The overview lists every topic with its Guide count first, then the root-level Guides:

```text
- data-quality/ (1 guide)
- revenue-billing/ (2 guides)
- revenue-billing/forecasting/ (1 guide)
- "Data platform overview" — what lives where in our warehouse (organization, uuid: a1b2c3d4-...)
```

## Example usage

When the user asks a data question, the assistant should call this tool before exploring the schema or writing SQL:

```text
What was our net revenue retention last quarter?
```

The assistant calls `get_query_guide`, sees that a `revenue-billing` topic exists, opens it with [`list_guides`](../list-guides), and reads the relevant Guide with [`get_guide`](../get-guide) before writing the query.

## Related

- [`list_guides`](../list-guides) — Browse the Guide catalog level by level.
- [`get_guide`](../get-guide) — Load a Guide's full content by UUID.
- [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) — Entry point for Dive conventions.
- [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide) — Entry point for Flight conventions.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

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

# list_guides
> Browse your organization's Guides level by level, grouped by topic
Browse your organization's [Guides](/key-tasks/guides/) — markdown documents that capture metric definitions, join conventions, and domain context that AI agents need to query your data accurately.

## Description

The `list_guides` tool browses the Guide catalog with progressive disclosure. Called with no arguments, it lists the root level: Guides with no topic plus every topic with its Guide count. Pass `topic` to open one — you get the Guides stored exactly at that topic and the nested topics below it.

Guides are identified by UUID. Use [`get_guide`](../get-guide) with a `uuid` from the listing to read a Guide in full.

For query guidance and a full topic overview in one call, start with [`get_query_guide`](../get-query-guide) instead.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topic` | string | No | Open this topic — for example `"revenue-billing"` or `"core/metrics"` (no leading or trailing slash). Omit for the root level. |

## Output schema

```json
{
  "success": boolean,
  "topic": string,           // The level being listed ("" for root)
  "topics": [
    {
      "topic": string,       // Nested topic path
      "guide_count": number  // Number of guides in that subtree
    }
  ],
  "guides": [
    {
      "uuid": string,        // Guide UUID — use with get_guide
      "topic": string,       // The guide's topic ("" for guides without a topic)
      "title": string,       // Guide title
      "access": string,      // "user" or "organization"
      "description": string  // One-line summary
    }
  ],
  "error": string            // Error message (on failure)
}
```

## Example usage

**Browse the root level:**

```text
What guides does my organization have?
```

The AI assistant calls the tool with no arguments and receives the Guides without a topic plus the top-level topics.

**Open a topic:**

```text
Show me the guides about revenue and billing
```

```json
{
  "topic": "revenue-billing"
}
```

**Open a nested topic:**

```json
{
  "topic": "core/metrics"
}
```

## Success response example

```json
{
  "success": true,
  "topic": "revenue-billing",
  "topics": [
    {
      "topic": "revenue-billing/forecasting",
      "guide_count": 2
    }
  ],
  "guides": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "topic": "revenue-billing",
      "title": "MRR and ARR Definitions",
      "access": "organization",
      "description": "How monthly and annual recurring revenue are calculated"
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "topic": "revenue-billing",
      "title": "Billing Edge Cases",
      "access": "organization",
      "description": "Pitfalls when querying the billing tables"
    }
  ]
}
```

## Related

- [`get_query_guide`](../get-query-guide) — Entry point: query guidance plus a full topic overview.
- [`get_guide`](../get-guide) — Load a Guide's full content by UUID.
- [`create_guide`](../create-guide) — Create a new Guide.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

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

# get_guide
> Load a Guide's full content by UUID, optionally pinning a historical version
Load a [Guide](/key-tasks/guides/) by UUID. Find a Guide's UUID with [`list_guides`](../list-guides) or through the entry points [`get_query_guide`](../get-query-guide), [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide), and [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide).

## Description

The `get_guide` tool returns a Guide's full markdown content plus its metadata and references. Guides are identified by UUID, consistent with Dives and Flights. Pass `version` to read a specific historical version; by default the current version is returned.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `version` | integer | No | Version number to read. Defaults to the current version. |

## Output

On success, the tool returns the Guide as a plain-text document rather than a JSON object: the title, a metadata line (UUID, topic, version, access level), the description, the full markdown content, and a references footer. The response is mirrored into structured content as:

```json
{
  "text": string  // The rendered guide document
}
```

On failure, the tool returns a structured error:

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

## Example usage

**Read a Guide found through the topic overview:**

```text
How should I calculate MRR for our billing data?
```

The assistant calls [`get_query_guide`](../get-query-guide) or [`list_guides`](../list-guides) to find the relevant Guide's UUID, then loads it:

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

**Read a specific historical version:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 2
}
```

## Success response example

```text
MRR and ARR Definitions
uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 · topic: revenue-billing · v3 · organization

How monthly and annual recurring revenue are calculated

# MRR and ARR Definitions

MRR is calculated as...

## References
- catalog md:billing main.subscriptions
```

## Related

- [`get_query_guide`](../get-query-guide) — Entry point: query guidance plus a topic overview.
- [`list_guides`](../list-guides) — Browse the Guide catalog to find a UUID.
- [`update_guide`](../update-guide) — Append a version to a Guide.
- [`edit_guide_content`](../edit-guide-content) — Make targeted in-place edits.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/create-guide

# create_guide
> Create a new Guide — a markdown document that AI agents use to answer your organization's data questions correctly
Create a new [Guide](/key-tasks/guides/) — a markdown document that captures metric definitions, join conventions, and domain context for your organization's data.

## Description

The `create_guide` tool creates a Guide identified by a generated UUID. Group related Guides with an optional lowercase kebab-case `topic` (for example `"revenue-billing"` or `"core/metrics"`); omit it to keep the Guide at the root level without a topic. Topics are grouping labels only — they carry no uniqueness, so multiple Guides can share the same topic.

Visibility is controlled by `access`: `"user"` (private, default) or `"organization"` (org-wide, admin-permission gated). Personal Dive and Flight style Guides belong under topic `"dives"` or `"flights"` with access `"user"` — they're surfaced by [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) and [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide).

Attach `references` to link the Guide to the 1–5 catalog objects, Dives, Flights, or other Guides it is authoritative about. References let [`list_tables`](/sql-reference/mcp/core/list-tables) and [`search_catalog`](/sql-reference/mcp/core/search-catalog) surface related Guides automatically.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | Human-readable title. Must not be empty. |
| `content` | string | Yes | Full markdown body of the Guide. Maximum 1 MB. |
| `topic` | string | No | Slash-separated grouping label — for example `"revenue-billing"` or `"core/metrics"` (no leading or trailing slash). Omit for no topic. |
| `description` | string | No | Short one-line summary shown in the Guide index. |
| `access` | string | No | `"user"` (private, default) or `"organization"` (org-wide, admin-permission gated). |
| `change_comment` | string | No | Optional note describing this initial version. |
| `external_id` | string | No | Optional caller-provided ID for this version (for example a git SHA). |
| `references` | array | No | Structured references to the 1–5 objects this Guide explains. See [reference object shape](#reference-object-shape). |

### Reference object shape

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | One of `"catalog"`, `"dive"`, `"flight"`, or `"guide"` |
| `url` | string | Conditional | MotherDuck URL — required for `catalog` type (for example `"md:my_database"` or a `"md:_share/..."` URL) |
| `schema` | string | Conditional | Schema name — required when `table`, `view`, or `macro` is set |
| `table` | string | No | Table name (catalog only) |
| `column` | string | No | Column name (catalog only, requires `table`) |
| `view` | string | No | View name (catalog only, mutually exclusive with `table`/`macro`) |
| `macro` | string | No | Macro name (catalog only, mutually exclusive with `table`/`view`) |
| `uuid` | string | Conditional | UUID of the referenced Dive, Flight, or Guide |
| `description` | string | No | Why this reference exists |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,                   // Generated UUID of the guide
    "topic": string,                // Grouping label (null if omitted)
    "title": string,                // Guide title
    "description": string,          // One-line summary
    "access": string,               // "user" or "organization"
    "current_version": number,      // Version number (1 for new guides)
    "created_at": string,           // ISO 8601 creation timestamp
    "updated_at": string,           // ISO 8601 last update timestamp
    "version_change_comment": string,
    "version_external_id": string,
    "version_created_at": string,
    "references": array             // Resolved references
  },
  "error": string                   // Error message (on failure)
}
```

## Example usage

**Create an org-wide metric definition Guide:**

```text
Create a guide explaining how we calculate MRR for the billing team
```

```json
{
  "title": "MRR and ARR Definitions",
  "topic": "revenue-billing",
  "description": "How monthly and annual recurring revenue are calculated",
  "access": "organization",
  "content": "# MRR and ARR Definitions\n\nMRR (Monthly Recurring Revenue) is the sum of all active subscription amounts normalized to a monthly value.\n\n## Key rules\n\n- Use the `subscriptions` table, not `invoices`\n- Filter to `status = 'active'`\n- Exclude trial subscriptions (`trial_end IS NULL`)",
  "references": [
    {
      "type": "catalog",
      "url": "md:billing",
      "schema": "main",
      "table": "subscriptions",
      "description": "Primary source for subscription revenue data"
    }
  ]
}
```

**Save personal Dive style preferences:**

```text
Remember that I prefer dark-themed Dives with the watermelon accent color
```

```json
{
  "title": "My Dive style preferences",
  "topic": "dives",
  "access": "user",
  "content": "## Style preferences\n\n- Dark theme by default\n- Watermelon accent color\n- Number formats: compact notation (1.2M, not 1,200,000)"
}
```

## Success response example

```json
{
  "success": true,
  "guide": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "topic": "revenue-billing",
    "title": "MRR and ARR Definitions",
    "description": "How monthly and annual recurring revenue are calculated",
    "access": "organization",
    "current_version": 1,
    "created_at": "2025-06-01T10:00:00Z",
    "updated_at": "2025-06-01T10:00:00Z",
    "version_change_comment": null,
    "version_external_id": null,
    "version_created_at": "2025-06-01T10:00:00Z",
    "references": [
      {
        "type": "catalog",
        "url": "md:billing",
        "schema": "main",
        "table": "subscriptions",
        "description": "Primary source for subscription revenue data"
      }
    ]
  }
}
```

## Related

- [`list_guides`](../list-guides) — Browse existing Guides before creating one.
- [`get_guide`](../get-guide) — Read a Guide's content.
- [`update_guide`](../update-guide) — Append a version to an existing Guide.
- [`edit_guide_content`](../edit-guide-content) — Make targeted in-place edits.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/update-guide

# update_guide
> Append a version to an existing Guide with updated content or references
Append a version to an existing [Guide](/key-tasks/guides/), identified by UUID. Use this to replace a Guide's full content. For smaller targeted edits, use [`edit_guide_content`](../edit-guide-content) instead.

## Description

The `update_guide` tool saves an updated version of an existing Guide. Omit `content` to carry the current text forward and only update metadata such as references. A supplied `references` list replaces the existing one — pass an empty array (`[]`) to clear all references, or omit `references` entirely to carry them forward.

To retitle or re-topic a Guide, use [`update_guide_metadata`](../update-guide-metadata). To change visibility, use [`set_guide_access`](../set-guide-access).

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `content` | string | No | New full markdown body. Omit to carry the current version's content forward. |
| `change_comment` | string | No | Optional note describing this version's change. |
| `external_id` | string | No | Optional caller-provided ID for this version (for example a git SHA). |
| `references` | array | No | Replaces the Guide's references. Pass `[]` to clear; omit to carry forward. See [reference object shape](/sql-reference/mcp/guides/create-guide#reference-object-shape). |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,
    "title": string,
    "description": string,
    "access": string,
    "current_version": number,
    "created_at": string,
    "updated_at": string,
    "version_change_comment": string,
    "version_external_id": string,
    "version_created_at": string,
    "references": array
  },
  "error": string
}
```

## Example usage

**Update the full content of a Guide:**

```text
Update the MRR guide to clarify that trial subscriptions are excluded
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "# MRR and ARR Definitions\n\n...(updated content)...",
  "change_comment": "Clarify trial subscription exclusion logic"
}
```

**Add references without changing content:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "references": [
    {
      "type": "catalog",
      "url": "md:billing",
      "schema": "main",
      "table": "subscriptions"
    },
    {
      "type": "catalog",
      "url": "md:billing",
      "schema": "main",
      "table": "invoices"
    }
  ]
}
```

**Clear all references:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "references": []
}
```

## Related

- [`edit_guide_content`](../edit-guide-content) — Make targeted in-place edits without replacing the full content.
- [`update_guide_metadata`](../update-guide-metadata) — Retitle, re-topic, or update the description.
- [`get_guide`](../get-guide) — Read the current Guide content before updating.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/edit-guide-content

# edit_guide_content
> Apply targeted string replacements to a Guide and save the result as a versioned update
Apply one or more string replacements to a [Guide](/key-tasks/guides/), identified by UUID, and save the result as an updated version. No prior [`get_guide`](../get-guide) call is needed.

## Description

The `edit_guide_content` tool reads the stored Guide, applies the supplied edits in sequence, and persists the result as a version update. This is the right choice for small, targeted changes such as fixing a typo, updating a table name, or adding a section. For replacing the entire content, use [`update_guide`](../update-guide).

Each edit must supply an `old_string` that is unique in the current content (unless `replace_all` is set), and a different `new_string`. Edits apply in order — the output of one edit is the input for the next.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `edits` | array | Yes | List of edits to apply in sequence. At least one edit is required. |
| `change_comment` | string | No | Optional note describing this version's change. |
| `external_id` | string | No | Optional caller-provided ID for this version (for example a git SHA). |

### Edit object shape

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `old_string` | string | Yes | The exact text to find. Must be unique in the content unless `replace_all` is true. |
| `new_string` | string | Yes | The replacement text. Must differ from `old_string`. |
| `replace_all` | boolean | No | Replace all occurrences of `old_string`. Defaults to `false`. |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,
    "title": string,
    "description": string,
    "access": string,
    "current_version": number,
    "created_at": string,
    "updated_at": string,
    "version_change_comment": string,
    "version_external_id": string,
    "version_created_at": string,
    "references": array
  },
  "edits_applied": number,       // Number of edits applied
  "total_replacements": number,  // Total string replacements made
  "error": string,               // Error message (on failure)
  "hint": string                 // Hint when old_string was not found (on failure)
}
```

## Example usage

**Fix a table name across a Guide:**

```text
Rename the orders table to customer_orders in the billing guide
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "edits": [
    {
      "old_string": "billing.main.orders",
      "new_string": "billing.main.customer_orders",
      "replace_all": true
    }
  ],
  "change_comment": "Rename orders to customer_orders after table migration"
}
```

**Apply multiple edits in one call:**

```json
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "edits": [
    {
      "old_string": "updated_at < CURRENT_TIMESTAMP - INTERVAL '24 hours'",
      "new_string": "updated_at < CURRENT_TIMESTAMP - INTERVAL '12 hours'"
    },
    {
      "old_string": "daily freshness threshold",
      "new_string": "12-hour freshness threshold"
    }
  ],
  "change_comment": "Tighten freshness SLA from 24h to 12h"
}
```

## Success response example

```json
{
  "success": true,
  "guide": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "topic": "revenue-billing",
    "title": "MRR and ARR Definitions",
    "description": "How monthly and annual recurring revenue are calculated",
    "access": "organization",
    "current_version": 4,
    "created_at": "2025-06-01T10:00:00Z",
    "updated_at": "2025-07-01T14:22:00Z",
    "version_change_comment": "Rename orders to customer_orders after table migration",
    "version_external_id": null,
    "version_created_at": "2025-07-01T14:22:00Z",
    "references": []
  },
  "edits_applied": 1,
  "total_replacements": 3
}
```

## Error response example

```json
{
  "success": false,
  "error": "old_string not found in guide content",
  "edits_applied": 0,
  "hint": "The string 'billing.main.orders' was not found. Check that the text matches exactly, including whitespace."
}
```

## Related

- [`update_guide`](../update-guide) — Replace the full content in one call.
- [`get_guide`](../get-guide) — Read the current content to identify the text to replace.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/update-guide-metadata

# update_guide_metadata
> Change a Guide's title, description, or topic without creating a content version
Change a [Guide](/key-tasks/guides/)'s title, description, or topic without appending a content version. The Guide keeps its UUID and full version history.

## Description

The `update_guide_metadata` tool lets you retitle or re-topic a Guide without touching its content. Use it when a Guide's title or grouping is outdated — for example after a team reorganization or a product rename.

Provide at least one of `title`, `description`, or `topic`.

To update content, use [`update_guide`](../update-guide) or [`edit_guide_content`](../edit-guide-content) instead.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `title` | string | No | New human-readable title. Must not be empty when supplied. |
| `description` | string | No | New one-line summary. Pass an empty string (`""`) to clear it. |
| `topic` | string | No | New grouping label — for example `"revenue-billing"` or `"core/metrics"` (no leading or trailing slash). Pass an empty string (`""`) to remove the topic. |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,           // Updated topic (null when cleared)
    "title": string,           // Updated title
    "description": string,     // Updated description
    "access": string,
    "current_version": number,
    "created_at": string,
    "updated_at": string
  },
  "error": string
}
```

## Example usage

**Move a Guide to a different topic:**

```text
Move the order filters guide from order-management to customer-orders
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "topic": "customer-orders",
  "title": "Customer Order Filters"
}
```

**Update only the description:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "description": "MRR and ARR definitions, including expansion and churn adjustments"
}
```

**Remove the topic (move the Guide to the root level):**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "topic": ""
}
```

## Related

- [`update_guide`](../update-guide) — Append a content version.
- [`edit_guide_content`](../edit-guide-content) — Make targeted in-place content edits.
- [`set_guide_access`](../set-guide-access) — Change a Guide's visibility.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/set-guide-access

# set_guide_access
> Change a Guide's visibility between private and org-wide
Change a [Guide](/key-tasks/guides/)'s visibility to `"user"` (private) or `"organization"` (visible to your whole org). Setting org-wide access is admin-permission gated.

## Description

The `set_guide_access` tool controls who can see and read a Guide:

- **`"user"`** — private to the Guide's owner. Only you can read or modify it.
- **`"organization"`** — visible to everyone in your MotherDuck organization. Setting this level requires admin permission.

Use this tool to promote a personal Guide to org-wide after review, or to make a Guide private again. Access is the only visibility mechanism — a Guide's topic has no effect on who can see it.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `access` | string | Yes | `"user"` (private) or `"organization"` (org-wide, admin-permission gated). |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,
    "title": string,
    "description": string,
    "access": string,       // Updated access level
    "current_version": number,
    "created_at": string,
    "updated_at": string
  },
  "error": string
}
```

## Example usage

**Publish a Guide to the whole org:**

```text
Make the MRR definitions guide available to the whole organization
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "access": "organization"
}
```

**Make a Guide private again:**

```json
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "access": "user"
}
```

## Related

- [`create_guide`](../create-guide) — Set access at creation time.
- [`update_guide_metadata`](../update-guide-metadata) — Change title, description, or topic.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/delete-guide

# delete_guide
> Soft-delete a Guide while preserving its version history
Soft-delete a [Guide](/key-tasks/guides/), identified by UUID. The version history is preserved for audit purposes.

## Description

The `delete_guide` tool removes a Guide from the active catalog. The Guide's version history is retained internally but is not exposed through normal tools after deletion. Only the Guide's owner can delete it.

References from other Guides to a deleted Guide are left dangling and resolve to not-found — clean them up in the referencing Guides if needed.

There is no undo through the MCP tools — if you delete a Guide by mistake, contact MotherDuck support.

:::warning
Deleting an org-wide Guide removes it from all users' Guide catalogs immediately. Verify you have the right Guide (read it with [`get_guide`](../get-guide)) before confirming deletion.
:::

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |

## Output schema

```json
{
  "success": boolean,
  "deleted": boolean,  // true when the guide was successfully deleted
  "error": string      // Error message (on failure)
}
```

## Example usage

**Delete a Guide:**

```text
Delete the outdated order-management guide
```

The assistant finds the Guide's UUID with [`list_guides`](../list-guides), verifies it's the right one, and calls:

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

## Success response example

```json
{
  "success": true,
  "deleted": true
}
```

## Related

- [`list_guides`](../list-guides) — Find the Guide's UUID before deleting.
- [`get_guide`](../get-guide) — Verify the Guide content before deleting.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

## Docs feedback

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

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fmcp%2F&page_title=MotherDuck%20Documentation%20-%20MCP%20Server&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

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