MotherDuck MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your MotherDuck MCP credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   MotherDuck MCP uses Dynamic Client Registration (DCR) — no client ID or secret is needed. The only step is registering your Scalekit redirect URI as an allowed domain in Atlassian Administration.

   1. Copy the redirect URI from Scalekit

      In the Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find MotherDuck MCP and click Create. Copy the redirect URI — it looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

   2. Open the Rovo MCP server settings in Atlassian

      • Go to admin.atlassian.com and select your organisation.
      • In the left sidebar, expand Rovo and click Rovo access.
      • Click Rovo MCP server in the submenu.
      • Select the Domains tab at the top of the page.

      Admin access required

      You must be an Atlassian organisation admin to access these settings. If you don’t see Rovo in the sidebar, your organisation may not have Rovo enabled.

   3. Add the redirect URI as a domain

      • Under Your domains, click Add domain.
      • In the Add domain dialog, paste the redirect URI from Scalekit into the Domain field.
      • Accept the terms and click Add.

      Once added, Scalekit automatically registers the OAuth client via DCR and handles token management for every user who authorizes the connection — no further configuration needed.

4. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'motherduckmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize MotherDuck MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'motherduckmcp_get_flight_guide',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "motherduckmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize MotherDuck MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="motherduckmcp_get_flight_guide",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Question ask docs — Query official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices
• Run cancel flight, flight — Cancel an in-progress Flight run
• Create flight — Create a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute
• Delete dive, flight — Permanently remove a Dive from the MotherDuck workspace
• Source edit flight — Edit a Flight’s source code through one or more find-and-replace operations, producing a new FlightVersion
• Get dive guide, flight, flight guide — Retrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client

Common workflows

Get your cloud ID

Most MotherDuck MCP tools require a cloudId — the UUID that identifies your Atlassian cloud site. Call motherduckmcp_getaccessibleatlassianresources once to retrieve it, then pass the id field value in every subsequent tool call.

Call this tool first

Run motherduckmcp_getaccessibleatlassianresources before calling any Jira or Confluence tool. The response lists every Atlassian site the user has access to. Use the id field as cloudId.

Node.js

// Step 1 — get the cloud ID
const resources = await actions.executeTool({
  connectionName: 'motherduckmcp',
  identifier: 'user_123',
  toolName: 'motherduckmcp_getaccessibleatlassianresources',
  toolInput: {},
});
const cloudId = resources[0].id;

// Step 2 — use cloudId in subsequent calls
const issue = await actions.executeTool({
  connectionName: 'motherduckmcp',
  identifier: 'user_123',
  toolName: 'motherduckmcp_getjiraissue',
  toolInput: {
    cloudId,
    issueIdOrKey: 'KAN-1',
  },
});
console.log(issue);

Python

# Step 1 — get the cloud ID
resources = actions.execute_tool(
    connection_name="motherduckmcp",
    identifier="user_123",
    tool_name="motherduckmcp_getaccessibleatlassianresources",
    tool_input={},
)
cloud_id = resources[0]["id"]

# Step 2 — use cloud_id in subsequent calls
issue = actions.execute_tool(
    connection_name="motherduckmcp",
    identifier="user_123",
    tool_name="motherduckmcp_getjiraissue",
    tool_input={
        "cloudId": cloud_id,
        "issueIdOrKey": "KAN-1",
    },
)
print(issue)

The motherduckmcp_getaccessibleatlassianresources response looks like this:

[
  {
    "id": "a4c9b3e2-1234-5678-abcd-ef0123456789",
    "name": "My Company",
    "url": "https://mycompany.atlassian.net",
    "scopes": ["read:jira-work", "write:jira-work", "read:confluence-content.all"]
  }
]

Use id as the cloudId parameter. If the user belongs to multiple Atlassian sites, the list contains one entry per site — pick the one matching the target url.

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

motherduckmcp_ask_docs_question # Query official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices. 1 param ▾

