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 iszelto-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 endpointhttps://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 athttps://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:
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: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):
/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]:
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:
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:
~/.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:
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 theowner 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. Impliesread.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 issend_feedback, which any credential can call (see Agent feedback).- No access scope — tokens minted before scopes existed keep full access.
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 matchingbrowse_*
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’sviewargument 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.
{ "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_alertto 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.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 aprovider 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.
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:
get_onboarding_status— readnextIncompleteto resume from the right step.connect_provider— passprovider(vapi,retell,speechify,telnyx,elevenlabs, orkapso) and give the returned browser link to the operator. Confirm completion withcheck_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 withlist_conversations. For AI-model or STT keys, useconnect_ai_providerinstead.create_monitor— pass astarterKeyfromlist_starter_monitors, alibraryKeyfromlist_metric_library, or aname+ a natural-language booleaninstruction. Omitting bothagentIdsandcompanyIdsapplies it to every current agent. Confirm withlist_monitors. Tool-execution checks (tool_check— didsubmit_orderactually fire) are authored in the Monitors editor;create_monitorstill creates an AI yes/no rubric.set_findings_delivery—channelsis any ofemail/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.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, passreferenceId 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
Beyondcreate_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 exceptlist_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.
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 ofAgent,
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 withisError: 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
401from 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 returns401, mint a new key.This credential is read-only and cannot call "<tool>".— the OAuth token was granted thereadscope only. Reconnect and grantwrite, or use an API key. See Read and write scopes.400withBatched tool calls are not supported— the client sent a JSON-RPC array. Send one message perPOST.Only an organization owner or admin can perform this action.— the tool worked, your role didn’t. Your credential resolves to thememberrole 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). 429rate-limited — back off and retry. Use thecursorpagination 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 withsend_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
Useget_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
Useget_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.
Invoices and payment links
Uselist_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
Useget_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.
