https://platform-api.sarj.ai/api/v1/mcp (with or without a trailing slash)
Use the server that matches the task:
The documentation server cannot place calls. Mintlify also exposes a documentation-feedback tool; it does not control calls. The published agent skill explains identifiers, result readiness, and retry constraints.
Prerequisites
- A Sarj.ai account: sign in at platform.sarj.ai
- An MCP-compatible client (Claude Code, Cursor, or any MCP SDK)
- For pilot tools: an organization in the MCP pilot and a key with the permissions listed below
1
Connect your MCP client
Add the Sarj.ai MCP server to your client. Sign in, or send a dashboard API key in a header.Leave out
headers to sign in instead.2
Authenticate
The server offers four sign-in scopes:
calls:read, calls:write, scenarios:read and scenarios:write. Claude Code requests them when you sign in, and the sign-in page lists each one before you approve. A client that requests no scope gets calls:read and calls:write; any other scope fails with invalid_scope. Each authorization code works once: a second exchange fails with invalid_grant and revokes the key, so sign in again. Sign in again when the key expires. A sign-in key works only on the public API, MCP included: the dashboard’s own routes refuse it with 401, whatever its scopes. Other clients send a dashboard key as Authorization: Bearer <key>.Give the key only the permissions the agent needs. A key never receives a permission you do not have. Keys created before you could choose permissions cannot use pilot tools; create a new key. Revoked and expired keys cannot open MCP requests.3
Prompt your agent
Example prompts:Replace the illustrative UUID with an active scenario ID copied from your dashboard. Confirm the recipient numbers before asking the agent to place real calls.
How changes reach calls
- Prompts and languages are drafts.
saveScenarioPrompt,addScenarioLanguageandremoveScenarioLanguagesave a draft. New calls keep the published prompt until a person publishes the draft in the dashboard. There is no publish tool. - Settings change only on scenarios that are not live. Scenario settings, tools, quality flags, CRM updates and recording destinations are refused with
409on a live scenario; make those changes in the dashboard. On other scenarios they apply to new calls at once. A persona cannot change while a live scenario uses it. - Creating is always allowed. A new scenario starts active and not live. A new persona is not used until a scenario is set to use it.
- Knowledge base edits apply at once. A replace or restore affects every scenario that uses the knowledge base, live or not. Calls that start after it returns use the new text; a call already in progress may keep the earlier text.
- Configuration edits are checked against what you read. Tools that change an existing scenario, prompt, tool, persona or knowledge base file declare
expected_updated_at: send theupdated_atfrom your last read. If the item changed since, the write fails with409: read it again and retry.cancelScheduledCall,rescheduleScheduledCallandcancelScenarioTestRunhave no such check and take noexpected_updated_at.
Secrets stay out of the model
- Tools refer to connections your organization already has, by id. Values that could be secrets read back as null: fixed header values other than
Content-Type,AcceptandAccept-Language, every fixed query value, an endpoint with a query string or a user name or password, keys, tokens and encrypted values. A tool that holds one is not editable through MCP and can change only in the dashboard, butdeleteScenarioToolcan still remove it. Writes that include such values are refused. - A custom API tool sends credentials only by reference to a connection.
saveScenarioToolkeeps a credential only when the stored tool with the same name already sends that same credential to the same host, written out in the endpoint. A new credential, or a credential sent to another host, is refused with422and the dashboard link where a person adds it.createScenariorefuses every credential. getScenarionever includes credentials, headers, endpoints or the values custom API tools send. A private variable’s default reads as null. Setting one is refused with422, and sending the variable back as read keeps the stored default; a person sets it in the dashboard. A variable is private when a custom API tool sends it anywhere (path, header, query or body), or when its name containsauth,key,token,secret,password,passwd,signature,session,cookieorbearer(any case).- A connector action leaves out inputs whose fixed values could carry secrets: encrypted values, inputs sent in a header, query, path or cookie, and inputs with names like those above. See Connector actions.
- A person connects integrations and enters secrets in the dashboard, through the links
listIntegrationsreturns. - MCP results never include recording links.
Pilot capabilities
Sarj enables pilot tools for each organization in groups called capabilities. There is no dashboard switch: ask your Sarj contact to enable the capabilities you need. During the pilot, Sarj can also limit the tools to named users. Your client lists only the pilot tools that your key and organization can use. Call tools andsendFeedbackToSarj need no capability.
Available tools
Calls
Schedule-config creation is currently a REST/SDK operation, not an action MCP tool. Reports are asynchronous and can remain null; do not poll indefinitely or infer webhook outcome types from call-status names.
Call history
Capabilityreads, permission calls:read.
- A turn’s
timestampis null when no time was recorded for it, and in the corrected transcript also when the call has neither a recording start nor astarted_at. Itsoffset_msis null whentimestampis, or when the call has nostarted_at. - Polling again does not fill in a null time. Times change only when the corrected transcript replaces the live one after post-call analysis.
Scenarios
updateScenario, updateScenarioQualityFlags, saveScenarioTool and deleteScenarioTool work only on scenarios that are not live.
Prompts and languages
Saving fails with
409 while language changes already wait for publishing. Publish or discard them in the dashboard first.
Personas
Knowledge bases
- The content a write replaces is kept as a new revision, so a restore can undo it.
- Until the file is reindexed in the background, calls that search knowledge bases in that file’s language use keyword matching.
- Text over the knowledge base size limit is refused with
knowledge_base_file_content_too_large.
Integrations
Connector actions
A connector is a custom integration registered on the dashboard’s integrations page.listIntegrations lists each connector with its actions; each action lists its inputs with where the request sends them, their type and whether they are required. Connectors can be off in an environment: the list is then empty, and new connector actions are refused.
A scenario’s CRM updates (post_call_sync) can run connector actions after each call:
updateScenarioreplaces every CRM update entry, connector actions included. Send back the entriesgetScenarioreturned to keep them; an entry left out is removed.- A new or changed connector action must use a connector, action and inputs that
listIntegrationslists, and take credentials only from your organization’s connections and integrations. A fixed value for an input that could carry a secret is refused. These refusals answer422; most messages include the dashboard link to use. getScenarionames each action with hidden inputs inlocked_connector_actions, with its connector, action and the inputs left out. Send it back unchanged to keep it as stored, hidden values included. Any other change fails with409 connector_action_not_editable; make it in the dashboard.
Automated chat tests
- The real agent answers each typed turn with the scenario’s current configuration. By default (
version: draft) it tests the latest saved draft, so a change can be checked before anyone publishes it.version: livetests the published prompt. Without an unpublished draft, a draft test uses the published prompt. Real calls keep using the published prompt. - Tests are typed chats only. They do not test speech recognition, voice or telephony quality.
- Tools, integrations and webhooks are replaced by mocks, so nothing external runs. A test call never sends webhooks, CRM updates or connector actions, never books a callback, gets no insight tagging, and stays out of customer metrics.
scoreis on by default: the run’s call gets post-call analysis, with the data it collected, its outcome against the success criteria, caller experience and quality flags. Read it withgetCallAnalysisonce the analysis finishes. Withscore: falsethe call gets no analysis. A rerun keeps the setting.- Checks:
tool_called,reply_contains,reply_not_contains,knowledge_base_returned,conversation_endedandjudge. Ajudgecheck is a model’s judgment of a rubric and names the judge model. - A run has up to 20 turns, 20 checks and 300 seconds (120 by default). An organization can have 2 runs queued or running at once; another start fails with
409 scenario_test_concurrency_limit. - A run’s call id is a plain UUID, like every call id, and works with
getCall,getCallTranscriptandgetCallAnalysis.listCallsleaves test calls out.
Feedback to Sarj
- An AI agent should send feedback when no tool can do the task (
missing), a tool failed or returned something wrong (broken), a tool or its result was unclear (confusing), or the user suggests an improvement or asks it to send feedback (idea). - It should send feedback at most once per task, never to log progress or to test the tool, and tell the user it sent it.
- The description says what the user wanted and what was missing in general terms, in up to 2,000 characters, with the tool’s name when there is one. It must leave out secrets, credentials, phone numbers, call transcripts and other customer data. Saudi phone numbers that slip through are masked to their last four digits before the feedback is stored.
- Any active dashboard or sign-in key of an organization can send feedback, with no capability or permission. A call-service key, or an expired or revoked key, is refused with
401. Each key can send 20 in any 24 hours; the next one fails with409 feedback_limit_reached. - Only Sarj’s team reads feedback. It does not reach your organization.
Errors
A failed tool call returns the HTTP status and the API error body as text in the tool result, for example:401 before any tool runs. A 403 answers error.type forbidden with its code in error.message. A 409 from a pilot tool or sendFeedbackToSarj answers error.type conflict with its code in error.code; error.message starts with the code, sometimes followed by ; and a hint. A 422 from a pilot tool answers error.type validation_error. Call tools keep their own error types, such as call_not_pending. Branch on error.type and error.code, not on the message text.
Data handling
- Transcripts and call analysis are your customers’ conversations. Treat what the agent reads, and where your client stores it, with the same care as the dashboard.
- MCP results contain no audio and no recording links. Use the dashboard or the REST API for recordings.
- Changes made through MCP are recorded as made by the user who owns the key.