Query official DuckDB and MotherDuck documentation to answer questions about SQL syntax, features, and best practices.

Name Type Required Description

question string required Question about DuckDB or MotherDuck.

motherduckmcp_cancel_flight_run # Cancel an in-progress Flight run. Returns an error if the run is already in a terminal state. 2 params ▾

Cancel an in-progress Flight run. Returns an error if the run is already in a terminal state.

Name Type Required Description

id string required Flight identifier (UUID).

run_number integer required Sequential run number to cancel, as returned by list_flight_runs.

motherduckmcp_create_flight # Create a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute. Supports optional cron scheduling. 7 params ▾

Create a new Flight — a Python entrypoint with optional dependencies that executes on MotherDuck compute. Supports optional cron scheduling.

Name Type Required Description

name string required Identifier for the Flight.

source_code string required Python program code for the Flight entrypoint. Should end with: if __name__ == "__main__": main()

config object optional Non-secret environment variable key-value pairs to pass to the Flight at runtime.

md_secret_names array optional Secret names to surface as environment variables inside the Flight execution context.

md_token_name string optional MotherDuck access token label; uses the default token if omitted.

requirements_txt string optional Pinned package dependencies in requirements.txt format, one package per line.

schedule_cron string optional UTC 5-field cron expression for automatic scheduling (e.g. '0 9 * * 1' for Mondays at 9am UTC).

motherduckmcp_delete_dive # Permanently remove a Dive from the MotherDuck workspace. This action cannot be undone. 1 param ▾

Permanently remove a Dive from the MotherDuck workspace. This action cannot be undone.

Name Type Required Description

id string required Unique identifier of the Dive to delete.

motherduckmcp_delete_flight # Permanently delete a Flight, its versions, schedule, and run history. This action cannot be undone. 1 param ▾

Permanently delete a Flight, its versions, schedule, and run history. This action cannot be undone.

Name Type Required Description

id string required Flight identifier (UUID) of the Flight to permanently delete.

motherduckmcp_edit_flight_source # Edit a Flight's source code through one or more find-and-replace operations, producing a new FlightVersion. Applies edits sequentially and validates the result. 2 params ▾

Edit a Flight's source code through one or more find-and-replace operations, producing a new FlightVersion. Applies edits sequentially and validates the result.

Name Type Required Description

edits array required List of find-and-replace edit operations to apply sequentially to the Flight source code.

id string required Flight identifier (UUID).

motherduckmcp_get_dive_guide # Retrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client. 1 param ▾

Retrieve comprehensive instructions for creating MotherDuck Dives (interactive React data apps), tailored to the calling AI client.

Name Type Required Description

client string required AI platform making the request.

motherduckmcp_get_flight # Fetch a Flight's metadata and version snapshot by UUID, including source code, requirements, config, secret names, and token name. 2 params ▾

Fetch a Flight's metadata and version snapshot by UUID, including source code, requirements, config, secret names, and token name.

Name Type Required Description

id string required Flight identifier.

version integer optional 1-indexed version number; omit for current version.

motherduckmcp_get_flight_guide # Retrieve the authoritative guide for working with MotherDuck Flights (anatomy, config vs. secrets, scheduling, run lifecycle, common failures). Call this first before using other Flight tools. 0 params ▾

Retrieve the authoritative guide for working with MotherDuck Flights (anatomy, config vs. secrets, scheduling, run lifecycle, common failures). Call this first before using other Flight tools.

motherduckmcp_get_flight_run_logs # Fetch the logs and run record for a single Flight run, combining stdout/stderr with status, exit code, and timing. 3 params ▾

Fetch the logs and run record for a single Flight run, combining stdout/stderr with status, exit code, and timing.

Name Type Required Description

id string required Flight identifier (UUID).

run_number integer required Sequential run number for this Flight, as returned by list_flight_runs.

