Model Context Protocol

Note

MCP access is available on Sonora’s Growth and Enterprise plans.

Sonora exposes a read-only Model Context Protocol server so MCP-compatible clients — Claude Desktop, Cursor, Claude Code, and others — can pull data from your workspace directly. Ask Claude about a customer, drop a Sonora URL into a prompt and have it expanded inline, or run a saved Sonora prompt without leaving your terminal.

One URL works for everyone — https://app.usesonora.com/mcp. Your workspace is picked when you approve the connection, from the account you sign in with, and every request after that is scoped to it. Your own subdomain (https://<your-subdomain>.usesonora.com/mcp) works too if you prefer it. Either way the client mints an OAuth bearer token on first use: no API keys to copy or share.

What you can do

A connected client picks up three things from Sonora: tools, resources, and prompts.

• Tools are seventeen typed queries against your workspace — the same questions Sonora chat answers internally: at-risk customers, recent meetings, open feature requests, escalations, product usage, sentiment trends, and how your workflows are performing.
• Resources are entity lookups by URL. Paste sonora://customer/:uuid into a Claude prompt and the full customer record loads into the conversation. Works for customers, contacts, meetings, notes, issues, and feature requests.
• Prompts are every prompt in your workspace — tenant-authored and Sonora’s built-in catalog — exposed as a templated MCP prompt with its slots as arguments.

The server is read-only. Nothing your MCP client does can mutate Sonora data.

Quickstart with Claude Desktop

1. Open Claude Desktop → Settings → Connectors → Add custom connector.
2. Name: Sonora. URL: https://app.usesonora.com/mcp.
3. Click Connect. Claude opens your browser to authorize.
4. Sign in to Sonora if needed, then click Authorize on the consent screen.
5. The browser returns to Claude, which now lists Sonora’s tools and resources.

Restart Claude Desktop if the new tools don’t show up — some versions cache the connector list until relaunch. The same flow works for Cursor (Settings → MCP → Add server) and Claude Code (claude mcp add sonora https://app.usesonora.com/mcp).

Tools

Each tool carries a typed JSON schema your client reads at connect time, so Claude builds the call from natural language rather than you constructing queries by hand.

Tool	What it does
query_customers	Filter and rank customers by health, ARR, owner, tier, recent activity.
query_contacts	Find people across accounts by role, seniority, or mention frequency.
query_meetings	Recent meetings with optional customer filter and date range.
query_notes	Search customer notes. Private notes are excluded server-side.
query_emails	Email snippets (headers and short previews — full bodies are not exposed).
query_customer_issues	Open support issues, scoped to a customer or workspace-wide.
query_customer_feature_requests	Aggregated feature requests with the customers asking for each.
query_escalated_customers	Currently-escalated accounts.
query_customer_engagement	Rolled-up engagement summary over a customizable window.
query_contact_engagement	Per-contact utterances from calls and meetings.
query_customer_ecsat_sentiment	Per-customer sentiment time series.
query_enrichment_changes	Transitions and numeric trends in enrichment values.
query_product_usage	Product usage metrics by customer.
query_salesforce_opportunities	Salesforce pipeline data, if the Salesforce integration is connected.
query_workflows	How each workflow performed over a window: runs started and how they ended, email opens, clicks, replies and bounces with their rates, and the goal rate.
query_workflow_runs	The customers a workflow enrolled, each with its status, what its emails got (opens, clicks, replies, bounces), and its goal result. Pass a run’s id for the full step-by-step trace.
query_workflow_goals	Which customers met, missed, or are still working toward a workflow’s goal, and each workflow’s goal rate.

The three workflow tools need the workflows:manage permission, the same one the Workflows pages need (every built-in role carries it), and see what you see in Sonora: your own private workflows are included, a colleague’s never are. Together they let you ask Claude how a campaign is doing and what came of it — “which accounts replied to the renewal sequence,” “which workflow has the best goal rate this quarter,” “did Acme reach healthy after onboarding.”

Resources

Resources let the client pull a single entity by URL — handy when you want a record loaded into a conversation without describing it.

URI template	Returns
sonora://customer/{id}	Customer profile with health, ARR, owner, and recent activity.
sonora://contact/{id}	Contact with stakeholder context.
sonora://meeting/{id}	Meeting with attendees and transcript.
sonora://issue/{id}	Customer issue with its timeline.
sonora://feature-request/{id}	Feature request with linked customers.
sonora://note/{id}	Customer note. Private notes return 404.

These are the same URLs Sonora chat surfaces in its responses. Copy a customer link out of chat and paste it into your MCP client — Claude resolves the URL and reads the record before answering.

Prompts

Every prompt in Settings → Prompts is exposed as an MCP prompt, plus Sonora’s built-in catalog (renewal briefings, QBR prep, expansion plays). Slot variables defined on the prompt become MCP arguments, so a prompt with a {{customer}} slot accepts a customer argument in any MCP client’s prompt picker.

Sonora’s catalog prompts are namespaced with a system__ prefix so they don’t collide with tenant-authored prompts of the same name.

Authentication

MCP traffic uses OAuth 2.1 with PKCE — the same flow modern MCP clients implement by default. On first connection:

1. Your client opens a browser to Sonora’s consent screen.
2. The screen names the requesting client and the scopes it’s asking for.
3. You approve. Sonora redirects back to your client with an authorization code, which the client exchanges for an access token (1 hour) and a refresh token (90 days).

The only scope used in v1 is mcp:read. A future mcp:write scope will gate any write-capable tools.

Tokens are bound to your user and your tenant. To revoke a client, disconnect it from inside the client — well-behaved MCP clients call Sonora’s revocation endpoint to invalidate tokens immediately. Signing out of Sonora invalidates the session that minted them.

Plain Sidekick

If your support runs on Plain, Sonora can mint a read-only MCP token for Plain’s Sidekick from the Plain connection’s settings, so your support AI answers from the whole relationship. It is the same server and the same scope; the token is shown once and lasts a year.

Limits

Server-side caps apply to every response regardless of the client-passed limit.

Limit	Value
Calls per token	60 per minute
Items per response	200
Response size	256 KB
Access token lifetime	1 hour (refresh token rotates)

When a result exceeds the item or byte cap, the response carries a truncated: true flag and a warning field telling you to narrow the query by date range, customer filter, or owner. query_workflow_runs and query_workflow_goals page: when there’s more, the response carries a nextCursor, and Claude passes it back to fetch the next page.

Past 60 calls per minute, requests return Rate limit exceeded. Retry after Xs. until the window resets. See usage and limits for how API usage fits alongside your plan.