> ## Documentation Index
> Fetch the complete documentation index at: https://assembly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect AI tools like Claude, ChatGPT, Cursor, and Perplexity to your Assembly workspace using MCP.
## Overview
The **Assembly MCP server** lets you connect AI tools like Claude, ChatGPT, Cursor, and Perplexity 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; send client invites.
* **Companies:** find, create, update, and delete companies.
* **Invoices, subscriptions, payments, products, prices:** read everything; create invoices, subscriptions, products, and prices; cancel subscriptions.
* **Contracts:** read contracts and templates; create new contracts from templates.
* **Messages and message channels:** read message history and unread counts; 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; create new forms; submit new responses.
* **Files and file channels:** read file metadata, upload and download files, change file and folder permissions, delete files, and 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.
* **Custom fields:** read custom fields and their options; create new custom fields.
* **Audit log:** read a workspace's activity events (who did what and when), filterable by date, event type, and actor.
* **Workspace metadata:** list the workspaces you belong to, list and update internal users (teammates), list installed apps, and run a cross-resource search.
The server does not expose billing configuration, workspace provisioning, role and permission editing, 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, Cursor, and Perplexity 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.
## Connect Perplexity
1. Open the right settings page:
* **For your account:** **Account settings → [Connectors](https://www.perplexity.ai/account/connectors)**
* **For your organization (admins only):** **Enterprise settings → [Permissions](https://www.perplexity.ai/account/org/permissions) → Connectors permissions**
2. Click **+ Custom connector** in the top-right corner, then select **Remote** in the modal.
3. Name the server `assembly`
4. Set the URL to `https://mcp.assembly.com`
5. Check the acknowledgement box to confirm you understand the risks of custom connectors.
6. Click **Add**. The connector appears in the **Connectors** screen in your account settings.
7. Click the connector card to start the authentication flow and enable it.
To modify or remove the connector later, click the ellipsis (⋮) on its card and choose the appropriate option.
## 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).
### Request intent logging
Each tool call carries a short **rationale** — a one-sentence description of what you are trying to accomplish, generated by the assistant. Assembly logs the rationale alongside the tool name and workspace for product analytics and abuse monitoring. It is derived from your request; no additional data is collected. Access tokens and refresh tokens are never logged.
## 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 |
| `search` | search (across \~20 entity types; supports paging) |
| `events` | list (audit log; filter by date, event type, actor) |
| `task_templates` | list, retrieve |
| `contract_templates` | list, retrieve |
| `invoice_templates` | list |
| `subscription_templates` | list |
| `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 | |
| `products` | create, list, retrieve | |
| `prices` | create, list, retrieve | |
| `custom_fields` | create, list, list\_options | |
| `forms` | create, list, list\_responses, retrieve | |
| `form_responses` | create | |
| `messages` | create, list | Sends a message visible to the channel's members. |
| `message_channels` | create, list, retrieve, unread | `unread` returns unread counts. |
| `file_channels` | create, list, retrieve | |
| `internal_users` | list, retrieve, update | `update` changes a teammate's company access. |
| `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 | Actions | Recovery |
| --------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `clients` | create, update, replace, list, retrieve, `delete` | `delete` is not recoverable from within Assembly. |
| `companies` | create, update, list, retrieve, `delete` | `delete` is not recoverable from within Assembly. |
| `files` | create (upload), download, download\_url, set\_permissions, list, retrieve, `delete` | `delete` is not recoverable from within Assembly. |
| `tasks` | create, update, list, retrieve, `delete` | `delete` is not recoverable from within Assembly. |
| `task_comments` | list, retrieve, `delete` | `delete` is not recoverable from within Assembly. |
| `notes` | create, update, list, retrieve, `delete` | `delete` is not recoverable from within Assembly. |
| `notifications` | create, list, mark\_read, mark\_unread, `delete` | `delete` is 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).
* Audit-log events for the workspace (actor, action, timestamp).
**What tools do not return:**
* Identity-provider secrets, refresh tokens, or encryption keys.
* Internal partition or sort keys, low-level audit-log bookkeeping, 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/api-reference/introduction), 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'?" |
| Audit | "Show me everything that changed on the Acme Corp account in the last week and who did it." |
### 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 July 17, 2026.*
* **Pagination.** List actions support cursor pagination (`nextToken`); the assistant pages through until it has the full set before answering aggregate questions. Default page size is 25 items (50 for audit events). Very large sweeps can still be slow or hit rate limits.
* **File upload.** Uploading and downloading files is supported via a two-step presigned S3 flow. Sandboxed web and mobile clients (ChatGPT and Claude on web/mobile) restrict outbound network access to an allowlist of domains; if `s3.amazonaws.com` is not on that allowlist, the presigned transfer will fail in those clients. Claude Code and other unrestricted clients can upload and download without this limitation.
* **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.
* **Templates are dashboard-created.** New contract templates, invoice templates, subscription templates, and task templates must be created in the Assembly Dashboard first before the MCP can use them. Custom fields, products, and prices can now be created directly through the MCP.
* **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/api-reference/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, forms, products, prices, 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.