Model Context Protocol
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.
The connection runs over your tenant subdomain with an OAuth bearer token your client mints on first use. No API keys to copy or share.
What you can do
Section titled “What you can do”A connected client picks up three things from Sonora: tools, resources, and prompts.
- Tools are fourteen 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.
- Resources are entity lookups by URL. Paste
sonora://customer/:uuidinto 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
Section titled “Quickstart with Claude Desktop”- Open Claude Desktop → Settings → Connectors → Add custom connector.
- Name:
Sonora. URL:https://<your-subdomain>.usesonora.com/mcp. - Click Connect. Claude opens your browser to authorize.
- Sign in to Sonora if needed, then click Authorize on the consent screen.
- 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://<your-subdomain>.usesonora.com/mcp).
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. |
Resources
Section titled “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
Section titled “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
Section titled “Authentication”MCP traffic uses OAuth 2.1 with PKCE — the same flow modern MCP clients implement by default. On first connection:
- Your client opens a browser to Sonora’s consent screen.
- The screen names the requesting client and the scopes it’s asking for.
- 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.
Limits
Section titled “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. Keyset cursors will arrive in v2.
Past 60 calls per minute, requests return Rate limit exceeded. Retry after Xs. until the window resets. See credits and rate limits for how API usage fits alongside your plan.