# Assembly's Model Context Protocol (MCP)

The MCP server lets AI assistants like ChatGPT and Claude take action inside an Assembly workspace on behalf of a signed-in workspace admin. It exposes a curated set of tools that map directly to the public [Assembly Platform API](https://docs.assembly.com/reference) — so the same operations available to an API integration are available to an AI assistant, with the same authentication, the same permissions, and the same rate limits.

## 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), read custom fields and their options, 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.

## 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." <br> "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'." <br> "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?" <br> "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." |

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

### 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) |
| `internal_users` | list, retrieve |
| `forms` | list, list_responses, retrieve |
| `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. |

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

## Privacy and data handling

See our full [AI policy](/content/legal/ai-policy/index.html) and [privacy policy](/content/legal/privacy-policy/index.html) 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.

### 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.
- **File upload.** Uploading and downloading files is supported via a two-step presigned S3 flow. Sandboxed web and mobile clients restrict outbound network access to an allowlist of domains.
- **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 can only be created in the dashboard.** New contract templates, invoice templates, subscription templates, and task templates 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.