---
sidebar_position: 0
title: Connect to the MotherDuck MCP Server
sidebar_label: Connect to MCP Server
description: Set up the MotherDuck MCP Server with Claude, ChatGPT, Cursor, Claude Code, and other AI assistants
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import ClaudeIcon from '../../../static/img/icons/brands/claude-icon';
import ChatGPTIcon from '../../../static/img/icons/brands/chatgpt-icon';
import CursorIcon from '../../../static/img/icons/brands/cursor-icon';
import ExternalLinkIcon from '../../../static/img/icons/external-link-icon';
import VideoPlayer from '@site/src/components/VideoPlayer';
import useBaseUrl from '@docusaurus/useBaseUrl';
import DocImage from '@site/src/components/DocImage';
import SignUpLink from '@site/src/components/SignUpLink';

The MotherDuck MCP Server lets AI assistants query and explore your databases using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). 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](#remote-vs-local-mcp-server).

:::info 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](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck#creating-an-access-token) instead of OAuth.
:::

## Prerequisites

- A MotherDuck account (<SignUpLink>sign up free</SignUpLink>)
- 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.

<Tabs groupId="mcp-client">
  <TabItem value="claude" label="Claude" default>

<a href="https://claude.ai/directory/0929a5c7-38ce-40ab-8aad-af9ce34553c7" target="_blank" rel="noopener noreferrer" style={{display: 'inline-flex', alignItems: 'center', gap: '8px', padding: '8px 14px', background: 'var(--ifm-background-color)', border: '1px solid var(--ifm-color-emphasis-300)', borderRadius: '4px', color: 'var(--ifm-font-color-base)', fontSize: '14px', fontWeight: 500, textDecoration: 'none', marginBottom: '16px'}}>
  <ClaudeIcon />
  <span>Add MotherDuck to Claude</span>
  <ExternalLinkIcon />
</a>

Or manually:

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

![MotherDuck Connector in the Claude connector Directory](./img/claude-connectors-motherduck.png)

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

  </TabItem>
  <TabItem value="chatgpt" label="ChatGPT">

<a href="https://chatgpt.com/apps/motherduck/asdk_app_696a54f1c91c81919002b9153ce0e336" target="_blank" rel="noopener noreferrer" style={{display: 'inline-flex', alignItems: 'center', gap: '8px', padding: '8px 14px', background: 'var(--ifm-background-color)', border: '1px solid var(--ifm-color-emphasis-300)', borderRadius: '4px', color: 'var(--ifm-font-color-base)', fontSize: '14px', fontWeight: 500, textDecoration: 'none', marginBottom: '16px'}}>
  <ChatGPTIcon />
  <span>Add MotherDuck to ChatGPT</span>
  <ExternalLinkIcon />
</a>

<VideoPlayer
  playbackId="GU41jMZ01O01uWGaukLbqj1Ee14tnHq800AV6OGWpvQbcE"
  title="Setting up MotherDuck in ChatGPT"
  autoPlay="true"
  muted="true"
  loop="true"
/>

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

<img src={useBaseUrl('/img/key-tasks/ai-and-motherduck/chatgpt-browse-apps.png')} alt="Browse Apps in ChatGPT settings" style={{maxWidth: '500px', width: '100%', display: 'block', margin: '0 auto'}} />

3. Search for **MotherDuck** and select it

<img src={useBaseUrl('/img/key-tasks/ai-and-motherduck/chatgpt-search-motherduck.png')} alt="Searching for MotherDuck in the ChatGPT App Store" style={{maxWidth: '500px', width: '100%', display: 'block', margin: '0 auto'}} />

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

<img src={useBaseUrl('/img/key-tasks/ai-and-motherduck/chatgpt-connect-motherduck.png')} alt="Connect MotherDuck dialog in ChatGPT" style={{maxWidth: '500px', width: '100%', display: 'block', margin: '0 auto'}} />

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

  </TabItem>
  <TabItem value="cursor" label="Cursor">
<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=motherduck&config=eyJ1cmwiOiJodHRwczovL2FwaS5tb3RoZXJkdWNrLmNvbS9tY3AifQ%3D%3D" target="_blank" rel="noopener noreferrer" style={{display: 'inline-flex', alignItems: 'center', gap: '8px', padding: '8px 14px', background: 'var(--ifm-background-color)', border: '1px solid var(--ifm-color-emphasis-300)', borderRadius: '4px', color: 'var(--ifm-font-color-base)', fontSize: '14px', fontWeight: 500, textDecoration: 'none', marginBottom: '16px'}}>
  <CursorIcon />
  <span>Add MotherDuck to Cursor</span>
  <ExternalLinkIcon />
</a>

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

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

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

> [Cursor MCP Documentation](https://docs.cursor.com/context/model-context-protocol)

  </TabItem>
  <TabItem value="claude-code" label="Claude Code">

1. Run the following command in your terminal:

```bash
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](https://code.claude.com/docs/en/mcp#mcp-installation-scopes)).
:::

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](https://code.claude.com/docs/en/mcp)

  </TabItem>
  <TabItem value="github-copilot" label="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:

```json
{
  "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](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck#creating-an-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:

```json
{
  "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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)

  </TabItem>
  <TabItem value="copilot-studio" label="Copilot Studio">

[Microsoft Copilot Studio](https://learn.microsoft.com/en-us/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**.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/01-add-tool.png"
     alt="Copilot Studio agent Tools tab with Add a tool button"
     width={700}
   />

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

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/02-mcp-option.png"
     alt="Add tool dialog with Model Context Protocol highlighted under Create new"
     width={700}
   />

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**.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/03a-oauth-auth.png"
     alt="MCP server configuration with OAuth 2.0 Dynamic discovery selected"
     width={500}
   />

   **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**.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/03b-api-key-auth.png"
     alt="MCP server configuration with API key authentication, Header type, and Authorization header name"
     width={500}
   />

   :::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**.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/04-create-connection.png"
     alt="Connection dropdown showing Create new connection option"
     width={700}
   />

   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 `:

   ```text
   Bearer <your_motherduck_token>
   ```

   Replace `<your_motherduck_token>` with an actual token from [MotherDuck → Settings → Access Tokens](https://app.motherduck.com/settings/tokens), then click **Create**.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/05-bearer-token.png"
     alt="Connect to MotherDuck MCP dialog with the Bearer token entered"
     width={700}
   />

   :::tip
   If the agent is published and used by many end users, create a dedicated [service account](/key-tasks/service-accounts-guide/) and use a [read scaling token](/key-tasks/authenticating-and-connecting-to-motherduck/read-scaling/) so the agent can't modify data. See [Restricting to read-only access](/key-tasks/ai-and-motherduck/securing-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**.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/07-tools-list.png"
     alt="MotherDuck MCP tool list with toggles for query, query_rw, list_databases, list_tables, list_columns, search_catalog, ask_docs_question, and others"
     width={700}
   />

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.

   <DocImage
     src="/img/key-tasks/ai-and-motherduck/copilot-studio/09-test-agent.png"
     alt="Copilot Studio test pane showing the agent calling the query tool and returning IMDB results from MotherDuck"
     width={900}
   />

:::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](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent)

<details>
<summary>Alternative: Power Automate custom connector (OpenAPI)</summary>

If you'd rather wire the MotherDuck MCP server in as a [Power Automate custom connector](https://learn.microsoft.com/en-us/connectors/custom-connectors/) (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.

```yaml
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.

</details>

  </TabItem>
  <TabItem value="others" label="Others">

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

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

  </TabItem>
</Tabs>

:::tip Authentication
The remote MCP server uses OAuth, so you'll authenticate with your MotherDuck account during setup. Some clients also support [token-based authentication](/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck#creating-an-access-token) through a Bearer header.
:::

## 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](/key-tasks/ai-and-motherduck/securing-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](https://github.com/motherduckdb/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.

<a href="https://github.com/motherduckdb/mcp-server-motherduck" target="_blank" rel="noopener noreferrer" className="github-repo-link">
  **Local MCP Server GitHub Repository** – Self-host the open-source MCP server for DuckDB and MotherDuck
</a>

## Where to go from here

- **[AI Data Analysis Getting Started](/getting-started/mcp-getting-started/)**: 5-minute walkthrough of querying data and creating Dives
- **[MCP Workflows Guide](/key-tasks/ai-and-motherduck/mcp-workflows/)**: Best practices for getting accurate results from AI-powered analysis
- **[MCP Server Reference](/sql-reference/mcp/)**: Server capabilities, available tools, and regional availability
- **[Restricting to Read-Only Access](/key-tasks/ai-and-motherduck/securing-read-only-access/)**: Restrict your AI assistant to read-only queries


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

Payload:

```json
{
  "page_path": "/key-tasks/ai-and-motherduck/mcp-setup/",
  "page_title": "Connect to the MotherDuck MCP Server",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed payloads, and `429` when rate-limited.