MCP server

CommSync speaks the Model Context Protocol. Point an MCP-capable app or agent at the endpoint. It can then read threads, send messages, manage contacts and labels, and more.

There are two ways to authenticate, and both reach the same tools:

• OAuth 2.1 is the primary way. The app signs you in with no shared secret. See Connect AI apps.
• An API key is the alternative for scripts and servers. Send it as a Bearer token. See API keys.

OAuth is how Claude, ChatGPT, Codex, Cursor, and VS Code connect.

The signed-in user and their org role scope every operation.

Connect

The server is a single stateless HTTP endpoint. To connect an AI app, paste the endpoint URL into the app and sign in. The Connect AI apps page has a guide for each app.

To call the endpoint from your own code with an API key:

curl -X POST "$COMMSYNC_API/api/mcp" \
  -H "Authorization: Bearer csk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "list_threads", "arguments": { "limit": 20 } }
}

Authentication

OAuth 2.1

CommSync is its own authorization server. A client needs only the endpoint URL, because it discovers everything else:

1. A request with no token gets 401 and a WWW-Authenticate header. The header names the protected-resource metadata (/.well-known/oauth-protected-resource/api/mcp, RFC 9728).
2. That document names the authorization server. Its metadata is at /.well-known/oauth-authorization-server (RFC 8414).
3. The client registers, sends you to the consent screen, and exchanges the code for tokens.