max_bytes integer optional Cap response size in bytes (minimum 1024). When the log exceeds this limit, the tail of the log is returned.

motherduckmcp_list_columns # List all columns of a table or view with data types, nullability, and comments. 3 params ▾

List all columns of a table or view with data types, nullability, and comments.

Name Type Required Description

table string required Table or view name. Accepts simple or fully qualified names (e.g. analytics.main.customers).

database string optional Database name; defaults to current database.

schema string optional Schema name; defaults to current schema (main).

motherduckmcp_list_databases # Retrieve all databases accessible to the MotherDuck account, including owned databases and attached shared databases. 0 params ▾

Retrieve all databases accessible to the MotherDuck account, including owned databases and attached shared databases.

motherduckmcp_list_dives # Return all Dives owned in the MotherDuck workspace, including metadata like version history and timestamps. Optionally filter by keywords. 1 param ▾

Return all Dives owned in the MotherDuck workspace, including metadata like version history and timestamps. Optionally filter by keywords.

Name Type Required Description

keywords string optional Keywords to filter by title/description (case-insensitive, all words must match).

motherduckmcp_list_flight_runs # Retrieve the execution history of a Flight (newest first), including run number, status, timing, and effective config. 2 params ▾

Retrieve the execution history of a Flight (newest first), including run number, status, timing, and effective config.

Name Type Required Description

id string required Flight identifier (UUID).

limit integer optional Maximum number of results to return (default 100, max 500).

motherduckmcp_list_flight_versions # Retrieve the complete version history of a Flight (newest first), enabling change tracking between versions. 2 params ▾

Retrieve the complete version history of a Flight (newest first), enabling change tracking between versions.

Name Type Required Description

id string required Flight identifier (UUID).

limit integer optional Maximum number of results to return (default 100, max 500).

motherduckmcp_list_flights # List all Flights owned by the caller with summary metadata (UUID, name, schedule, status, current version). Optionally filter by keyword. 2 params ▾

List all Flights owned by the caller with summary metadata (UUID, name, schedule, status, current version). Optionally filter by keyword.

Name Type Required Description

keywords string optional Filter Flights by name (case-insensitive, all words must match).

limit integer optional Maximum number of results to return (default 100, max 500).

motherduckmcp_list_shares # Retrieve all database shares that have been shared with the user by other MotherDuck users. Each share includes a name and URL for attaching via the ATTACH command. 0 params ▾

Retrieve all database shares that have been shared with the user by other MotherDuck users. Each share includes a name and URL for attaching via the ATTACH command.

motherduckmcp_list_tables # List all tables and views in a MotherDuck database, including schema, type (table or view), and any comments. 2 params ▾

List all tables and views in a MotherDuck database, including schema, type (table or view), and any comments.

Name Type Required Description

database string required Database name to list tables from.

schema string optional Schema filter; omitting returns tables from all schemas.

motherduckmcp_query # Execute read-only SQL queries against MotherDuck databases using DuckDB SQL syntax. Cross-database queries are supported via fully qualified names. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds. 2 params ▾

Execute read-only SQL queries against MotherDuck databases using DuckDB SQL syntax. Cross-database queries are supported via fully qualified names. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds.

Name Type Required Description

database string required Database name to query.

sql string required DuckDB SQL statement (read-only; mutation statements are rejected).

motherduckmcp_query_rw # Execute SQL statements that can read or modify data and schema in MotherDuck databases using DuckDB SQL syntax. Supports DDL and DML operations. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds. 2 params ▾

Execute SQL statements that can read or modify data and schema in MotherDuck databases using DuckDB SQL syntax. Supports DDL and DML operations. Results are capped at 2,048 rows and 50,000 characters. Timeout is 55 seconds.

Name Type Required Description

sql string required DuckDB SQL statement (read or write).

database string optional Database name to target. Required when targeting database objects; optional for account-level operations.

motherduckmcp_read_dive # Retrieve a Dive's complete details including title, description, timestamps, and full React component source code. 2 params ▾

Retrieve a Dive's complete details including title, description, timestamps, and full React component source code.

Name Type Required Description

id string required Unique identifier of the Dive.

version number optional Version number to retrieve (1-indexed); defaults to latest.

motherduckmcp_run_flight # Trigger an asynchronous execution of a Flight using its current version. Returns a Run record immediately in PENDING or RUNNING state. 2 params ▾

Trigger an asynchronous execution of a Flight using its current version. Returns a Run record immediately in PENDING or RUNNING state.

Name Type Required Description

id string required Flight identifier (UUID) to trigger an execution for.

config object optional Key-value pairs to override stored config for this execution only. Does not persist to the Flight definition.

motherduckmcp_save_dive # Create a new Dive in the MotherDuck workspace. Validates JSX/React component code and analyzes database dependencies. 3 params ▾

Create a new Dive in the MotherDuck workspace. Validates JSX/React component code and analyzes database dependencies.

Name Type Required Description

content string required JSX/React component code.

title string required Name of the Dive.

description string optional Brief explanation of the Dive.

motherduckmcp_search_catalog # Fuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring. Results are ranked by relevance. 2 params ▾

Fuzzy search across the MotherDuck catalog (databases, schemas, tables, columns, shares) using Jaro-Winkler similarity scoring. Results are ranked by relevance.

Name Type Required Description

query string required Search term; supports partial matching, underscores, dots.

object_types array optional Filter to specific object types. If omitted, searches all types.

motherduckmcp_share_dive_data # Make a Dive's underlying data accessible to your organization by creating org-scoped shares for owned databases referenced by the Dive's SQL queries. 1 param ▾

Make a Dive's underlying data accessible to your organization by creating org-scoped shares for owned databases referenced by the Dive's SQL queries.

Name Type Required Description

diveId string required Unique identifier of the Dive.

motherduckmcp_update_dive # Update an existing Dive's title, description, or content. At least one optional field must be provided. 4 params ▾

Update an existing Dive's title, description, or content. At least one optional field must be provided.

Name Type Required Description

id string required Unique identifier of the Dive to update.

content string optional New JSX/React component code.

description string optional New description for the Dive.

title string optional New title for the Dive.

motherduckmcp_update_flight # Update a Flight's source code, dependencies, config, authentication tokens, secrets, name, or schedule. Omitted fields remain unchanged. Code/dependency/config/secret changes create a new FlightVersion. 8 params ▾

Update a Flight's source code, dependencies, config, authentication tokens, secrets, name, or schedule. Omitted fields remain unchanged. Code/dependency/config/secret changes create a new FlightVersion.

Name Type Required Description

id string required Flight identifier (UUID).

config object optional Full replacement config map of non-secret environment variable key-value pairs. Providing this field creates a new FlightVersion.

md_secret_names array optional Replacement list of secret names to surface as environment variables. Providing this field creates a new FlightVersion.

md_token_name string optional MotherDuck token label for authentication. Providing this field creates a new FlightVersion.

name string optional Updated name for the Flight (metadata-only change, does not create a new FlightVersion).

requirements_txt string optional Package dependencies in requirements.txt format. Providing this field creates a new FlightVersion.

schedule_cron string optional 5-field cron expression in UTC. Pass an empty string to clear the existing schedule.

source_code string optional Python entrypoint code. Providing this field creates a new FlightVersion.

motherduckmcp_view_dive # Render a MotherDuck Dive as a live, interactive MCP app inside the host client. 3 params ▾

Render a MotherDuck Dive as a live, interactive MCP app inside the host client.

Name Type Required Description

dive_id string required Unique identifier of the Dive to render.

initial_state object optional Seeds the Dive's UI state; keys match useDiveState hook calls; values must be JSON-serializable.

required_resources array optional Override declared databases for this render. Each entry must have a url and an optional alias.