# MotherDuck Documentation - Attach modes > Understand Workspace and Single attach modes Generated: 2026-08-25 > MotherDuck is a serverless cloud data warehouse built on DuckDB. It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics. ## Key capabilities - **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses) - **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session - **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language - **Data Sharing**: Share databases and query results with team members and external users - **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI - **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more - **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation ## When to use MotherDuck Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP. ## Agent guidance If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation. For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows. To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question. For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json. ## Account setup for agents If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request. `POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`. Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership. Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup. ## Included documentation Source: https://motherduck.com/docs/key-tasks/authenticating-and-connecting-to-motherduck/attach-modes/attach-modes # Attach Modes > Understand Workspace and Single attach modes ## MotherDuck attach modes: workspace and single modes This guide explains MotherDuck's two connection modes: **workspace** and **single**. Workspace mode is designed for working with multiple databases persistently across sessions, while single mode uses a non-persistent, isolated session that does not reuse your saved workspace. :::tip **TL;DR** Use single mode for service accounts and automated workflows, use workspace mode for personal usage across sessions, for example the MotherDuck UI, your AI agent and the local DuckDB CLI. ::: ### Connection modes MotherDuck offers two connection modes: workspace and single. The mode you use determines how your attachments and detachments are handled and whether these changes are saved for future sessions. Both modes allow you to `ATTACH` databases, the difference is whether those attachments are remembered for your next session. * **Workspace Mode** is the default mode when you want to work with all attached MotherDuck databases. When you attach or detach a database in this mode, that change is remembered for your next session. This is useful when you consistently work with the same set of databases. Parallel connections to MotherDuck in workspace mode will keep their attachments in sync. E.g. detaching a database in one client in workspace mode will detach it in all other clients that are connected in workspace mode. * **Single Mode** is for when you want a one-time, non-persistent session that does not reuse or change your saved workspace. This is useful in automated workflows and minimizes the catalog size. Any databases you attach or detach during this session will not affect the saved workspace for the next time you connect or interfere with attachment state of other parallel connections to MotherDuck. You can still attach multiple databases in a single-mode session, including databases shared with you. For example, you can start with your own database and then `ATTACH 'md:_share/...'` to attach a share. Single mode is useful with BI tools that only support a single attached database at a time. :::tip You can't switch between modes in the middle of a session. The mode is set by the first command you use to connect to MotherDuck. ::: ### Connecting to MotherDuck with a connection string When you first connect to MotherDuck in a session, the connection string you use determines the attach mode. This applies to most of clients, like the DuckDB CLI (`duckdb 'md:...'`) and Python (`duckdb.connect('md:...')`). * **To connect in Workspace Mode (default):** * Use `md:` or `md:`. * This connects to your MotherDuck workspace, attaching *all* databases from your last saved session. * If you specify a database name, it becomes the active database. * Any changes to attachments (attaching or detaching databases) are saved and will be restored in your next workspace session. * **To connect in Single Mode:** * Use `md:?attach_mode=single`. * This connects to the specified database without using your saved workspace. * Attachment changes are *temporary* and will *not* be saved. * Note: You must specify a database name to use single mode. Connecting with `md:?attach_mode=single` is not allowed, as this mode requires a specific database target. ### Connecting to MotherDuck using the ATTACH command If you are already in a DuckDB session, but **not** connected to MotherDuck yet, your first ATTACH command that targets MotherDuck establishes the attach mode for that session. * **To connect in Workspace Mode:** * Use `ATTACH 'md:'`. * This attaches your entire saved workspace. * The session is now in workspace mode, and any subsequent attachment changes will be persisted for future sessions. * **To connect in Single Mode:** * Use `ATTACH 'md:'`. * This attaches the specified database without using your saved workspace. * The session is implicitly set to single mode. Attachment changes are not saved. * Once in single mode, you cannot attach the entire workspace using `ATTACH 'md:'`. ### Tips & tricks Further Notes: * You can also explicitly set the attach mode before connecting to MotherDuck. ```sql LOAD motherduck; SET motherduck_attach_mode = 'workspace'; -- or 'single' ATTACH 'md:foo'; -- database created by your account ``` * The MotherDuck UI always connects in workspace mode. --- ## 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%2Fauthenticating-and-connecting-to-motherduck%2Fattach-modes%2F&page_title=MotherDuck%20Documentation%20-%20Attach%20modes&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.