Connect to the MotherDuck MCP Server

The MotherDuck MCP Server lets AI assistants query and explore your databases using the Model Context Protocol (MCP). This guide walks you through connecting your preferred AI client to the remote MCP server (fully managed, zero setup). For local DuckDB files or self-hosted setups, see the local MCP server.

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. You can also authenticate with a Bearer token instead of OAuth.

Prerequisites

• A MotherDuck account (sign up free)
• An MCP-compatible AI client (Claude, ChatGPT, Cursor, Claude Code, Codex, or others)

Set up the remote MCP server

Select your MCP client and follow the instructions to connect.

Claude

Add MotherDuck to Claude

Or manually:

1. Go to Settings → Connectors
2. Click Browse Connectors to find the MotherDuck connector

A browser window should open for authentication. After authentication you can double check the connection by asking "List all my databases on MotherDuck."

ChatGPT

Add MotherDuck to ChatGPT

1. Open the ChatGPT desktop or web app
2. Go to Settings → Apps and click Browse Apps

3. Search for MotherDuck and select it

4. Click Continue to MotherDuck and authenticate with your MotherDuck account

After authentication, ChatGPT can access your MotherDuck data. Try asking "List all my databases on MotherDuck" to verify the connection.

Cursor

Add MotherDuck to Cursor

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Tools & MCP
3. Click + New MCP Server
4. Add the following to the configuration file:

{
  "MotherDuck": {
    "url": "https://api.motherduck.com/mcp",
    "type": "http"
  }
}

5. Save and click Connect to authenticate with your MotherDuck account

Cursor MCP Documentation

Claude Code

1. Run the following command in your terminal:

claude mcp add MotherDuck --transport http https://api.motherduck.com/mcp

tip

By default, this command adds the MCP server to the current project. You can also pass the --scope user flag, and the MCP server will be available for all sessions from your current user (--scope documentation).

2. Run claude to start Claude Code
3. Type /mcp, select MotherDuck from the list, and press Enter
4. Select Authenticate and confirm the authorization dialog

Claude Code MCP Documentation

GitHub Copilot (VS Code)

Configure GitHub Copilot in VS Code to use the MotherDuck MCP server through a workspace config file:

1. Open the Command Palette (Cmd/Ctrl + Shift + P) and run MCP: Add Server to open .vscode/mcp.json. You can also create the file manually in your workspace. Add this configuration:

{
  "servers": {
    "motherduck": {
      "type": "http",
      "url": "https://api.motherduck.com/mcp"
    }
  }
}

2. Save the file and start the server from the Start code lens that appears above the motherduck entry in mcp.json. You can also start it through the Command Palette: MCP: List Servers → motherduck → Start Server.

3. VS Code opens a browser window so you can sign in to MotherDuck through OAuth, then stores the credentials for subsequent server starts.

4. Open the Copilot Chat view, switch to Agent mode, and confirm that the MotherDuck tools appear in the tool picker. Try asking "List all my databases on MotherDuck" to verify the connection.

Authenticate with an access token instead of OAuth

If you'd rather provide a MotherDuck access token explicitly, use a promptString input and a Bearer Authorization header. VS Code prompts for the token when the server starts and stores it in its secret store:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "motherduck-token",
      "description": "MotherDuck access token",
      "password": true
    }
  ],
  "servers": {
    "motherduck": {
      "type": "http",
      "url": "https://api.motherduck.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:motherduck-token}"
      }
    }
  }
}

VS Code MCP Documentation

Copilot Studio

Microsoft Copilot Studio is a cloud-hosted platform for building agents that run inside Microsoft 365, Teams, and other Microsoft surfaces. Because the platform runs in Microsoft's cloud, it connects to the remote MotherDuck MCP server — either with OAuth (each user signs in with their own MotherDuck account) or with a shared API key backed by a service-account token.

1. In Copilot Studio, open your agent. Under Tools, click Add a tool.

   

2. In the Add tool dialog, under Create new, click Model Context Protocol.

   

3. Fill in the MCP server details and pick an authentication method:

   • Server name: MotherDuck MCP
   • Server description: Connect to MotherDuck, query your data, create Dives and more!
   • Server URL: https://api.motherduck.com/mcp
   • Authentication: either OAuth 2.0 or API key (see below)

   Option A — OAuth 2.0 (dynamic discovery). Each end user signs in to MotherDuck with their own account when they first use the agent. Select OAuth 2.0 and leave Dynamic discovery as the type, then click Create.

   

   Option B — API key (shared service-account token). All end users share a single MotherDuck token. Useful when you don't want every user to provision a MotherDuck account, for example a Teams bot exposed to a wide audience. Select API key, set Type to Header, enter Authorization as the Header name, and click Create.

   
   caution

   Header name must be Authorization — not Bearer. The Bearer prefix belongs in the value you enter in step 5.

