# Connect to the MotherDuck MCP Server > Connect to MotherDuck with the official ChatGPT and Codex plugin, or set up the MCP server in Claude, Cursor, and other AI assistants. 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. ::: :::tip[Coding agent with a terminal?] MCP is the right tool for exploring data and answering questions in a chat client. For agents that have a shell and a filesystem, the [MotherDuck CLI](/getting-started/interfaces/motherduck-cli/agents/) is more efficient for file-shaped work: reading a Dive or Flight, saving an edit, listing Dives and Flights, and exporting large results, because the output goes to disk instead of through the model's context. See [choosing between the CLI and MCP](/getting-started/interfaces/motherduck-cli/agents/#choosing-between-the-cli-and-mcp). The two work well together. ::: ## Prerequisites - A MotherDuck account ([sign up free](https://app.motherduck.com/)) - An MCP-compatible AI client (Claude, ChatGPT, Cursor, Claude Code, Codex, or others) ## Connect with the official MotherDuck plugin The official [MotherDuck plugin](https://chatgpt.com/plugins/plugin_asdk_app_696a54f1c91c81919002b9153ce0e336) connects ChatGPT and Codex to MotherDuck so you can explore schemas, run queries, and create Dives. It configures the hosted MCP connection for you. 1. Open **Plugins** in ChatGPT on the web or in the desktop app. 2. Search for **MotherDuck**, open its details, and select **+** to install it. 3. Connect your MotherDuck account when prompted. 4. Start a new ChatGPT or Codex chat. Type `@` and select **MotherDuck**, then ask "List all my databases on MotherDuck." Confirm that the assistant calls a MotherDuck tool and returns your databases. If installation is unavailable, check your workspace's plugin settings with your administrator. See [OpenAI's plugin guide](https://learn.chatgpt.com/docs/plugins) for supported surfaces and access requirements. To connect through ChatGPT's app settings, use the **ChatGPT** tab below. ## Set up the remote MCP server Select your MCP client and follow the instructions to connect. ### Claude [Add MotherDuck to Claude](https://claude.ai/directory/motherduck) 1. Open Claude on the web or in Claude Desktop 2. Go to **Customize** → **Connectors** and click **+** to browse the directory 3. Find **MotherDuck**, open its details, and click **Connect** 4. Complete the MotherDuck authorization when prompted After authentication, ask "List all my databases on MotherDuck" to verify the connection. If Claude doesn't use MotherDuck, open **+** → **Connectors** in the chat and enable it for that conversation. On Claude Team and Enterprise plans, an organization owner must enable the connector before members can connect. See [Claude's connector guide](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities) for organization setup. ### ChatGPT [Add MotherDuck to ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_696a54f1c91c81919002b9153ce0e336) 1. Open the ChatGPT desktop or web app 2. Go to **Settings** → **Apps** and click **Browse Apps** ![Browse Apps in ChatGPT settings](useBaseUrl('/img/key-tasks/ai-and-motherduck/chatgpt-browse-apps.png')) 3. Search for **MotherDuck** and select it ![Searching for MotherDuck in the ChatGPT App Store](useBaseUrl('/img/key-tasks/ai-and-motherduck/chatgpt-search-motherduck.png')) 4. Click **Continue to MotherDuck** and authenticate with your MotherDuck account ![Connect MotherDuck dialog in ChatGPT](useBaseUrl('/img/key-tasks/ai-and-motherduck/chatgpt-connect-motherduck.png')) 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](cursor://anysphere.cursor-deeplink/mcp/install?name=motherduck&config=eyJ1cmwiOiJodHRwczovL2FwaS5tb3RoZXJkdWNrLmNvbS9tY3AifQ%3D%3D) 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) ### Claude Code If you've connected MotherDuck in Claude and use a Claude account to sign in to Claude Code, run `/mcp` first. If MotherDuck is listed and connected, you can use it without adding another server. API-key and third-party provider sessions don't inherit these connectors; see [Claude account connectors in Claude Code](https://code.claude.com/docs/en/mcp#use-mcp-servers-from-claudeai) for details. To configure the server directly: 1. From your project directory, run the following command in your terminal: ```bash claude mcp add --transport http MotherDuck https://api.motherduck.com/mcp ``` :::tip The command uses Claude Code's local scope by default: only you can use the server, and only in the current project. To make it available to you across projects, use this command instead: ```bash claude mcp add --transport http --scope user MotherDuck https://api.motherduck.com/mcp ``` See the [`--scope` documentation](https://code.claude.com/docs/en/mcp#mcp-installation-scopes) for project and user scope details. ::: 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 Ask "List all my databases on MotherDuck" and confirm that Claude calls a MotherDuck tool and returns your databases. > [Claude Code MCP Documentation](https://code.claude.com/docs/en/mcp) ### GitHub Copilot (VS Code) [Add MotherDuck to VS Code](vscode:mcp/install?%7B%22name%22%3A%22MotherDuck%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.motherduck.com%2Fmcp%22%7D) The button opens an **MCP Server: MotherDuck** tab with the server prefilled; nothing is added until you click **Install**. On VS Code Insiders, use the [Insiders link](vscode-insiders:mcp/install?%7B%22name%22%3A%22MotherDuck%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.motherduck.com%2Fmcp%22%7D) instead. Or configure GitHub Copilot in VS Code 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) ### 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**. ![Copilot Studio agent Tools tab with Add a tool button](/img/key-tasks/ai-and-motherduck/copilot-studio/01-add-tool.png) 2. In the **Add tool** dialog, under **Create new**, click **Model Context Protocol**. ![Add tool dialog with Model Context Protocol highlighted under Create new](/img/key-tasks/ai-and-motherduck/copilot-studio/02-mcp-option.png) 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**. ![MCP server configuration with OAuth 2.0 Dynamic discovery selected](/img/key-tasks/ai-and-motherduck/copilot-studio/03a-oauth-auth.png) **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**. ![MCP server configuration with API key authentication, Header type, and Authorization header name](/img/key-tasks/ai-and-motherduck/copilot-studio/03b-api-key-auth.png) :::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**. ![Connection dropdown showing Create new connection option](/img/key-tasks/ai-and-motherduck/copilot-studio/04-create-connection.png) 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 ``` Replace `` with an actual token from [MotherDuck → Settings → Access Tokens](https://app.motherduck.com/settings/tokens), then click **Create**. ![Connect to MotherDuck MCP dialog with the Bearer token entered](/img/key-tasks/ai-and-motherduck/copilot-studio/05-bearer-token.png) :::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**. ![MotherDuck MCP tool list with toggles for query, query_rw, list_databases, list_tables, list_columns, search_catalog, ask_docs_question, and others](/img/key-tasks/ai-and-motherduck/copilot-studio/07-tools-list.png) 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. ![Copilot Studio test pane showing the agent calling the query tool and returning IMDb results from MotherDuck](/img/key-tasks/ai-and-motherduck/copilot-studio/09-test-agent.png) :::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)
Alternative: Power Automate custom connector (OpenAPI) 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 ` 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: ```json { "mcpServers": { "MotherDuck": { "url": "https://api.motherduck.com/mcp", "type": "http" } } } ``` :::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. For example: ```json { "headers": { "Authorization": "Bearer " } } ``` ::: ## Offer an MCP connection under your own brand If your customers should sign in to your product and access data through tenant service accounts, build a wrapper around the managed remote server. You can select tools, supply business and style guidance, capture question context, and return dashboards in your application. See [White-label the MotherDuck MCP server](/key-tasks/ai-and-motherduck/mcp-workflows/white-label-mcp-server/) for the architecture and implementation considerations. ## 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. [**Local MCP Server GitHub Repository** – Self-host the open-source MCP server for DuckDB and MotherDuck](https://github.com/motherduckdb/mcp-server-motherduck) ## 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 - **[Work with agents through the CLI](/getting-started/interfaces/motherduck-cli/agents/)**: When to reach for the MotherDuck CLI instead of MCP, and why it costs fewer tokens --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fai-and-motherduck%2Fmcp-setup%2F&page_title=Connect%20to%20the%20MotherDuck%20MCP%20Server&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.