Skip to main content
Zelto exposes a Model Context Protocol server at https://api.zelto.ai/mcp. Any MCP-compatible client can connect and get read access to your agents, conversations, transcripts, reviews, and findings, plus a small set of write tools for the bucket-based review workflow. Most read and write tools mirror a public REST API endpoint, so anything you can do over HTTP you can do from inside your editor. Some tools go beyond the REST surface, though — review queues, changes, bucket population, voice-provider connect/import, and organization settings tools are MCP-only. The Mirrors column in each table below tells you which is which (— (MCP-only) means there’s no REST equivalent).
New here? Onboard with an agent drives the whole setup — connect a provider, get conversations in, create a monitor, and route findings — over the onboarding tools below.
Building a benchmark? Create cases with the API covers the benchmark case tools (add_benchmark_cases, add_benchmark_cases_from_conversations, add_benchmark_cases_from_traces).

TypeScript integration

For TypeScript projects, the official npm package is zelto-sdk. Conversation ingestion requires version 0.4.0 or later. Before installing, check npm view zelto-sdk version: if 0.4.0 is not published yet, use the HTTP integration below. Version 0.3.0 only provides the legacy web analytics API. Once available, run npm install zelto-sdk@^0.4.0 and use Zelto.sendConversation on the server; see the TypeScript example in the upload guide. Keep the API key in server-only environment variables. MCP connects remotely without an npm package. “Install Zelto in this project” is a coding-agent instruction, not a shell command.

Create your account using only MCP

The public discovery endpoint https://api.zelto.ai/mcp/signup exposes start_signup with {}. It returns signInUrl, signupUrl, and mcpUrl. The agent gives you a link; you sign in or register in your browser, choose your own credentials and verify your email with Verify my account in the email. The agent never generates a password or asks for an email code. Connect to the returned mcpUrl using your client’s normal OAuth flow and approve organization access in the browser. The client handles PKCE and state. This works for new and existing accounts. Clients without OAuth can use an API key configured directly in their local secret store, never pasted into chat. The registration endpoint cannot read data or mint keys; the former resend_signup_code and complete_signup tools are no longer exposed. If you open the verification link in another browser or for a different account, Zelto shows the email address and asks you to confirm before signing you in.

Get an API key

Mint one at https://dashboard.zelto.ai/org/<your-slug>/settings/integrations → API integration. The key is shown once — copy it immediately. The same key works for the REST API and every MCP client below. Minting and revoking keys is an owner/admin action; if you hold the member role, ask an owner or admin for one (and see Your role decides what you can do). Export it for the snippets below:
The REST base is https://api.zelto.ai/v1.

Sign in with OAuth

Clients that support remote MCP OAuth — Claude, Cursor, VS Code, and others — can connect without minting a key. Point the client at the server URL and sign in through your browser:
On first connect the client opens a browser window to sign in to Zelto and authorize access. If you belong to more than one organization you choose which one the connection is scoped to on the consent screen — the client only ever sees that organization’s data, exactly like an org-scoped API key. Access tokens are short-lived (one hour), refresh only while your Zelto session is valid, and stop working as soon as you lose access to that organization. Under the hood the server is a standard OAuth 2.1 Authorization Server as the MCP spec defines it — it publishes Protected Resource Metadata, supports Dynamic Client Registration, and requires PKCE — so a compliant client discovers everything it needs from the URL alone. API keys keep working in parallel; use whichever your client supports.
Using Claude on the web or the Claude Desktop app? Connect Zelto to Claude walks through adding it as a custom connector.

Clients

Claude Code

Add the server to ~/.claude.json (create the file if it doesn’t exist):
Restart Claude Code (or run /mcp to refresh). The zelto: tools appear in the picker; zelto:health returns your org id as a smoke test.
The integrations page also shows this snippet pre-filled with the current host — go to Settings → Integrations → AI agent access and open the Claude card.

OpenAI Codex CLI

Codex CLI supports MCP servers via ~/.codex/config.toml. Add a server entry under [mcp_servers.zelto]:
Then run codex and ask it something that needs your data, e.g. “list my last 20 conversations and group failures by agent.” Codex discovers the zelto: tools automatically.

Cursor

~/.cursor/mcp.json accepts the same shape as Claude Code:
Then open Cursor’s MCP panel and toggle the zelto server on. The tools show up in the chat sidebar.

Continue, Zed, and other Streamable-HTTP clients

The server speaks Streamable HTTP, so any client that accepts a URL + Authorization header works. Continue uses config.yaml:
Zed uses ~/.config/zed/settings.json under context_servers.zelto with the same url + headers shape.

