MotherDuck is DuckDB-as-a-service — analytical SQL with built-in sharing and durability. Connecting MotherDuck to clariBI exposes every workspace, database, and table as a first-class analytical source.
Why connect MotherDuck
Analytical SQL questions usually mean opening a SQL editor, pasting credentials, and running a query. With MotherDuck connected, the AI engine writes and runs SQL itself, then narrates the result.
You can ask "Average order value by region last quarter from the orders table", "Show me schemas in the analytics database", or "Top 10 SKUs by revenue this year" and the AI engine routes through MotherDuck.
How the connection works
clariBI talks to MotherDuck through its hosted MCP server at https://api.motherduck.com/mcp. Authentication uses an OAuth flow that clariBI registers itself for (no developer console setup on your side). Tokens stay encrypted server-side and never leave clariBI in clear form.
sequenceDiagram
actor U as You
participant C as clariBI
participant V as MotherDuck
U->>C: Click Authorize with MotherDuck
C->>V: Open OAuth authorization
V-->>U: Grant read access?
U->>V: Approve
V-->>C: Authorization code
C->>V: Exchange code for tokens
V-->>C: Access + refresh tokens
C->>C: Encrypt and store credentials
C-->>U: Connection ready
Available tools
clariBI exposes the read-only MotherDuck tools that the vendor's MCP server publishes at connection time. Write operations (create, update, delete, send, refund) are filtered out by a name-pattern blocklist before any tool reaches the analysis engine, so connecting MotherDuck cannot modify data on the vendor side.
The exact tool inventory depends on the MotherDuck features your account has access to. After connecting, try a few natural-language questions to see what MotherDuck data clariBI can pull.
Data flow during analysis
When you ask a question that maps to MotherDuck, the AI engine routes to the right tool, reads the result, and pairs the answer with a chart you can pin to a dashboard.
sequenceDiagram
actor U as You
participant C as clariBI
participant AI as AI engine
participant V as MotherDuck
U->>C: Ask a question about analytical SQL data in MotherDuck/DuckDB
C->>AI: Plan the analysis
AI->>V: Call the right tool
V-->>AI: Tool result
AI->>AI: Summarize and chart
C-->>U: Answer plus visual
Setting up the connection
- Open Data Sources in the clariBI sidebar.
- Click Add data source.
- Open the MCP Servers tab.
- Click the MotherDuck card.
- Click Authorize with MotherDuck.
- Sign in to MotherDuck in the popup window and grant the requested read scopes.
- Back in clariBI, give your data source a name.
- Click Finish.
Permissions and data access
OAuth scoping is granted at authorize time on the MotherDuck consent screen. clariBI restricts itself to read-only tools (no create_*, insert_*, delete_*). Disconnect from MotherDuck account settings or from clariBI Settings.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
| "Database not found" | The database was renamed or moved between workspaces. | Use the current workspace + database names in the question; the schema cache refreshes on the next query. |