4. Back in the Add tool dialog for MotherDuck MCP, open the Connection dropdown and click Create new connection.

   

   The next step depends on the authentication method you picked in step 3:

   • OAuth 2.0: Copilot Studio opens a browser window that redirects to MotherDuck. The end user signs in to their MotherDuck account and approves the request. The connection is created once authentication completes — skip to step 6.
   • API key: Copilot Studio shows the token entry dialog described in step 5.

5. In the Connect to MotherDuck MCP dialog, enter your MotherDuck access token prefixed with Bearer :

   Bearer <your_motherduck_token>

   Replace <your_motherduck_token> with an actual token from MotherDuck → Settings → Access Tokens, then click Create.

   
   tip

   If the agent is published and used by many end users, create a dedicated service account and use a read scaling token so the agent can't modify data. See Restricting to read-only access for details.

6. Once the connection shows a green check mark, click Add and configure. Copilot Studio confirms the tool was added successfully.

7. The MotherDuck MCP entry opens with the full tool list. Enable or disable tools based on what the agent should be allowed to do (for example, disable query_rw if the agent should stay read-only), then click Save.

   

8. Open the agent's connection manager and click Connect on the MotherDuck MCP entry, then submit. This reuses the connection you created in step 5.

9. Switch to the Test pane and ask a question that exercises the tools, for example "What's the highest rated movie with over 10k votes in my IMDb database?". The agent calls the MotherDuck tools and responds with live data from your databases.

   

note

When you authenticate with an API key, all users of the Copilot Studio agent share the same MotherDuck token. Queries run by any end user are attributed to the service account that owns the token, not to the individual Microsoft 365 user. Use OAuth 2.0 if you need per-user attribution.

Copilot Studio MCP documentation

Alternative: Power Automate custom connector (OpenAPI)

If you'd rather wire the MotherDuck MCP server in as a Power Automate custom connector (for example, to share the connector across Copilot Studio and Power Automate flows in the same environment), you can import the following OpenAPI 2.0 spec. The x-ms-agentic-protocol: mcp-streamable-1.0 extension tells Copilot Studio to treat the connector as a streamable MCP server.

swagger: '2.0'
info:
  title: MotherDuck Remote MCP
  description: The remote MCP to connect to MotherDuck tools, docs and more
  version: 1.0.0
host: api.motherduck.com
basePath: /
schemes:
  - https
paths:
  /mcp:
    post:
      summary: MotherDuck Remote MCP
      description: The remote MCP to connect to MotherDuck tools, docs and more
      operationId: InvokeServer
      x-ms-agentic-protocol: mcp-streamable-1.0
      responses:
        '200':
          description: Immediate Response
securityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: Authorization
security:
  - api_key: []

In Power Automate, go to Custom connectors → New custom connector → Import an OpenAPI file, paste the spec above, and save. When you create a connection, enter Bearer <your_motherduck_token> as the API key value — the same format as the native MCP flow described above.

Others

If you're using Windsurf, Zed, or another MCP-compatible client, use the following JSON configuration:

{
  "mcpServers": {
    "MotherDuck": {
      "url": "https://api.motherduck.com/mcp",
      "type": "http"
    }
  }
}

Authentication

The remote MCP server uses OAuth, so you'll authenticate with your MotherDuck account during setup. Some clients also support token-based authentication through a Bearer header.

For example:

{
  "headers": {
    "Authorization": "Bearer <your_motherduck_token>"
  }
}

Configuring tool permissions

Most MCP clients let you control how the AI uses each tool. The exact UI varies by client, but the general permission levels are:

Permission	Behavior
Always allow	The AI uses the tool automatically without asking. Faster iteration when errors occur, but no human confirmation before each action.
Needs approval	The AI asks for your confirmation before each tool use. Gives you visibility into every action.
Blocked	The AI cannot use this tool.

tip

The MCP Server provides both read-only (query) and read-write (query_rw) tools. For exploratory analysis, setting read-only tools to "Always allow" enables faster back-and-forth when the AI needs to retry or refine queries. You can keep query_rw on "Needs approval" or block it if you only need read access. See Restricting to read-only access for more options.

Remote vs local MCP server

MotherDuck offers two MCP server options:

Server	Best for	Setup	Access
Remote (hosted by MotherDuck)	Most users who query and modify data on MotherDuck cloud	Zero setup; connect through URL and OAuth	Read-write
Local (mcp-server-motherduck)	Self-hosted use; local DuckDB files; or when you need full customization	Install and run the server yourself	Fully customizable

The remote server is recommended for most use cases. Use the local server when you need to work with local DuckDB files, want custom tool configurations, or require full control over the server environment.

Local MCP Server GitHub Repository – Self-host the open-source MCP server for DuckDB and MotherDuck

Where to go from here

• AI Data Analysis Getting Started: 5-minute walkthrough of querying data and creating Dives
• MCP Workflows Guide: Best practices for getting accurate results from AI-powered analysis
• MCP Server Reference: Server capabilities, available tools, and regional availability
• Restricting to Read-Only Access: Restrict your AI assistant to read-only queries