Quick smoke test (curl)

If a client is misbehaving, verify your key and connectivity against the REST API — the same key authenticates both:
A 200 with a { "data": [...] } page means the server and your key are good — the problem is in the client config. From inside a connected client, the health tool returns { "status": "ok", "orgId": "…" } as the same check. A 401 means the credential is the problem: the key was deleted, or the person it belongs to lost access to the organization (removed, or their account banned). Minting a fresh key only helps if your own account still has access to that org.

Authentication

Every request to the regular /mcp server carries an Authorization: Bearer <token> header, where the token is either an API key or an OAuth access token obtained by signing in. Requests with no token or an invalid/expired token return 401 and never reach a tool. Either way the token resolves to a single organization server-side — an API key from its baked-in org, an OAuth token from the org you chose at consent — and a tool only ever sees that organization’s data.

Your role decides what you can do

Authenticating proves which organization you may act on, not what you may do inside it. Tools that administer the organization itself require the owner or admin role — the same gate the dashboard applies: update_org_settings · invite_member · remove_member · save_usage_report_config · set_voice_tool_access · delete_agent · set_findings_delivery · merge_findings · delete_finding · approve_finding_candidate · reject_finding_candidate · update_finding (only when you pass title — the triage fields stay open to any member) update_member_role is stricter still: owner only, and it refuses to change your own role. remove_member likewise refuses to remove your own membership, whatever your role — ask another owner or admin. A token belonging to a member reaches every read tool and every non-administrative write, but the tools above return Only an organization owner or admin can perform this action. instead of acting (update_member_role returns Only an organization owner can perform this action.). This is true for both credential types: a key or token acts as the person behind it, and this gate reads that person’s role at call time rather than at mint time. To take a credential out of service entirely, revoke it — see API keys. Removing that person from the organization (or banning their account) does the same thing implicitly: every request re-checks the owner, so their keys and OAuth tokens stop working on the next call.

Read and write scopes

An OAuth client asks for an access scope at consent time, and the server enforces it before a tool runs:
  • write — every tool, including the mutating ones. Implies read.
  • read — the read tools only. A read-scoped token that calls a mutating tool gets a tool error instead of a result: This credential is read-only and cannot call "<tool>". Reconnect with the "write" scope to allow changes. The call never reaches the tool, and the attempt is recorded in the organization’s MCP activity. The one exception is send_feedback, which any credential can call (see Agent feedback).
  • No access scope — tokens minted before scopes existed keep full access.
API keys carry full access; a key is not narrowed by scope. Whichever credential you use, the role gate still applies on top. Send one JSON-RPC message per POST /mcp. A JSON-RPC batch array that contains a tool call is refused with 400; request bodies over 4 MiB are refused with 413.

Tools

Read tools

read_docs is MCP-only — call it with no arguments to list every documentation page (slug + title + description), then pass a path (e.g. findings or integrations/slack) to read that page’s full Markdown. Tool arguments name an entity’s id two ways, depending on the tool: a finding is id for get_finding / update_finding but findingId for approve_finding_candidate, a monitor is monitorId for get_monitor but id for update_monitor, and so on. The tables list the canonical name. The server also accepts the other spelling (id or <entity>Id) for finding, monitor, conversation, agent, change, bucket and queue ids, so a call that guesses the wrong one still works. An explicit canonical argument always wins. status enums: reviews accept pending / reviewed / flagged; findings accept open / acknowledged / resolved / ignored. Finding priority accepts none / low / medium / high / urgent.

Interactive views (MCP Apps)

Seven tools open Zelto’s findings and monitors experience inside the conversation instead of returning text. Clients that support MCP Apps render them inline; other clients see an empty result, so use the matching browse_* or list_* tool there. They are one connected view, so you can follow links in either direction: from the list to a finding, from a finding (or a conversation example in its text) to a conversation’s transcript, from a transcript to the same conversation’s trace and back, and from a conversation to the findings it belongs to. From a monitor’s results you can open a conversation’s transcript, and go back to the monitor where you left it. Findings list. What the Findings page shows: status tabs with counts, search, priority, assignee, and agent filters, sortable columns (last seen, age, conversations, volume, priority), and an assignee on each row. The arguments choose how it opens — for example { "status": "open", "priority": ["urgent", "high"], "assignee": "me" } — and you can change every filter afterwards. assignee accepts a user UUID, me, or unassigned. Finding. The finding’s rich-text content (including quoted agent prompts and conversation examples), its stats, and its linked conversations. Transcript card. Every turn with its speaker and time, a search that highlights matches, and tool calls with their arguments, results, and errors. Opened from a finding (or with findingId), it also shows that finding’s annotations, pinned to the moment of the conversation they refer to. Trace card. Everything the Traces page lets you do with a trace:
  • Three views of the spans — Tree, Timeline (a waterfall you can zoom from 1× to 8× and fit), and Tracks (one lane per kind of span) — with one shared selection and span search by name, type, or model. show_trace’s view argument picks the one it opens on.
  • Overview — time by step (average, with min, max, sum, count, and cost on demand), response time per turn (expandable to the spans behind each turn), attributes by span, and the trace’s log lines.
  • Span detail — type, time, duration, model, tokens, cost, and any error message, with the span’s input and output (formatted by role, or raw), attributes, and logs, and previous / next to step through the trace in time order.
