MCP server

CommSync speaks the Model Context Protocol. Point an MCP-capable agent (Claude Desktop, a custom client, or your own integration) at the endpoint with an API key. It can then read threads, send messages, manage contacts and labels, and more. The key owner's user and org role scope every operation it performs.

Connect

The server is a single stateless HTTP endpoint. Authenticate with a csk_… key as a bearer token.

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 } }
}

Authorization model

Every request resolves your key to (userId, orgId, role, accessibleChannels). Each tool sits behind one of four 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   owner / admin   owner only

• any member — any user with org membership.
• channel access — you must have access to the channel involved.
• 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

An API key can be fine-tuned to specific lines instead of your full channel access. When you create (or edit) a key in Settings, then API Keys, choose Specific lines. Pick the email addresses and phone numbers it can touch.

The server then intersects your live channel access with the key's allowlist on every request. A scoped key 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.

Tool catalog

Threads

Org-scoped reads (filtered by channel access); mutations write only your own per-user view state.

Outbound sends

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

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": "JustCall",
    "sustainedPerMinute": 54,
    "rateLimited": true,
    "reason": "JustCall 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.

Channel management

Billing

Contacts

The contact graph is private per user — these never leak across users.

Identities

Labels

AI

Search, account & webhooks

Resources

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

commsync://threads/{threadId}/messages   — messages in a thread
commsync://contacts/{personId}            — a contact's detail
commsync://digests/{localDate}            — the AI digest for a date

Common workflows