让 AI 工具安全地在 Sonny 中工作

Model Context Protocol（模型上下文协议）是一项开放标准，让兼容的助手通过清晰、机器可读的输入发现并使用 Sonny 的操作。Claude 和 Cowork 可通过 OAuth 2.1 和 PKCE 连接，然后分拣你的收件箱、共享客户信息、读取报表，并发送带文件的回复。

通过 OAuth 连接查看所有 API 操作

远程 MCP 配置

JSON

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

不同客户端的配置格式各不相同。添加远程 Streamable HTTP 端点后，兼容的客户端会自动发现 Sonny 的 OAuth 设置。无法使用 OAuth 的客户端仍可使用限定权限的 API 密钥。

为什么选择 MCP

同一个 Sonny，通过你的 AI 工具使用

每个 MCP 工具都使用与 Sonny 公开 API 相同的工作流，你的自动化和团队都能得到一致的结果。

工具自动被发现: 你的助手可以看到可用的 Sonny 操作、所需的输入，以及每项操作是读取、写入还是删除数据。
完整覆盖 API: 分拣未回复的工作、同步变更、分配团队、共享客户信息、读取报表并发送文件。每一项公开 API 操作都有对应的 MCP 工具。
同样的安全边界: MCP 与每个直接的 API 请求使用相同的权限范围、工作区边界和业务规则。

工具目录

操作清晰，输入精简

只读工具会为助手单独标注。破坏性工具也会被单独标识，让你的客户端在执行前先请你确认。

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.

安全连接

一次连接，只授予你选择的权限

通过 OAuth 连接: 登录，查看所请求的权限范围，然后选择一个工作区。
添加 MCP 服务器: 添加远程 URL，支持 OAuth 的客户端会自动完成其余步骤。
始终限定在一个工作区: Sonny 会把每次工具调用限定在你批准的工作区内。