On narrow screens the span list and the detail take turns, with a way back. Monitors list. What the Monitors page lists: every monitor in the order you arranged it, with its status, the agents or companies it applies to, its stages, and the affected rate over a window of 24 hours or 7, 15, or 30 days, in the monitor’s own outcome words (for example “refund promised”). Status tabs with counts, search, an agent filter, and sorting narrow it down. The arguments choose how it opens, for example { "status": "paused" }, and you can change every filter afterwards. Monitor. Four tabs, like the monitor page:
  • Overview — evaluated and affected counts, the affected-rate trend (or the average score) over 7, 30, or 90 days, a chart for each stage that produces a yes/no, category, or number, and a step-completion funnel for each flow check.
  • Results — one row per evaluated conversation with the verdict in the monitor’s own words, the agent, and the model’s reasoning for each stage. Filter all, affected, or not affected, and page through them. A result that failed to evaluate, or could not be scored, is shown as such, never as “not affected”. Open a result to read the conversation’s transcript.
  • Configuration — where it applies, what decides the verdict, the outcome labels, sampling, model, version, and every pipeline stage with its instruction. Read-only: to change a monitor, ask Claude (it can use update_monitor) or use the Zelto app.
  • Alerts — the threshold rule and who is notified, read-only; use save_monitor_alert to change it.
show_monitor’s tab and resultsFilter arguments choose what it opens on. Editing. Priority, status, and assignee are editable in the list and on a finding. Each edit is an ordinary update_finding call made through your client, so it needs the write scope, only organization members can be assigned, and a refused change is rolled back in the view with the reason. The switch on a monitor, in the list or on the monitor, is an ordinary set_monitor_enabled call, with the same scope requirement and the same rollback. Access. Everything is read through the browse_* tools, so the views see exactly your organization’s data under the same sign-in, role, and scope rules as any other tool call. Reading a transcript or a conversation’s details writes the same audit record as get_transcript and get_conversation. The structure of a trace (spans, timing, models, tokens) loads with the card; what a span was given and said (its input, output, attributes, and log lines) can contain what the user and agent said, so it is read only when you open a span or the Attributes and Logs tabs, and each of those reads is audited like a transcript read. A page of monitor results can quote the conversation, so reading one writes the same audit record as get_monitor_results; the overview, the configuration, and the alert carry no conversation content and are not audited. Long values are cut to keep the view fast, and the view says when that happened. The views open no network connections of their own.

Write tools

