Un modo sicuro per far lavorare gli strumenti AI in Sonny

Model Context Protocol è uno standard aperto che permette agli assistenti compatibili di scoprire e usare le azioni di Sonny con input chiari e leggibili dalle macchine. Claude e Cowork possono connettersi con OAuth 2.1 e PKCE, poi smistare la tua posta in arrivo, condividere il contesto dei clienti, leggere i report e inviare risposte con file.

Connetti con OAuth Vedi tutte le operazioni API

Configurazione MCP remota

JSON

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

Il formato di configurazione varia da client a client. Aggiungi l'endpoint remoto Streamable HTTP: i client compatibili rilevano automaticamente la configurazione OAuth di Sonny. Le chiavi API con ambiti restano disponibili per i client che non possono usare OAuth.

Perché MCP

Lo stesso Sonny, attraverso i tuoi strumenti AI

Ogni strumento MCP usa gli stessi flussi di lavoro dell'API pubblica di Sonny, così le tue automazioni e il tuo team ottengono risultati coerenti.

Gli strumenti si presentano da soli: Il tuo assistente vede le azioni di Sonny disponibili, gli input richiesti e se un'azione legge, scrive o elimina dati.
Copertura completa dell'API: Smista il lavoro senza risposta, sincronizza le modifiche, assegna i team, condividi il contesto dei clienti, leggi i report e invia file. Ogni operazione dell'API pubblica ha il suo strumento MCP.
Gli stessi limiti di sicurezza: MCP usa gli stessi ambiti, gli stessi confini tra spazi di lavoro e le stesse regole di business di ogni richiesta API diretta.

Catalogo degli strumenti

Azioni chiare con input mirati

Gli strumenti di sola lettura sono contrassegnati per gli assistenti. Quelli distruttivi sono identificati a parte, così il tuo client può chiedere conferma prima di agire.

get_connection_info: Reports effective scopes and allowed source names after key and member restrictions intersect. sourceAccess=all means every current workspace source; selected means only the listed sources. Does not reveal credentials.
get_conversation_context: One bounded read of conversation state, full messages without HTML, latest reply delivery, and investigation checks. Follow message pagination before answering. Use expectedLastMessageId and a stable idempotencyKey when replying. after reads only new messages; omit it after transcript edits. Checks marked stale need verification; fresh checks retain their timestamps and references.
list_conversation_checks: Reads the latest result for each named check on an accessible conversation, including checker, authenticated actor, server timestamp and card reference. Read before repeating investigation.
record_conversation_check: Stores a result under a stable key on an accessible conversation in the private Sonny workspace. Replaces only that named check; other checks are preserved. checkedBy labels the checker; actorId and checkedAt are set by Sonny. Omitted reference clears it. A reference URL is stored as text and is never fetched. Does not send messages, call external services, or mark the customer answered.
get_status: Checks that the app can reach its database. If MCP tools fail to load, call the independent unauthenticated /api/health route directly. This check does not prove that webhook delivery workers or external email providers are healthy.
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. compact=true returns message previews capped at 200 characters instead of bodies. 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 tag IDs, names and colors, ordered by name. Available to channel-scoped keys with tags:read; tag definitions are shared across channels. Use add_conversation_tag with conversations:write to tag only accessible conversations. Tag creation, editing and deletion still require an all-channel key.
create_tag: Creates a workspace tag with a unique name and optional hex color. Requires access to all channels.
get_tag: Returns one shared workspace tag by ID. Available to channel-scoped keys with tags:read.
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. Use erase_contact to permanently delete the person's data.
erase_contact: Permanently and irreversibly deletes the contact and everything stored about them: every conversation (including Trash) with its messages, notes, attachments and stored files, plus tags, custom property values, customer memories, verified identities, push devices and visitor browsing history. For data-protection (GDPR) erasure requests; use archive_contact to hide a contact but keep history. Email suppression and blocked-sender entries for the address are kept. Audit-logged with ids and counts only; sends contact.erased and conversation.deleted webhooks. Owner or admin keys with access to all channels only. Confirm with the user first.
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: For oldest waiting sellers use status=open, awaitingReply=true, sort=waitingSince, direction=asc, compact=true. waitingSince is the first incoming message since the last reply; reminders and internal notes do not reset it. Returns non-trash, non-spam conversations with attention, assignment, snooze, priority and tag filters. Set status=open, awaitingReply=true and sourceId to list one store's waiting customers. 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, tags or channel. Pass sourceId to move the conversation to another channel, optionally with channel to pick chat or email when the destination has both; the destination need not be one the key can access, though the conversation being moved must be, and a key loses a conversation it moves out of its own channels. Moving to an email channel requires the conversation to have a contact email. The move is audit-logged and noted on the thread. 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 after with the last seen message ID for cheap rereads; compact=true returns sender, time, read time and a 200-character text preview without attachment or transcript payloads. Full mode includes fresh 15-minute attachment download URLs, agent-only image extraction, and video transcripts. While full-mode readings are running, readsInProgress suggests the next call; waitSeconds can hold that call up to 30 seconds.
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.
edit_message: Edits the plain-text body of your own human customer reply. Requires messages:send and access to the conversation source. Preserves attachments and the original send time; clears prior HTML and link preview. Updates the transcript and connected chat clients without sending another email or notification. Delivered emails remain unchanged. Incoming messages, bot replies, notes and replies from other teammates cannot be edited. Wait until pending email delivery completes before editing.
send_message: Sends a customer-facing reply as the authenticated teammate. Pass expectedLastMessageId to fail with 409 if any newer message or note arrived, and idempotencyKey to replay the saved result safely after a retry. internalNote and status can be saved with the reply in one transaction; these fields also require messages:write and conversations:write respectively. 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. Narrow delivery with agentGroupIds (conversations owned by those groups; unassigned conversations are not delivered), customerMessagesOnly (skips team replies, notes, and API/MCP/AI sends) and excludedSenderIds (skips messages from those users). All default to no filter, and the message filters apply to message.* events only. coalesceSeconds (5-300, null for real time) groups a conversation's messages into one conversation.activity delivery carrying every message id. Set headers to send custom request headers, such as Authorization, with every delivery; values are stored encrypted and never returned, and Sonny's own headers cannot be overridden.
list_webhook_events: Returns the canonical subscription catalog.
update_webhook: Changes endpoint configuration or enabled state. Resubmit a saved custom header by name alone to keep its stored value; send an empty headers array to remove them all. Changing the URL to a different host requires re-sending every header value, so a stored credential is never forwarded to a new destination. coalesceSeconds (5-300, or null for real time) groups a conversation's messages into one conversation.activity delivery.
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 a category in the accessible help center using a stable external ID. Requires the category name; omitted optional fields are preserved on update. Returns the category and whether it was created. Does not create or publish articles. Category changes can affect the published help center.
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: Lists named reader audiences for the accessible help center, including each audience ID, name, slug, and verified customer trait rules. Read-only; does not create, change, or delete audiences.
create_kb_audience: Creates a named reader audience in the accessible help center. Supply a name and rules with match all or any and trait conditions; slug is optional. Returns the created audience. Assign its ID to help articles or categories separately to restrict their readers.
update_kb_audience: Updates the supplied name, slug, or verified customer trait rules of one audience in the accessible help center. Returns the updated audience. Rule changes affect which verified readers can access linked help articles and categories.
delete_kb_audience: Manage named audiences using verified customer trait rules. Audience deletion leaves linked content verified-only.

Connessione sicura

Una sola connessione, solo l'accesso che scegli

Connetti con OAuth: Accedi, controlla gli ambiti richiesti e scegli uno spazio di lavoro.
Aggiungi il server MCP: Aggiungi l'URL remoto. I client compatibili con OAuth trovano da soli il resto.
Resta in un solo spazio di lavoro: Sonny limita ogni chiamata agli strumenti allo spazio di lavoro che hai approvato.