Connect to MotherDuck

Source Of Truth

• Prefer current MotherDuck connection, attach-mode, read-scaling, and multithreading docs.
• If the MotherDuck MCP ask_docs_question tool 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_token returns 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 with connection_timeout (md:my_db?connection_timeout=30s, MOTHERDUCK_CONNECTION_TIMEOUT, or SET motherduck_connection_timeout = '30s' before the first ATTACH '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; read references/MCP_SETUP.md.
• Use native DuckDB custom_user_agent where supported; for PG endpoint clients, prefer the client's application_name setting 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.