annotate_finding_conversation (add a system-authored, optionally audio-ranged annotation to a conversation within a finding) requires a platform-admin API key and the X-Organization-Id header — it is not callable with a standard org key. Regular org keys can write the same annotation over REST at POST /v1/findings/[id]/conversations/[conversationId]/comments (attributed to the calling user), or read them via list_finding_conversation_comments and edit/remove with update_finding_conversation_comment / delete_finding_conversation_comment.
Idempotent: add_conversation_to_bucket and add_conversation_to_finding return the existing row with alreadyExisted: true on re-add. The conversation must belong to the same agent as the bucket. create_bucket accepts only type: "static" today. AI agent creation runs the system prompt through the audit pipeline before insert. create_finding publishes an open finding in your organization, just like POST /v1/findings by default. Findings supplied by your own agent are visible immediately in the dashboard and readable through REST/MCP on every plan, including Free. Creating one does not enable paid automated analysis or linking. Platform-admin MCP callers retain the candidate review workflow. Existing candidate and rejected findings remain staff-only. The Candidates review workflow is unchanged for findings submitted through that workflow. conversationIds must be conversations of your organization: any other id is rejected with a conversation_not_found error naming it, and nothing is created. A finding description can be a plain string: Markdown (paragraphs, lists, bold, links) is converted to the rich-text document Zelto stores. Pass a TipTap/ProseMirror JSON document instead when you need blocks Markdown cannot express, such as the agentPrompt block below. A finding description can quote the instruction from an agent’s system prompt that the finding is about with an agentPrompt block: {"type": "agentPrompt", "attrs": {"agentId": "<agent id>", "agentName": "Paula", "agentVersionId": "<version id>", "versionNumber": 3, "lineStart": 12, "lineEnd": 18, "excerpt": "<lines>"}}. The excerpt must appear word for word in that agent version’s system prompt (without agentVersionId, in its current or any previous prompt), the version must belong to the agent, and the agent must belong to your organization — otherwise create_finding, update_finding and the REST endpoints reject the description. In the app, type / → Agent prompt in the description editor to pick the version and a start/end range of prompt lines. update_agent changes only the fields you pass — send description: null to clear it, omit a field to leave it untouched. systemPrompt is accepted for AI agents only (human agents have none) and is written as-is: unlike creation, it is not re-run through the audit pipeline. An agent’s type and provider are immutable and cannot be changed.

Review queues

A queue is a saved set of filters defining a dynamic collection of conversations to review. These tools are MCP-only. The filters object accepts: agentIds, agentType (ai / human), durationMinSeconds, durationMaxSeconds, endedReasons, dateFrom (YYYY-MM-DD), dateTo (YYYY-MM-DD), alreadyReviewed, hasAudio, isInteresting, findingTypes. An empty/omitted filters matches every conversation in the org. On update_queue, passing filters replaces the whole object — it is not merged with the existing one.

Changes

A change is one atomic, agent-scoped suggestion that addresses a set of findings. Each new change starts as a draft (no workflow status, hidden from the main list) until a human publishes it. These tools are MCP-only.
For API stability the MCP tool names keep the original solution term (create_solution, list_solutions, …) even though the product now calls these changes. The tools and the UI operate on the same records.
create_solution inserts exactly one draft per call — never bundle multiple ideas into one body; call it again for each distinct suggestion. A published change’s status is one of backlog / todo / in_progress / done / cancelled. You can’t set status on a draft: move it out of draft first with publish_solution (→ backlog) or discard_solution (→ cancelled). Deleting a change removes its finding links by cascade but never deletes the underlying findings.

Reports

A report is a free-form analyst write-up authored in the same rich-text editor as findings and changes. prompt holds the question or brief; description holds the body as a TipTap/ProseMirror JSON document. status tracks the generation lifecycle (pending / generating / completed / failed) — a report you create sits in pending unless you pass a finished body and set completed. These tools are MCP-only. On update_report, passing description replaces the whole body — it is not merged with the existing document. Pass prompt: null to clear the ask.

Bucket population

These tools snapshot conversations into buckets from queues or raw filters. They are MCP-only. Because queues can span multiple agents but buckets are agent-scoped, create_bucket_from_queue creates one bucket per matched agent and returns an array. The populate_* tools are idempotent — re-running adds zero new rows — and matches belonging to a different agent than the bucket are skipped and counted in skippedOtherAgentCount.

Bucket & finding mutations

The remaining MCP-only mutations, plus the one finding-conversation unlink that does mirror a REST endpoint. type accepts only "static". Every delete cascades its own link rows (bucket tasks, finding-conversation links, comments) but never deletes the underlying conversations.

Provider import

