motherduckdb/agent-skills / plugins/motherduck-skills-claude/skills/motherduck-connect
motherduck-connect
VerifiedSet up or troubleshoot MotherDuck connections, the MotherDuck MCP server in AI clients, authentication, client runtimes, and read scaling.
Connect to MotherDuck
Source Of Truth
- Prefer current MotherDuck connection, attach-mode, read-scaling, and multithreading docs.
- If the MotherDuck MCP
ask_docs_questiontool is available, use it first for current connection behavior. - When it is unavailable, verify guidance against the public docs before making firm claims about connection strings, token types, or read-scaling behavior.
Default Posture
- Start with the PG endpoint (MotherDuck's Postgres-compatible endpoint) for backend applications, BI tools, and serverless runtimes that want PostgreSQL wire compatibility.
- For BI tools, treat the PG endpoint as the compatibility path for Power BI and Tableau Cloud when current docs list them as supported.
- Use the native DuckDB API when you need local files, hybrid local/cloud execution, or direct DuckDB control.
- Use
md:workspace connections for multi-database exploration, bootstrap flows, and temporary validation environments. - Reuse an existing connection, connector, or environment-managed token when the user's context already provides one; do not ask for secrets that can be discovered from the active workspace. When only the MotherDuck MCP server is connected and a one-off local session needs credentials,
get_short_lived_tokenreturns a temporary token and endpoint details; pass it through the process environment and never write it to files, code, or logs. Deployed services still need a service-account token. - Start with one connection. Add pooling or read scaling only when real concurrent-read pressure exists.
- For services that should fail over instead of blocking while a Duckling starts, bound native
md:connects withconnection_timeout(md:my_db?connection_timeout=30s,MOTHERDUCK_CONNECTION_TIMEOUT, orSET motherduck_connection_timeout = '30s'before the firstATTACH 'md:'). It applies to DuckDB clients with the MotherDuck extension, not the PG endpoint or Wasm. Without it, only network retries are bounded. - To connect an AI client (Claude, Cursor, VS Code, Gemini CLI, ChatGPT, Codex) to MotherDuck, use the hosted MCP server at
https://api.motherduck.com/mcp; readreferences/MCP_SETUP.md. - Use native DuckDB
custom_user_agentwhere supported; for PG endpoint clients, prefer the client'sapplication_namesetting when available. The tag shows per query in the Duckling Overview, which makes it the quickest way to see which workload is using a Duckling.
Runtime Selection
Pick the connection method (above) and the runtime separately. The runtime is what actually executes queries: MotherDuck MCP, the MotherDuck CLI, a Python or Node process, or the DuckDB CLI.
For answer, review, or planning requests, inspect the available runtimes and recommend a path without installing anything. Install or configure a runtime only when the user asks to connect, build, or change the application.
Reuse the project’s language, dependencies, and working connection. Prefer MCP for chat-only exploration and the MotherDuck CLI for file-shaped Dive/Flight work or large output. For application code, use its existing runtime; choose a new runtime only when none is established.
Before installing a DuckDB client, check https://motherduck.com/docs/duckdb-versions.json and pin a MotherDuck-supported version. Keep an existing compatible pin unless the task requires an upgrade. See the runtime reference for installation examples.
Workflow
- Choose the connection path for the workload; keep ingestion and serving paths distinct when their needs differ.
- Put the MotherDuck token in environment-managed secrets, not in source code.
- Establish the connection with explicit SSL settings where required.
- Verify the connection with
SELECT 1 AS connectedand then list reachable tables. - If the workload is read-heavy and concurrent, evaluate read scaling and a stable
session_nameper end user.
References
- Read
references/MCP_SETUP.mdto add the MotherDuck MCP server to an AI client.
Read only the reference sections needed for the current task.
- Read
references/CONNECTION_GUIDE.mdfor connection-method selection, PG endpoint and native DuckDB examples, token handling, read scaling, attach modes, and common failure modes - Read
references/RUNTIME_SELECTION.mdfor the MCP-vs-Python-vs-Node-vs-CLI decision tree, detection commands, install snippets, and the DuckDB version-pinning workflow
Related Skills
Load related skills only for missing capabilities; reuse established context.
motherduck-explorefor discovering databases, tables, columns, and shares after the connection is establishedmotherduck-queryfor executing DuckDB SQL against the connected databasesmotherduck-duckdb-sqlfor DuckDB syntax and function lookup supportmotherduck-rest-apifor control-plane admin operations; those useMOTHERDUCK_ADMIN_TOKEN, which is never used for database connectionsmotherduck-clifor terminal queries and file-oriented Dive/Flight authoring
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |