> ## Documentation Index
> Fetch the complete documentation index at: https://studio.assembly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP (beta)
> Connect AI tools like Claude, ChatGPT, and Cursor to your Assembly workspace using MCP.
## Overview
The **Assembly MCP server** lets you connect AI tools like Claude, ChatGPT, and Cursor to your Assembly workspace. Once connected, your AI assistant can read from and act on your clients, companies, invoices, messages, tasks, forms, files, and more, without leaving your chat.
MCP (Model Context Protocol) is an open standard that serves as a secure bridge between the AI tool you already use and your Assembly data, using your own Assembly login. The server provides tools mapped to the public Assembly Platform API, with the same authentication, permissions, and rate limits.
A few things you can ask your AI once connected:
* **Get briefed on clients prior to calls:** *"Summarize past messages and internal notes from Acme Corp. Get a sense of customer health/sentiment."*
* **Find information fast:** *"Which clients have an overdue invoice older than 30 days?"*
* **Create work in bulk:** *"Send a message to clients in my Gold tier."*
* **Answer and analyze:** *"What are the most common questions we get from our clients?"*
## What the MCP server can do
Once connected, the assistant can read and write across these workspace areas:
* **Clients:** find, create, update, replace, and delete client records.
* **Companies:** find, create, update, and delete companies.
* **Invoices, subscriptions, payments, products, prices:** read everything; create invoices and subscriptions; cancel subscriptions.
* **Contracts:** read contracts and templates; create new contracts from templates.
* **Messages and message channels:** read message history; send new messages; create one-to-one, group, or company channels.
* **Tasks and task comments:** read, create, update, and delete tasks; read and delete task comments; read task templates.
* **Forms:** read forms and existing responses; submit new responses.
* **Files and file channels:** read file metadata; change file permissions; delete files; create file channels.
* **Notes:** read, create, update, and delete notes attached to clients or companies.
* **Notifications:** read notifications; mark them read or unread; create or delete notifications.
* **Workspace metadata:** list the workspaces you belong to, list internal users (teammates), read custom fields and their options, list installed apps, and run a cross-resource search.
The server does not expose billing configuration, user provisioning, role and permission editing, audit log internals, or anything outside the public Platform API surface.
## Before you start
* **You need to be an Assembly admin.** The MCP server acts as you through Assembly's API, which is admin-only. Non-admin teammates won't be able to use it.
* **You need an AI tool that supports MCP.** Claude, ChatGPT, and Cursor are detailed below.
## Connect Claude
You can add Assembly to Claude connectors via any of the following options. Connectors in Claude are available on all paid plans.
### On the website (claude.ai)
1. Go to **Customize > Connectors**.
2. Click [**Add custom connector**](https://claude.ai/customize/connectors?modal=add-custom-connector).
3. Enter the MCP URL:
`https://mcp.assembly.com`
4. Click **Connect** and sign in to Assembly when prompted.
5. Test the connection by starting a new chat and asking Claude something about your workspace, for example: *"What apps do I have installed in my Assembly workspace?"* or *"Who are my team members in my Assembly workspace?"*
### On Claude Desktop
1. Open Claude Desktop and go to **Customize → Connectors**.
2. Click **Add connector**, choose **Custom**, and paste `https://mcp.assembly.com`.
3. Sign in to Assembly in the browser window that opens.
4. The Assembly tools will appear in your tool menu the next time you start a chat.
### On Claude Code
If you use Claude Code in your terminal, run:
`claude mcp add --transport http assembly https://mcp.assembly.com`
You'll be sent through a browser sign-in to authorize access. After that, Assembly tools are available in every Claude Code session.
## Connect ChatGPT
Apps like Assembly are available on ChatGPT Plus, Pro, and Business plans.
### Add Assembly to ChatGPT
1. In ChatGPT, go to **Settings → Apps → Advanced Settings** and enable Developer mode. You must be on Plus or higher to see this setting.
2. After enabling, you will see the option to **Create** an app.
3. Set the **name** to `Assembly`
4. Set the **MCP server URL** to `https://mcp.assembly.com`
5. Set the authentication method to OAuth. You will be redirected to log in with Assembly.
6. Accept the checkbox and click **Create**. The app will appear as a Draft in your Apps settings.
7. **For admins/owners on Business plans:** Go to **Workspace Settings → Apps → Drafts**, select the Assembly app, and click **Publish**.
### Use Assembly in ChatGPT
1. Start a new chat.
2. Open the tools menu (the **+** button) and select Assembly from the "More" dropdown.
3. Try a simple prompt to test, e.g. *"What apps do I have installed in my Assembly workspace?"* or *"Who are my team members in my Assembly workspace?"*
## Connect Cursor
**Option 1:** [Use the install deeplink.](cursor://anysphere.cursor-deeplink/mcp/install?name=Assembly\&config=eyJ1cmwiOiJodHRwczovL21jcC5hc3NlbWJseS5jb20ifQ==)
**Option 2:**
1. In Cursor, open **Settings → Cursor Settings → MCP**.
2. Click **Add new MCP server** and choose the **HTTP** transport.
3. Name the server `assembly`
4. Set the URL to `https://mcp.assembly.com`
5. Save and sign in to Assembly when Cursor prompts you.
## Disconnecting MCP
To revoke access, remove the Assembly connector in your AI tool's settings. The AI loses access immediately.
* **In Assembly:** **Settings → Account → Connected apps → Revoke.**
* **In ChatGPT:** **Apps → select Assembly → Disconnect → Delete.**
* **In Claude:** **Connectors → select Assembly → Disconnect → Delete.**
## Authentication and permissions
### How you connect
1. The MCP client (ChatGPT, Claude, etc.) opens the OAuth authorization URL on `https://mcp.assembly.com`.
2. You are redirected to Assembly's branded login page and sign in with **email and password**, **Google SSO**, or **TOTP-based MFA** if enabled on your account.
3. After you consent, an access token (about 1 hour) and a long-lived refresh token are issued. The MCP client stores them; Assembly stores only the encrypted refresh token server-side.
An access token auto-refreshes via the MCP client when it expires. The refresh token is long-lived and is revoked by your action (see [Disconnecting MCP](#disconnecting-mcp)). A connection that is created but never used is cleaned up after about 48 hours.
### Who can connect
* Connections require an **Assembly internal admin** login. Client-portal end users (the customers your workspace serves) and Staff-role internal users **cannot** connect to the MCP server.
* Your existing in-product permissions apply: the assistant can only see and modify what you could see and modify through the dashboard or Platform API.
### What data the AI can access
* Tools are filtered per workspace by enabled **modules**. If a workspace hasn't enabled the Payments, Contracts, Files, Forms, Messages, or Tasks modules, the corresponding tools are not registered and not visible to the assistant.
* If you belong to a single workspace, it is resolved automatically. If you belong to multiple, the assistant passes the workspace on each call (`list_workspaces` returns the full list).
## Tool safety
Every tool carries a safety hint derived from its underlying HTTP method: read-only actions (GET) are safe to call without confirmation, write actions (POST/PUT/PATCH) create or modify data, and delete actions are destructive. All workspace-data operations are scoped to your workspace.
### Read-only (safe to call without confirmation)
| Tool | Actions |
| ------------------------ | --------------------------------------------- |
| `assembly_overview` | reference (returns Assembly product glossary) |
| `dashboard_links` | reference (returns dashboard URL patterns) |
| `list_workspaces` | list |
| `workspaces` | retrieve |
| `internal_users` | list, retrieve |
| `custom_fields` | list, list\_options |
| `search` | search |
| `forms` | list, list\_responses, retrieve |
| `task_templates` | list, retrieve |
| `contract_templates` | list, retrieve |
| `invoice_templates` | list |
| `subscription_templates` | list |
| `products` | list, retrieve |
| `prices` | list, retrieve |
| `payments` | list |
### Write (creates or modifies; confirm before calling)
| Tool | Actions | Notes |
| ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------- |
| `invoices` | create, list, retrieve | Created invoices are drafts unless otherwise specified. |
| `subscriptions` | create, list, retrieve, cancel | `cancel` is a non-destructive POST; the subscription record is preserved. |
| `contracts` | create, list, retrieve | |
| `form_responses` | create | |
| `messages` | create, list | Sends a message visible to the channel's members. |
| `message_channels` | create, list, retrieve | |
| `file_channels` | create, list, retrieve | |
| `installs` | list, retrieve, list\_connections, create\_connection | `create_connection` wires a marketplace app credential. |
Create actions may trigger client notifications (via email and in-product) that cannot be reversed through the MCP. Admins should review whether clients receive notifications in their [client notification settings](https://dashboard.assembly.com/settings/client-notifications) before taking these actions.
### Destructive (irreversible; require explicit confirmation)
| Tool | Destructive actions | Recovery |
| --------------- | ------------------- | ---------------------------------------------------------- |
| `clients` | `delete` | Not recoverable from within Assembly. |
| `companies` | `delete` | Not recoverable from within Assembly. |
| `files` | `delete` | Not recoverable from within Assembly. |
| `tasks` | `delete` | Not recoverable from within Assembly. |
| `task_comments` | `delete` | Not recoverable from within Assembly. |
| `notes` | `delete` | Not recoverable from within Assembly. |
| `notifications` | `delete` | Not recoverable; affects the in-product notification feed. |
Assembly does not maintain a soft-delete or trash for the resources above. A successful `delete` removes the record permanently.
## Privacy and data handling
See our full [AI policy](https://assembly.com/legal/ai-policy) and [Privacy policy](https://assembly.com/legal/privacy-policy) for details.
**Data categories returned by tools:**
* Workspace metadata (workspace name, branding, custom fields).
* Client and company records (name, email, address, custom-field values).
* Message content and channel membership.
* File metadata and, on explicit request, signed download URLs or file bytes.
* Form definitions and submitted responses.
* Financial records: invoices, subscriptions, payments, products, prices.
* Task content, task comments, and notes.
* Notification feed entries for the connected user.
* Internal teammate directory (name, email, role).
**What tools do not return:**
* Identity-provider secrets, refresh tokens, or encryption keys.
* Internal partition or sort keys, audit-log internals, or AWS request IDs.
* Database row versions, soft-delete tombstones, or other internal bookkeeping fields.
* API keys, webhook signing secrets, or any credential material.
* Logs, stack traces, or debug payloads on error. Errors are surfaced as the Platform API's standard JSON error envelope (status code plus a human-readable message), nothing more.
Resource IDs returned to the assistant are the **public Platform API IDs** documented in the [Platform API reference](https://docs.assembly.com/reference), the same IDs a third-party integration would see. No internal-only identifiers are exposed. OAuth refresh tokens are stored encrypted at rest, and access tokens are never logged or echoed back through tool responses.
## Example prompts
| Type | Example prompt |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Simple actions | "Create a task assigned to myself called 'Quarterly review'. Include a summary of what we just talked about in the description."
"Create an invoice for John Doe for marketing services, \$5,000 total, due in 30 days." |
| Bulk actions | "Send a message to all clients who have the tier custom field set to 'Advanced'."
"Create a task 'Upload tax documents' for all clients who have plan custom field set to 'Starter'." |
| Analysis | "How responsive has my team been in replying to clients this past month?"
"What are the most common pain points we've heard from clients this past week?" |
| Search | "Can you figure out which clients I talked to about 'Form 941-X'?" |
### How the assistant handles different requests
* **Read-only lookup:** *"List clients with overdue invoices."* The assistant calls the invoice and client tools and returns the results as a table.
* **No results:** if nothing matches, it says so and stops. It won't invent client or record IDs.
* **Single write:** *"Send my contract template to \[client]."* It confirms the client, then creates the contract.
* **Bulk action:** *"Draft a payment reminder for each client with an overdue invoice and show me before sending."* It drafts one message per client with explicit Send and Cancel controls. Nothing is written until you approve.
* **Destructive with confirmation:** *"Delete the client \[name]."* It restates the client's name and email, warns that the deletion is not recoverable, and waits for explicit confirmation before deleting.
* **Brief and analyze:** *"Brief me on Acme Corp."* It searches across messages, notes, invoices, contracts, tasks, and files, then summarizes account health, outstanding payments, key relationships, and recommended follow-ups.
* **Out of scope:** *"Schedule a call at 4pm."* It declines (it has no calendar or scheduling access) and may suggest sending a scheduling link through a message instead.
* **Error case:** *"Show the invoice with ID inv\_invalid."* It reports that no invoice with that ID exists, does not retry, and does not surface raw error payloads.
## Known limits
*Last updated June 16, 2026.*
* **Pagination.** Analyzing more than 25 clients at a time can produce incomplete results.
* **File upload.** As of April 2026, the Platform API doesn't support file upload because ChatGPT and Claude web/mobile restrict outbound network access to an allowlist of domains, and `s3.amazonaws.com` is not included. Claude Code does allow file upload. We are working on a solution.
* **No per-tool scopes yet.** Today the connection inherits your full workspace permissions; there is no way to grant the assistant read-only or domain-scoped access.
* **Rate limits** inherit the public Platform API; sustained bulk loops will eventually return a 429.
* **Some resources have no create action.** New contract templates, invoice templates, subscription templates, task templates, custom fields, products, and prices must be created in the Assembly Dashboard first before the MCP can use them.
* **Workspace selection.** Multi-workspace users must specify the workspace in the prompt, or rely on the assistant calling `list_workspaces` first.
## Frequently asked questions
The AI can see any data available in the [Platform API](https://docs.assembly.com/reference/getting-started-introduction) for any workspace where you have admin-level access. See [What the MCP server can do](#what-the-mcp-server-can-do) and [Privacy and data handling](#privacy-and-data-handling) for coverage, and our [AI policy](https://assembly.com/legal/ai-policy) for how we approach data handling.
Yes. It can create and update clients, tasks, invoices, messages, and more when you ask it to. We recommend reviewing all actions before confirming; most AI tools show you the request before sending. See the [Tool safety](#tool-safety) section for the full list of write actions.
Yes, for the following items if you give it permission: clients, companies, tasks and task comments, files, internal notes, and notifications.
Deleting any of these items is non-recoverable. Exercise caution and do not allow blanket deletions from your AI tools.
Not today. The MCP server uses Assembly's admin-only API, so only admins can use it. Staff-role internal users and client-portal end users cannot connect.
Data handling with the MCP is governed by the AI tool you connect. Refer to our [AI policy](https://assembly.com/legal/ai-policy) section on MCP connections and check your AI tool's plan and privacy policies for specifics.
If your account belongs to more than one workspace, the AI will ask which workspace to use each time it makes a request. Answer in chat, for example, "Use the Acme Agency workspace," and it will carry that choice through the rest of the conversation.
No. MCP is an internal tool for your team only. Clients don't see it.
Try disconnecting and reconnecting the Assembly connector in your AI tool, or try restarting your tool after installing the Assembly MCP. Make sure you select or mention the app "Assembly" by name.