Connect a provider and pull its agents and conversations directly into Zelto — the same connect → import → backfill flow as Settings → Integrations, driven from your editor. These tools are MCP-only and cover every pull-capable provider: Vapi, Retell, Speechify, Telnyx AI, ElevenLabs, and Kapso (WhatsApp). Each takes a provider argument (vapi / retell / speechify / telnyx / elevenlabs / kapso). connect_provider uses a browser handoff so the API key never passes through the agent: it returns a one-time url (valid 15 minutes). You hand that URL to the user; they open it while signed in as an organization owner or admin and paste their key there, so the key goes straight to the server — never into your context or logs. Don’t ask the user for their API key yourself. After they finish, poll check_provider_connection with the returned token until status is completed (it returns agentsFound) — or expired (start over). label defaults to Default and must be unique per provider; the user can change it on the connect page. The page identifies the provider and destination organization, shows progress while checking the key, and lets the user correct a rejected key without starting over. Once connected, it confirms completion and offers a link to integration settings. The user can close the tab and return to the agent; reopening a completed link shows the existing connection without requesting another key. For AI-model and speech-to-text keys, use connect_ai_provider instead. It supports the same providers as create_ai_key, including custom_openai, and defaults the label to the provider name. The web form collects the key and, for custom endpoints, the base URL, model IDs and capabilities. Custom endpoint validation makes a small billed request per model. The existing PHI-mode restrictions apply. Poll the same check_provider_connection tool: kind: "ai" identifies an AI-key request, and completed means it was validated and saved. Use list_ai_keys afterwards to get the saved key’s ID and redacted metadata. kind: "voice" identifies a voice integration and includes agentsFound on completion. ElevenLabs voice integration and ElevenLabs STT keys are separate. Neither completion check returns the API key.
Never accept a provider API key as a tool argument. It would be captured in the agent’s conversation and client logs. connect_provider is a handoff for exactly this reason — the key only ever travels browser → server.
list_provider_agents returns every agent/assistant in the connected account(s), each annotated with alreadyImported (and importedAgentId once imported). agentId is the provider’s external id; for Vapi and Telnyx AI that is the assistant id; for Kapso it is the WhatsApp phone_number_id (each number is one agent — see Kapso). get_retell_agent reads one Retell agent directly without importing it. It returns the current general_prompt for Retell LLM agents and global_prompt for conversation-flow agents. import_provider_agent imports one agent and fails if it is already imported — call list_provider_agents first. It backfills the agent’s recent conversations (sinceDays, default 14, max 30) and enrolls the agent in ongoing auto-import, so new conversations keep flowing in without another pull. import_provider_conversations imports that agent’s conversations from since (an ISO 8601 timestamp, e.g. 2026-03-01T00:00:00Z) until now, in the background — the agent must already be imported, and re-running with an overlapping window is safe (already-imported conversations are skipped).

Onboarding

Stand a new organization up end to end from your editor: connect a provider, create a monitor, and route findings. These tools are MCP-only. The Onboard with an agent guide walks an agent through the whole flow using them. A headless run in order:
  1. get_onboarding_status — read nextIncomplete to resume from the right step.
  2. connect_provider — pass provider (vapi, retell, speechify, telnyx, elevenlabs, or kapso) and give the returned browser link to the operator. Confirm completion with check_provider_connection, then list and import their agents. Optional webhook setup is in Settings → Integrations; Kapso registers its webhook when a WhatsApp number is imported. Confirm conversations are arriving with list_conversations. For AI-model or STT keys, use connect_ai_provider instead.
  3. create_monitor — pass a starterKey from list_starter_monitors, a libraryKey from list_metric_library, or a name + a natural-language boolean instruction. Omitting both agentIds and companyIds applies it to every current agent. Confirm with list_monitors. Tool-execution checks (tool_check — did submit_order actually fire) are authored in the Monitors editor; create_monitor still creates an AI yes/no rubric.
  4. set_findings_delivery — channels is any of email / slack (Slack also needs the Slack app connected via OAuth in the web UI).
get_onboarding_status returns the ordered steps, each with a done flag: connectCalls (conversations are arriving, through a connected provider or the ingest API), importAgent (an agent exists) and createMonitor. It also returns nextIncomplete, the raw checklist, and monitorsAvailable. On a plan without monitors (Free), createMonitor is marked optional and blockedByPlan, nextIncomplete skips it, and complete is true once the other steps are done. Whether a first finding exists and whether delivery is set are not steps; read them with list_findings and set_findings_delivery.
Monitors are part of the Observability plan. Findings supplied by your own agent are available on every plan; automated linking requires Improve. On the Free plan monitorsAvailable is false and create_monitor answers Monitors aren't included in your organization's current plan (Free)… instead of creating one. Conversations, transcripts and traces work on every plan.
These are write tools (except the list_* / get_* reads) and return a JSON object that may carry an error key — inspect it, and because writes settle asynchronously, confirm each step with the paired read tool before advancing.

Monitors & scorecards

Manage the AI judges that surface findings (create_monitor / list_monitors / list_starter_monitors are under Onboarding). Use list_monitors to find an ID, then call get_monitor with that ID as monitorId. It returns { monitor: { ...configuration, alert } }. The pipeline is resolved for legacy monitors too; timestamps (analysisStartAt, updatedAt) are ISO strings, and sourceFindingId identifies an originating finding when present. alert includes its enabled state, comparator, threshold, window, sustained days, Slack channel ID, and email recipients; it is null when no alert is configured. API keys are never returned; hasApiKey reports whether one is configured, and aiKeyId is the organization AI provider key the monitor runs on (null otherwise). Reads are uncached and scoped to your organization. Missing or other-organization IDs return a monitor-not-found error. Use get_monitor_results separately for evaluation outputs, and get_monitor_trends for how they move over time.

