Assembly MCP Server (beta)

Assembly's Model Context Protocol (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 — 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 (Beta)

Once connected, the assistant can read and (where the API supports it) write across these areas of an Assembly workspace:

• 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 the user belongs 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/permission editing, audit log internals, or anything outside the public Platform API surface.

Tool safety matrix

Every tool is annotated with MCP safety hints (readOnlyHint, destructiveHint, openWorldHint). These annotations are derived from the underlying HTTP method at registration time, not hand-written, so they cannot drift from actual behavior:

• All actions are GET-only ⇒ readOnlyHint: true.
• Any action uses DELETE ⇒ destructiveHint: true.
• Has POST/PUT/PATCH but no DELETE ⇒ write tool, not destructive.
• openWorldHint: false for every workspace-data tool (operations are scoped to the connected workspace, not an open-ended internet surface).

Read-only (safe to call without confirmation)

Write (creates or modifies; confirm before calling)

Note: Create actions may trigger client notifications (via email and in-product) that cannot be reversed via Assembly’s MCP. Admin users should adjust whether clients receive notifications in their client notification settings prior to taking these actions.

Destructive (irreversible; require explicit user confirmation)

Note: Assembly does not maintain a soft-delete / trash for the resources above — a successful delete removes the record permanently.

Authentication & permissions

How a user connects

For more detailed install instructions, use the MCP Guide.

1. The MCP client (ChatGPT, Claude, etc.) opens the OAuth authorization URL on https://mcp.assembly.com.
2. The user is redirected to Assembly's branded login page (/mcp/login) and signs in with email + password, Google SSO, or TOTP-based MFA if enabled on their account.
3. After consent, an access token (~1 hour) and a long-lived refresh token are issued. The MCP client stores them; Assembly stores only the encrypted refresh token server-side.

Who can connect

• Connections require an Assembly internal Admin user login. Client-portal end-users (the customers an admin's workspace serves) and Staff role internal users cannot connect their accounts to the MCP server.
• The connecting user's existing in-product permissions apply: the AI assistant can only see and modify what the human 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 has not enabled the Payments, Contracts, Files, Forms, Messages, or Tasks modules, the corresponding tool families are not registered and not visible to the assistant.
• If the user belongs to a single workspace, it is auto-resolved. If they belong to multiple, the assistant must pass workspaceId on each call (list_workspaces returns the full list).

Token lifecycle

• Access token: ~1 hour, then auto-refreshed by the MCP client.
• Refresh token: long-lived; revoked by user action (see below).
• An MCP connection that is created but never used is cleaned up after ~48 hours.

How to disconnect or revoke access

In Assembly: Settings → Account → scroll to connected Connected apps → Revoke.

In the ChatGPT: Apps → select Assembly → Disconnect → Delete

In Claude: Connectors → select Assembly → Disconnect → Delete

Privacy & data handling

See full AI Policy and 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 / file bytes.
• Form definitions and submitted responses.
• Financial records: invoices, subscriptions, payments, products, prices.
• Task content, task comments, notes.
• Notification feed entries for the connected user.
• Internal teammate directory (name, email, role).

What tools do not return:

• Raw Cognito subjects, refresh tokens, encryption keys, or any other identity-provider secrets.
• Internal partition / 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 + human-readable message), nothing more.

Resource IDs returned to the assistant are the public Platform API IDs are documented at https://docs.assembly.com/reference — the same IDs a third-party API integration would see. No internal-only identifiers are exposed.

OAuth refresh tokens are stored encrypted at rest. Access tokens are never logged or echoed back through tool responses.

Example Prompts

1. Read-only lookup

"List clients with invoices overdue. Show amount and days outstanding."

Expected tool calls: invoices (list) and clients (list) firing.

Expected output: Response renders as a table.

2. Read-only with no results

"Show invoices for client xyz-not-real."

• Expected tool calls: clients (list, filter) returns empty.
• Expected output: assistant says "no matching client found" and stops. Does not invent client IDs and does not call invoices.

3. Single write

“Send my [contract template] to [client name].”

• Expected tool calls contracts (create), clients (retrieve to confirm clientID)
• Expected output: After confirmation, a contract template is sent to client.

4. Bulk action

“Draft a payment reminder to each of my clients with overdue invoices and show me before sending.”

• Expected tool calls: invoices (list), clients (list), messages (create)
• Expected output: Draft preview of 3–5 messages, one per overdue client, each editable. Explicit Send / Cancel controls. Nothing is written to the workspace until the user clicks Send. After approval: success confirmation with message IDs.

5. Destructive with confirmation

"Delete the client named [Annie Edison]."

• Expected tool calls: clients (retrieve to confirm identity) → on user confirmation, clients (delete).
• Expected behavior: assistant restates the client's name and email, warns that the deletion is not recoverable from within Assembly, and waits for explicit confirmation before calling clients.delete.

7. Brief/Analyze (multi-tool call + synthesis)

"Brief me on Acme Corp.”

Expected tool calls: search (company name), list actions for following tool calls: tasks, notes, clients, message_channels, messages, file_channels, files, invoices, contracts

Expected behavior: assistant summarizes key findings of list search with actionable assessment of recent communication, outstanding payments due, key relationships, notes, etc. and recommendations on user follow up.

6. Negative / out-of-scope

"Schedule a call with my client for 4PM"

• Expected behavior: assistant declines and explains that it does not have access to calendar/scheduling tools via Assembly (even if user embedded external tools). May suggest alternative tools or sending individual message with a link to a external calendar using messages tool.

7. Error case

"Show the invoice with ID inv_definitely_invalid."

• Expected tool calls: invoices (retrieve) returns a 404.
• Expected output: assistant says "no invoice with that ID exists," does not retry, and does not surface raw error payloads or stack traces to the user.

Known limits

Last updated 05/04/2026

• Pagination. Analysis of more than 25 clients at time can produce incomplete results.
• File upload. As of April 2026, platform API doesn’t support file upload because ChatGPT and Claude web/mobile restricts outbound network access to an allowlist of domains, and s3.amazonaws.com is not included. Claude Code does allow for file upload. We are working on a solution for this.
• No per-tool scopes yet. Today the connection inherits the user's full workspace permissions; there is no way to grant the AI assistant read-only or domain-scoped access. (The Scope field on the connection record is reserved for a future release.)
• Rate limits inherit the public Platform API; sustained bulk loops will eventually 429.
• Some events in the platform API do not currently have create actions: new contract_templates, invoice_templates, subscription_templates, task_templates, customFields, andproducts & prices must be created in the Assembly Dashboard UI 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.