The authorization response carries iss (RFC 9207). A loopback redirect (http://127.0.0.1, http://localhost, http://[::1]) can use any port.

A code is single-use. A second exchange that passes the PKCE check revokes the tokens that the first exchange issued. CommSync refuses a second exchange without the right verifier, and that exchange changes nothing.

API key

Send Authorization: Bearer csk_…. A key does not expire, and you revoke it under Settings, in API keys. A key suits a script or a server-side agent.

Authorization model

Every request resolves your credential (an OAuth token or an API key) to (userId, orgId, role, accessibleChannels). Each tool sits behind one of five gates. The server rejects a call that exceeds your access before anything happens.

any member any user in the org   channel access needs access to the relevant channel   agents access   owner / admin   owner only

• any member — any user with org membership.
• channel access — you must have access to the channel involved.
• agents access — owners and admins, and members when the workspace lets members use Agents.
• owner / admin — reserved for org owners and admins.
• owner only — the single workspace owner (for example, billing).

Owners and admins have channel access implicitly; members get it per channel — see Roles & permissions.

CommSync also tags tools by effect: read (no change), write (mutates), or destructive (removes data — use with care).

Channel-scoped keys and apps

An API key or a connected app can be fine-tuned to specific lines instead of your full channel access. For a key, choose Specific lines when you create or edit it under Settings, in API keys. For an app, choose it on the consent screen. You can change it later under Settings, in Connect AI apps. Pick the email addresses and phone numbers it can touch.

The server then intersects your live channel access with the allowlist on every request. A scoped key or app can only read, send, and act on the chosen lines. Threads on other channels are invisible to it, and CommSync refuses sends from other channels. Channel listings only show what is in scope.

• The default is All channels: the key follows your live access.
• This includes lines you connect later; CommSync migrated pre-existing keys this way.
• A scoped key never out-privileges you.
• If you lose access, or someone deletes the line, it drops from the key's scope too.
• Per-user surfaces (contacts, labels, AI, webhooks, profile) do not belong to a channel, so scope does not affect them.
• The agent tools show only the agents, turns, and threads on the chosen lines.
• They pause or activate only an agent with every line in scope. They do not return the agent stats.

Security details

Each key and each app has one more setting: Security details. It decides how much of your account security mail the key or app reads. You set it on the consent screen. To change it later, click the key under API keys or the app under Connect AI apps.

Choose Redacted for a key that a script or a shared tool holds. No setting ever returns a link, a token, or a code from a security event, because CommSync never stores one.

Tool catalog

Threads

Reads follow your channel access and return a compact shape for an AI app. A message carries its plain-text body, the sender, the attachments, the call details, and your read and star state. It also carries the identityId of the other party, which send_sms and send_email take. CommSync cuts a body longer than maxBodyChars (default 4,000 characters) and sets truncated: true. The HTML body of an email comes back only when you set includeHtml: true.

Every action changes only your own view of the thread, and your open web and iPhone apps show the change at once. An action works on every thread that list_threads shows you, also a thread on a line that an owner removed. On a line that you connected with Google sign-in, the read, archive, spam, Trash, restore, and star actions also change Gmail. Only a key or app with access to all channels does this.

Outbound sends

CommSync enforces channel access before any send. Compose and forward also need at least one accessible channel of the right kind.

Group threads and reply-all

A group thread has more than one other person in it. On a group thread, leave identityId out.

SMS. send_sms sends one text to every member, from the line of the group. Some phone platforms cannot send a text to a group. On those lines the tool answers GROUP_SEND_UNSUPPORTED with the app to reply in, and sends nothing. It never sends a private text to one member.

Email. send_email answers the latest inbound sender and copies everyone else. On a 1:1 thread, set replyMode to REPLY_ALL to do the same. CommSync then reads To and Cc from the message you answer, and leaves out your own mailbox. inReplyToMessageId picks that message.

Call get_send_options first to see the lines that can reply and whether a group reply can reach every member.

Files and scheduled sends

upload_attachment takes one file as base64 text and returns an id. Pass the ids in attachmentIds of send_email, compose_email, forward_message, send_sms, or compose_sms. A text takes images only, at most 10 files and 5 MB in total. The limit of 25 MB for a request applies to the base64 text, so one file can be about 18 MB. CommSync deletes a file that no send or draft uses within 24 hours. A file type that can run a program, such as .exe, .js, or .sh, gets the error FILE_TYPE_BLOCKED.

send_sms, send_email, compose_sms, and compose_email take scheduledFor, a future time with a UTC offset, such as 2026-10-05T09:00:00-04:00. The message waits with the status SCHEDULED. list_scheduled_messages lists your scheduled sends. reschedule_message moves one, and cancel_scheduled_message stops one. A stopped send stays on the thread as failed, so resend_failed_message can still send it.

Email bodies

send_email and compose_email take two body fields: bodyText and bodyHtml. Give one of them or both. A call with neither fails before CommSync sends anything.

Plain text alone is fine. CommSync builds the HTML part from bodyText. It escapes the text, keeps the line breaks, and turns each http:// or https:// link into a clickable link. When you give bodyHtml, CommSync sends your HTML unchanged. When you give only bodyHtml, CommSync makes the plain-text part from it. The account signature and the "Sent from CommSync" footer, when they are on, go after your text in both parts.

Rate limits never reach you

CommSync accepts every authorised send and owns delivery from that point on — this covers carrier and mail-host rate limits too. Send tools do not return 429 and never ask you to retry. When a provider throttles us the message stays queued, backs off, and goes out on its own.

Every send tool returns a receipt that describes where the message actually is:

{
  "accepted": true,
  "messageId": "cm9x…",
  "threadId": "cm7a…",
  "state": "waiting_on_line",
  "estimatedSendAt": "2026-07-29T18:41:12.000Z",
  "pacing": {
    "provider": "<platform name>",
    "sustainedPerMinute": 54,
    "rateLimited": true,
    "reason": "<platform name> rate limit — waiting 45s"
  }
}

state is one of dispatching, waiting_on_line, scheduled, sent, or failed. Never call a send tool twice for the same message — CommSync has already queued a waiting_on_line message and will deliver it.

Before a bulk run, call get_send_capacity for the sustainable rate on each line you can send from. If you exceed it, that is safe — messages queue rather than fail; they simply take longer to go out.

Retry safely with an idempotency key

A call can time out, or the connection can drop, after CommSync has already accepted the message. A plain retry then sends a second copy. To prevent that, give each message an idempotencyKey. The key is a string of 1 to 200 characters that you choose. A UUID works well.

send_sms, send_email, compose_sms, compose_email, and forward_message all take the key. When you call a tool again with a key that you already used, CommSync sends nothing. It returns the receipt of the first message, with "deduplicated": true.

{
  "to": "maya.chen@northwind.example",
  "subject": "Your lab results",
  "bodyText": "Hi Maya, your report is ready.",
  "idempotencyKey": "6f1c2a9e-3b7d-4e2a-9c55-0d8e41b7a3f2"
}

• Use a new key for each new message. A reused key returns the old message, even with new text.
• Your keys are private to your account. A teammate who picks the same key gets their own message, never yours.
• Without a key, each call sends a new message.

Channel management

Billing

Contacts

The contact graph is private per user — these never leak across users. A contact that a teammate shares with you opens with get_contact and list_contact_threads, without its owner’s notes.

Identities

Labels

AI

Attachments

These tools read the files on messages you can read. A key or app limited to some lines reads only the files on those lines.

Message entities

The bills, invoices, receipts, subscriptions, shipments, reservations, deadlines, phone numbers, addresses, people, and security events that CommSync read out of your messages. get_message and get_thread_messages also return them on each message. The security details setting applies.

Mailing lists

The mailing lists and marketing text senders that mail your lines. An unsubscribe applies to the whole line and needs send authority on it. CommSync never unsubscribes from a message with a caution strip or a spam verdict, and these tools never send a STOP text. See Unsubscribe from mailing lists.

Search, account & webhooks

Drafts

A draft is your own unsent email or SMS. A draft never sends. You send it from the app, or the AI app sends the message with a send tool and then deletes the draft. A key or app limited to some lines sees only the drafts on those lines.

Notes

Your private note and checklist on one conversation. Teammates never see it.

Home

Your to-dos and the two reply lists of Home, as Home shows them.

Team comments

Team comments on one conversation. The customer never sees them. The rules are the rules of the app: any share permit reads, and VIEW or above writes, except a shared-contact VIEW permit, which only reads. An @mention must name a teammate who can read the conversation, and that teammate gets the same email as from the app.

Teams and shared contacts

These tools only read. A team or a shared contact can give teammates access to conversations, so members, permits, transfers, and coverage decisions stay in the app. A team never shows a conversation that you cannot already read.

Agents

Agents are the AI teammates that answer inbound texts and email. An AI app can do everything that the Agents pages do: build an agent, give it knowledge and tools, test it, and supervise it. The tables below split the tools by job.

The permission rules are the rules of the app:

• Every agent tool needs agents access. Owners and admins always have it.
• Members have agents access when the workspace lets members use agents.
• A member sees only the activity on the lines they hold.
• To change, test, pause, or activate an agent, a member needs every line of that agent.
• A key or an app limited to some lines follows the same line rule.
• A key or an app limited to some lines can read knowledge, webhook tools, and MCP connections. It cannot change them.
• A key or an app limited to some lines cannot create or delete an agent.
• The approval queue is for owners and admins.
• Anyone who can see a conversation can take it over.
• No tool returns a secret or a credential.
• The one exception is the signing secret of a webhook tool.
• You get the signing secret once, when you create or rotate it.

The first table is for supervision.

Agent setup

Agent inspection

Agent test runs

A test run shows what an agent would do with a message, on a real conversation or one you type. It uses the same instructions, tools, and safety check as a real reply. CommSync sends nothing and writes nothing to the conversation. Each run uses AI credits like a real reply.

A saved test keeps a conversation and what passes, so you can run it again after each change to the agent. A test checks the next reply, a tool call, or a whole conversation with a simulated contact.

Agent analysis

After an agent conversation ends, a model judges the goals of the agent ("Did it book a visit?") and captures its fields ("Visit date", "Budget"). Set the goals and fields, try drafts on past conversations, and read each conversation with its outcome and results. Search the conversations of every agent with the filters of the Conversations view. Read a transcript, rate a conversation, or correct a result. Analyze again, or export a CSV file.

Set the alerts of an agent, and read or build its topics.

A key or an app limited to some lines sees only the conversations whose every thread is on its lines. It never sees a field marked sensitive. Only an owner or admin on a key or app with every line can export sensitive fields.

Knowledge

Agent webhook tools

Webhook tools are the HTTP endpoints that an agent calls while it works on a reply.

Agent MCP connections

These tools connect the external MCP servers that agents and Ask use.

Resources

Beyond tools, the server exposes MCP resources for direct reads:

commsync://threads/{threadId}/messages   — the newest 200 messages, compact
commsync://contacts/{personId}            — a contact's detail
commsync://digests/{localDate}            — the AI digest for a date

Common workflows