Finding a conversation by its reference id

To find one call by the id your own system or provider gave it, pass referenceId to list_conversations (or GET /v1/conversations?referenceId=). It is an exact, indexed match on the conversation’s referenceId, so it answers quickly however old the call is; then read the transcript and trace with the returned conversation id. Prefer it to a meta filter on the same value: meta has to read every conversation’s metadata, which is slow for a high-volume organization. createdAfter (inclusive) and createdBefore (exclusive) bound the list by createdAt. Each takes an ISO 8601 date (2026-11-01, read as UTC midnight) or a date-time with a UTC offset (2026-11-01T11:30:00-03:00). Use them to page one day or hour instead of everything newer than it. An invalid value is an error (HTTP 400 on REST).

Filtering conversations by metadata

list_conversations (and GET /v1/conversations) and get_monitor_trends accept meta, the same filter as the dashboard’s Conversations page: key:op[:value] segments joined by ; (up to 8; all must match). key is a dotted path into the conversation’s metadata — call list_conversation_metadata_keys to see which exist. op is one of eq, neq, contains, not_contains, gt, gte, lt, lte (these take a URI-encoded value; the numeric ones need a number) or is_set, is_not_set, is_true, is_false. A filter that does not parse is an error (HTTP 400 on REST), never silently ignored. Metadata property paths are discovered automatically, including nested fields such as contexto.call_id. For an ID stored there, pass meta: "contexto.call_id:eq:1234567890"; numbers and booleans are compared by their text representation for equality. No organization-specific index setup is needed. Selective exact-value filters (eq / neq) use the search index after historical coverage is verified. Common values and other operators retain the JSON query path to avoid large historical candidate sets. Substring operators retain their existing behavior; use a date window to bound their work on large histories. Pass companyIds to create_monitor, create_pipeline_monitor, or update_monitor to target conversations attributed to selected companies, including future agents. Companies must be enabled to create a company scope, IDs must belong to your organization, and at least one company is required. Do not pass agentIds together with companyIds. Omitting both on update preserves the saved scope; list_monitors exposes its scopeType and selected companies. Company edits change visible history without deleting stored results; missing historical evaluations still require opt-in analysis. Each ai_analyze stage in create_pipeline_monitor accepts useAgentPrompt and useCallContext (available CRM data); both default to false on new stages. To edit context, read stage IDs with get_monitor, then call update_monitor with stageContext: [{ stageId: "step-id", useAgentPrompt: false, useCallContext: true }]. Each patch needs a unique existing AI stage ID and at least one boolean option; omitted options are preserved. All supplied edits apply atomically. Context changes increment the monitor version for future evaluations and reset alert breach state; historical results stay intact. The response includes version and, when context is supplied, the updated pipeline. Use update_monitor_pipeline when a rubric needs to change but the monitor’s history should survive. Read the monitor with get_monitor, then pass either instruction (a new yes/no rubric for a single-rubric monitor) or pipeline (the complete edited stage list; reuse a stage’s id to keep it the same stage). Only an organization owner or admin may call it. The monitor keeps its ID, agent or company scope, alert configuration and all stored results, and when scoring changes its version goes up by one and alert breach state is reset. The response returns previousVersion, version, the resolved pipeline and headlineStageId. Editing only outcome labels or tone does not change the version, and resending an identical definition is a no-op. Existing results are not re-judged, deleted or recomputed, and no model credits are spent. They remain stamped with the version that produced them, so the monitor’s history mixes versions across the change; only conversations evaluated after the edit use the new rubric. get_monitor_results returns results from every version, while the per-version views in the Monitors UI keep them apart. To evaluate past conversations against the new rubric, run a historical analysis from the Monitors UI (this does spend credits). Audio monitors have no stage pipeline and cannot be edited this way.

Findings workflow

Beyond create_finding / update_finding, these drive the candidate → open lifecycle and dedup. Everything in this table except set_finding_version_scope requires the owner or admin role, as does delete_finding and renaming through update_finding — see Your role decides what you can do.

Conversation review

flag_call_for_review only queues a conversation; these record the actual review.

Agents (lifecycle)

create_ai_agent / create_human_agent / update_agent plus: merge_agents / unmerge_agents exist too but require an admin (cross-org) key, matching the staff-only merge tools in the web UI.

