Skip to main content
Connect an MCP client to place and inspect calls. Organizations in the MCP pilot can also let an agent read and draft scenario configuration, edit knowledge bases, review calls and run automated chat tests. MCP complements the dashboard: the agent works on the same scenarios and knowledge bases you see there, with the permissions of the key it uses. It never publishes a prompt; a person does that in the dashboard. Server URL: 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.
Keys are scoped to your account and organization. Generate a separate dashboard key for direct API or SDK access.
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, addScenarioLanguage and removeScenarioLanguage save 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 409 on 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 the updated_at from your last read. If the item changed since, the write fails with 409: read it again and retry. cancelScheduledCall, rescheduleScheduledCall and cancelScenarioTestRun have no such check and take no expected_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, Accept and Accept-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, but deleteScenarioTool can still remove it. Writes that include such values are refused.
  • A custom API tool sends credentials only by reference to a connection. saveScenarioTool keeps 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 with 422 and the dashboard link where a person adds it. createScenario refuses every credential.
  • getScenario never includes credentials, headers, endpoints or the values custom API tools send. A private variable’s default reads as null. Setting one is refused with 422, 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 contains auth, key, token, secret, password, passwd, signature, session, cookie or bearer (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 listIntegrations returns.
  • 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 and sendFeedbackToSarj 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

Capability reads, permission calls:read.
  • A turn’s timestamp is null when no time was recorded for it, and in the corrected transcript also when the call has neither a recording start nor a started_at. Its offset_ms is null when timestamp is, or when the call has no started_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:
  • updateScenario replaces every CRM update entry, connector actions included. Send back the entries getScenario returned to keep them; an entry left out is removed.
  • A new or changed connector action must use a connector, action and inputs that listIntegrations lists, 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 answer 422; most messages include the dashboard link to use.
  • getScenario names each action with hidden inputs in locked_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 with 409 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: live tests 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.
  • score is 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 with getCallAnalysis once the analysis finishes. With score: false the call gets no analysis. A rerun keeps the setting.
  • Checks: tool_called, reply_contains, reply_not_contains, knowledge_base_returned, conversation_ended and judge. A judge check 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, getCallTranscript and getCallAnalysis. listCalls leaves 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 with 409 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:
Requests without a valid key are refused with 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.
A tool call with an argument the tool does not declare fails before anything is sent. The tool error names the arguments:

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.
Last modified on November 17, 2026