Give AI tools a safe way to work in Sonny

Model Context Protocol is an open standard that lets compatible assistants discover and use Sonny actions with clear, machine-readable inputs. Claude and Cowork can connect with OAuth 2.1 and PKCE, then triage your inbox, share customer context, read reports, and send replies with files.

Connect with OAuth See every API operation

Remote MCP configuration

JSON

{
  "mcpServers": {
    "sonny": {
      "url": "https://www.usesonny.com/api/mcp"
    }
  }
}

Configuration formats vary by client. Add the remote Streamable HTTP endpoint; compatible clients discover Sonny's OAuth setup automatically. Scoped API keys remain available for clients that cannot use OAuth.

Why MCP

The same Sonny, through your AI tools

Every MCP tool uses the same workflows as Sonny's public API, so your automation and your team get consistent results.

Tools discover themselves: Your assistant can see available Sonny actions, their required inputs, and whether an action reads, writes, or deletes data.
Complete API coverage: Triage unanswered work, sync changes, assign teams, share customer context, read reports, and send files. Every public API operation has an MCP tool.
The same safety boundary: MCP uses the same scopes, workspace boundaries, and business rules as every direct API request.

Tool catalog

Clear actions with narrow inputs

Read-only tools are marked for assistants. Destructive tools are identified separately, so your client can ask for confirmation before it acts.

create_conversation: Creates an inbound email conversation with a contact summary and the first incoming message. Requires both conversations:write and contacts:write. Resolves the contact by email, preserves an existing name, creates missing text fields and validates existing typed fields atomically. Fields are included in text and HTML. Applies existing tag IDs, source routing, notifications and webhooks. Replies deliver by email. Channel-restricted keys can create only on their selected sources; standalone contact endpoints still require all channels. externalId is scoped to workspace + source; concurrent retries return the original IDs with deduplicated=true (200), ignoring changed content. Without externalId every call creates a separate conversation. No attachments or AI auto-response.
upload_attachment: Stages a private file up to 25MB for one conversation and the current sender. REST takes multipart file and conversationId; MCP takes fileName, contentType and dataBase64. Attach the returned ID once within one hour using attachmentIds on a reply or note. Replies still require messages:send. Message reads include agent-only extraction and new 15-minute download URLs. Older files are explicitly marked legacy_public and remain public.
list_properties: Lists workspace property definitions and their allowed types/options. Requires access to all channels.
get_contact_properties: Returns stored strings with property definitions, last-write provenance and update times. Requires access to all channels.
set_contact_property: Sets a typed value by property ID or name; null clears it. API-authored values are labelled and shared with AI under its verified-customer rules. Manual internal values stay excluded. Requires access to all channels.
list_contact_memories: Reads saved customer context for one contact and accessible source, including manual and learned facts used by Sonny AI.
create_contact_memory: Saves a manual memory through the shared validation, deduplication and per-contact/source limits. Available to Co-Pilot and to the auto-responder under its verified identity rules.
delete_contact_memory: Removes one memory belonging to the supplied contact and source.
get_report: Uses the dashboard's reporting queries and date/source/assignee/tag filters. Kinds: overview (counts, response times and CSAT), volume, response-times, agents, sources, tags, csat, ai, knowledge, leads, online-hours. Knowledge uses the date range and permitted sources, independent of source/assignee/tag selections. Online hours describes workspace presence for accessible teammates; conversation counts remain channel-scoped. Responses are not cached. Existing CSAT endpoints retain their separate scope and populations.
sync: Returns a bounded durable change feed. Without a cursor, starts with the last hour. Retains events for 30 days; expired cursors return 410 resync_required. Deduplicate by event ID. Payloads require their own read scopes; messages and memories are opt-in. To bootstrap, drain and save a cursor, read current lists, then replay from that cursor.
batch_update_conversations: Applies one patch to up to 100 unique conversations, with independent atomic results for each ID. Supports team round-robin, snooze and tag changes. Uses the existing request-based rate limit.
list_members: Lists active assignable teammates with current availability and effective channel access. Omits email and teammates outside accessible channels.
list_teams: Lists workspace teams and their accessible active members. Channel-restricted callers see only teams with an accessible member.
list_tags: Returns all workspace tags, ordered by name. Requires access to all channels.
create_tag: Creates a workspace tag with a unique name and optional hex color. Requires access to all channels.
get_tag: Returns one workspace tag. Requires access to all channels.
update_tag: Updates a workspace tag's name or color. Omitted fields are preserved. Requires access to all channels.
delete_tag: Permanently deletes a workspace tag and removes it from all contacts and conversations. Requires access to all channels.
add_conversation_tag: Applies an existing workspace tag to an accessible conversation. Existing assignments are preserved. Read assigned tags with get_conversation.
remove_conversation_tag: Removes a tag from an accessible conversation without deleting the workspace tag. Read assigned tags with get_conversation.
list_contacts: Returns workspace contacts with tags and conversation counts. Filter by exact stored property values; multiple property filters must all match.
create_contact: Creates a contact. Email addresses are unique within a workspace.
get_contact: Returns one workspace contact.
update_contact: Updates supplied contact fields.
archive_contact: Archives the contact without deleting conversation history.
list_channels: Returns the stable channel values accepted by conversation filters.
list_sources: Returns configured workspace sources and the conversation channels each source supports.
list_conversations: Returns non-trash, non-spam conversations with attention, assignment, snooze, priority and tag filters. Awaiting reply ignores notes; unread is specific to the current teammate. Tags match any supplied ID. Defaults remain compact=false and snoozed=any. Use sync for durable message and state changes.
get_conversation: Returns one conversation with contact, assignee, group, and tags.
update_conversation: Changes status, priority, assignee, team, snooze or tags. Request assignment=round_robin with a team to select an available member (409 if none). Preserves audit, CSAT, notification, search, realtime, and webhook side effects.
list_messages: Returns chronological messages. Use before for older history or after for newer messages. Attachments include fresh 15-minute download URLs, storage access guarantees and agent-only AI extraction.
create_internal_note: Adds an internal note with optional attachmentIds from uploads owned by the current sender and conversation. Attachment-only notes are supported. This endpoint never sends a customer-facing message.
send_message: Sends a customer-facing reply as the authenticated teammate. Accepts attachmentIds from uploads owned by that sender and conversation, including attachment-only replies. Delivery follows the conversation's channel: realtime chat (with an email copy when the visitor is offline) or email from the source's sending identity. Check emailDeliveryStatus for email delivery: failed means the reply was saved but the email was not sent; retry it from the inbox. Requires the messages:send scope, granted separately from messages:write.
list_webhooks: Returns endpoints and recent delivery status. Secrets are never returned.
create_webhook: Creates an HTTPS endpoint. The signing secret is returned once.
list_webhook_events: Returns the canonical subscription catalog.
update_webhook: Changes endpoint configuration or enabled state.
delete_webhook: Deletes the endpoint and its delivery history.
test_webhook: Queues webhook.test for this enabled endpoint even when it is not subscribed to that event. Disabled endpoints return 409.
list_webhook_deliveries: Returns the 50 most recent delivery attempts.
retry_webhook_delivery: Resets a terminal failed delivery and queues it immediately. Disabled endpoints return 409.
list_kb_articles: Returns the help center articles for a source, ordered by position. Use status to filter drafts or published articles.
create_kb_article: Creates an article in the source's help center and indexes it into the AI knowledge base when published. Slugs are auto-derived from the title when omitted and deconflicted automatically.
get_kb_article: Returns one article including its sanitised HTML body.
update_kb_article: Updates supplied article fields and re-syncs the AI knowledge index. Publishing stamps publishedAt the first time only.
delete_kb_article: Permanently deletes the article and withdraws it from the AI knowledge index.
list_kb_categories: Returns the help center categories for a source, ordered by position.
create_kb_category: Creates a category in the source's help center. Slugs are auto-derived from the name when omitted.
update_kb_category: Updates supplied category fields. Articles keep their category unless it is deleted.
delete_kb_category: Deletes the category. Its articles become uncategorised, they are not lost.
get_csat_summary: Returns customer satisfaction scores on the 1–3 scale (1 bad, 2 okay, 3 great) for the whole workspace, per channel type (chat, email), and per source (channel), with the rating distribution, satisfaction rate (share rated great), and response rate against conversations closed in the same window. Omit every filter for the all-time global score.
list_csat_ratings: Returns individual customer ratings with comments, newest first. Filter by rating value (for example rating=1 for every bad rating, or rating=1,2), source, channel type, assignee, contact, comment presence, and time window.
get_conversation_csat: Returns the customer's rating and comment for one conversation, or null data when the customer has not rated it yet.
reorder_kb_articles: Supply the complete ordered list of IDs. Rejects stale or foreign IDs transactionally.
upsert_kb_article: Creates or updates using a stable external ID unique to this help center. Returns 201 on create or 200 on update. Omitted update fields are preserved. New articles default to draft and uncategorised.
reorder_kb_categories: Supply the complete ordered list of IDs. Rejects stale or foreign IDs transactionally.
upsert_kb_category: Creates or updates using a stable external ID unique to this help center. Returns 201 on create or 200 on update. Omitted update fields are preserved. New articles default to draft and uncategorised.
get_kb_category: Returns one category in the accessible help center.
get_help_center: Returns branding, publishing, discovery settings and the current public URL. Domain connection remains available in the dashboard.
update_help_center: Updates the supplied publishing and appearance settings. First create an article or category to initialise the help center.
upload_kb_media: Uploads JPEG, PNG, GIF or WebP up to 25MB. Returns a public URL for article bodies. REST accepts multipart file; MCP accepts base64 bytes.
list_kb_audiences: Manage named audiences using verified customer trait rules. Audience deletion leaves linked content verified-only.
create_kb_audience: Manage named audiences using verified customer trait rules. Audience deletion leaves linked content verified-only.
update_kb_audience: Manage named audiences using verified customer trait rules. Audience deletion leaves linked content verified-only.
delete_kb_audience: Manage named audiences using verified customer trait rules. Audience deletion leaves linked content verified-only.

Connect securely

One connection, only the access you choose

Connect with OAuth: Sign in, review the requested scopes, and choose a workspace.
Add the MCP server: Add the remote URL. OAuth-capable clients discover the rest.
Stay in one workspace: Sonny scopes every tool call to the workspace you approved.