Receivers (phone numbers)

Integrations & connectors

Provider connect/import is under Provider import. These configure an already-connected integration. Slack (post-connect; OAuth install stays in the web UI): add_slack_channel, remove_slack_channel, set_default_slack_channel, set_slack_channel_chat_enabled, send_slack_channel_test, set_agent_slack_channel — each takes a Slack channel id (C…), and set_agent_slack_channel also an agentId. Linear (post-connect; OAuth install stays in the web UI): list_linear_teams, set_default_linear_team (teamId, nullable), create_linear_issue_for_finding (findingId), create_linear_issue_for_solution (solutionId), unlink_linear_issue (findingId? / solutionId?).

AI provider keys

The organization’s own (bring-your-own) provider keys from Settings → AI providers. Every tool here is owner/admin only, and every tool except list_ai_keys requires the write scope. A secret is write-only: it is checked with a no-cost provider call before it is stored encrypted, and responses carry only lastFour. A success returns { key }. A failure returns { error, code }, where error is a readable message and code is invalid_input, invalid_key (the provider rejected it), provider_unreachable, duplicate_label, not_found, in_use, or phi_mode_blocked. Pass a key’s id as aiKeyId to test_monitor to try a monitor on it, then to set_monitor_model (with the provider’s model id) to put a saved monitor on it.
When a person can paste the key, prefer the Settings → AI providers page: over MCP the secret passes through the agent’s conversation and its client’s logs.

Organization & members

upload_conversation charges one conversation credit, like any upload. A voice conversation also needs durationSeconds (greater than 0, at most 31536000) to be analyzed, because plan minutes are metered by it; for a chat, set channel to text, chat, web-chat, sms, whatsapp or in-app instead, which uses no voice minutes. The response’s analysisSkipReason (plan_limit or no_duration) and message say why a stored conversation was not analyzed. A conversation needs at least 4 turns to be analyzed; a shorter one is stored and readable but skipped by the analysis pipeline (no summary, findings or monitor results). To send conversations from your own code instead of one at a time, POST them to the ingest endpoint with the same key. Every tool in this table except upload_conversation requires the owner or admin role, and update_member_role requires owner — see Your role decides what you can do. The inputs above are the primary fields; the MCP server advertises the full, authoritative schema for each tool via tools/list. Email inputs use regular-language JSON Schema patterns so the advertised tool schemas remain compatible with strict structured-output providers, including OpenAI.

Output shapes & pagination

Tool responses match the REST API exactly. See the API reference for the JSON shapes of Agent, Conversation, Transcript, Review, Bucket, and Finding, plus the { data, nextCursor } pagination envelope. limit clamps to 200 (default 50). cursor is opaque — pass back the nextCursor value from a previous response to fetch the next page. A cursor the API did not issue is an error result with code invalid_parameter (parameter: "cursor"), as on REST, never a silent restart from page 1. Conversations from list_conversations and get_conversation carry analysisStatus: analyzed, pending, skipped_too_short (under 4 turns), skipped_plan_limit (longer than the monthly minutes left when it arrived), skipped_no_duration (a voice conversation sent without a duration) or unknown. It is how an agent that uploads more than the plan allows can tell a conversation was stored but not analyzed. New values may be added later; treat one you do not know as “not analyzed yet”.

Error results

A refusal is a result with isError: true and a JSON body that always has error, plus code, message and hint where there is a next step: not_found (an id that is not in your organization: the get_*, browse_* and monitor tools all answer it, with a hint naming the tool that lists valid ids), invalid_parameter, not_entitled (the plan does not include the feature; the hint says where to upgrade) and not_enabled. Match on code, not on the message text. The browse_* tools behind the interactive views keep their empty shape (for example conversation: null) next to the error fields for an unknown id.

Troubleshooting

  • 401 from every tool — the bearer token is wrong or revoked. Test the key directly: curl -H "Authorization: Bearer $ZELTO_API_KEY" https://api.zelto.ai/v1/agents. If that also returns 401, mint a new key.
  • This credential is read-only and cannot call "<tool>". — the OAuth token was granted the read scope only. Reconnect and grant write, or use an API key. See Read and write scopes.
  • 400 with Batched tool calls are not supported — the client sent a JSON-RPC array. Send one message per POST.
  • Only an organization owner or admin can perform this action. — the tool worked, your role didn’t. Your credential resolves to the member role and the tool administers the organization. Ask an owner or admin to run it or to raise your role; see Your role decides what you can do.
  • Tools list is empty in the client — most clients cache the tool list. Restart the client (Claude Code: /mcp; Cursor: toggle the server off/on; Codex: restart the CLI).
  • 429 rate-limited — back off and retry. Use the cursor pagination instead of fetching large pages.
  • Cross-org access denied — keys are scoped to the org they were minted in. Switch organizations in the web app and mint a new key from that org’s Settings → Integrations.

Recording access

Recording URL fields point to authenticated playback routes. Send the same organization API key or OAuth bearer token when fetching audio; browser playback requires a current signed-in membership. Both mixed and multi-channel recordings follow this rule. Managed recordings use redirects to signed URLs that expire after 15 minutes. Follow the redirect to play or download, and request the original authenticated route again when the signed URL expires. Historical public recording URLs stop working when private storage is enabled. Custom OpenAI-compatible connections: create_ai_key accepts provider: "custom_openai" and customConfig with baseUrl, explicit models, and optional streaming, tools, structuredOutput flags. A synthetic completion per model validates the connection and may incur provider charges. See AI providers.

Support tickets

Your coding agent can file a support ticket, check progress, and add follow-up comments without leaving the conversation. Tickets appear in Support in your organization dashboard. All tools are scoped to the authenticated organization; internal support comments are never returned. Creating tickets and adding comments require write scope; every organization member can use them. Status updates are synchronized from the support system. Include error reference IDs and reproduction steps, never API keys or sensitive call content. After an ambiguous write failure, check existing tickets or the timeline before retrying to avoid duplicates.

Agent feedback

When a capability is missing or a tool blocks the task, your agent can tell the Zelto team directly with send_feedback. Unlike a support ticket, feedback gets no reply and is not stored; it goes to an internal channel. Any credential can call it, including a read-scoped OAuth token, and every organization member can use it. It shares the REST endpoint’s limit of 5 attempts per organization per minute. Use synthetic examples only, report each issue once, and do not retry automatically. See Agent feedback. The server invites feedback in two places: the instructions a client receives when it connects (initialize), and every failed tool call. A tool error result gets an extra text item and a feedback field in structuredContent; a JSON-RPC error (for example Tool <name> not found) gets the invitation appended to its message and in data.feedback. Successful results are unchanged, and send_feedback’s own errors never carry the invitation.

Usage statement

Use get_usage_statement (read-only, optional month as YYYY-MM) to read what your organization is charged for a month. It mirrors GET /api/v1/usage/statement and the Settings → Usage page: amounts are USD micros, with each item as quantity and unit price, the volume tier, free credit, the month-end forecast, the AI spend cap, and the price of every unit at every tier. The tool always uses the authenticated organization. See Plans and limits for how tiers work.

AI usage breakdown

Use get_ai_usage_breakdown (read-only, optional month as YYYY-MM) to see what your organization’s AI usage was spent on in a month. It mirrors GET /api/v1/usage/ai and the breakdown under AI usage at cost on Settings → Usage. The total is the month’s AI usage at cost, and the same amount is broken down by monitor, by activity (monitor runs, backfills, setup, call processing, assistants, simulations), by model (input and output tokens, plus today’s rate per 1M tokens), and by day. Each row includes model calls and approximately how many calls it was spent on. Amounts are USD micros. Use list_invoices (read-only, no arguments) to list your organization’s recent invoices from Stripe and Mercury. It mirrors GET /api/v1/billing/invoices and the invoices on Settings → Billing. Use create_invoice_payment_link (write, owners and admins only, invoiceId from list_invoices) to get a link for one open or paid Stripe invoice that you can send to whoever pays it. The page needs no sign-in and shows only that invoice, its lines and, for agreements that bill AI at cost, what the AI usage was spent on, plus a Pay button. Anyone with the link can view the invoice, and it expires after 30 days. It mirrors POST /api/v1/billing/invoices/{invoiceId}/payment-link and Share link on Settings → Billing.

Shared Free balances

Use get_free_budgets (read-only, no arguments) to inspect your organization’s current USD 5 AI and USD 5 observability balances. It mirrors GET /api/v1/usage: amounts are USD micros, with used, reserved, available, and UTC reset fields. freeBudgets: null means this contract is inactive or your organization is paid. The tool always uses the authenticated organization; it cannot read another org. See Plans and limits for what consumes each balance. Google Gemini keys (provider: "google") can run Benchmarks candidates and LLM judges. Add the key with connect_ai_provider, then select its aiKeyId for a benchmark run. Google keys are not supported by test_monitor or set_monitor_model.