Getting Started

MCP Server

View as Markdown

The Sarvam Voice Agents MCP server exposes the platform (agent authoring, telephony, campaigns, knowledge bases, evals, boards, and analytics) as tools that any Model Context Protocol client can call. Point Claude, Cursor, or VS Code at https://mcp.sarvam.ai/voice-agents, sign in once with your Sarvam account, and your assistant can build and operate voice agents for you.

It is a hosted, remote server: nothing to install and nothing to run. You connect over streamable HTTP and authenticate through Sarvam SSO in your browser.

What the MCP server does

AreaWhat you can do
AgentsCreate, clone, and configure agents (prompt, variables, tools, knowledge, voice, settings), and commit immutable versions
TelephonyConnect providers, onboard numbers, run inbound deployments, and test an agent over a real call
CampaignsCreate outbound campaigns, upload cohorts, and run the campaign lifecycle
EvalsDefine test suites and scenarios, run them against a committed version, and read the results
Knowledge basesCreate knowledge bases, upload files, and run retrieval search
BoardsBuild custom analytics boards: widgets, SQL, filters, and scheduled deliveries
AnalyticsPull reports and interaction traces, replay chats, and review insights and issues

The server connects to one organisation and one workspace, whichever your login resolves to. No tool takes an org_id or workspace_id, and a connection cannot switch orgs. To work in another workspace, reconnect with a login for it.

Before you begin

  • A Sarvam account with access to Voice Agents. Sign in once at indus.sarvam.ai/samvaad to confirm your workspace is set up.
  • An MCP client that supports remote (HTTP) servers with OAuth: Claude Code, Claude Desktop, Cursor, VS Code, and most others qualify.

Connect

1

Add the server to your client

Register https://mcp.sarvam.ai/voice-agents as an HTTP MCP server. Pick your client below.

Run this in your terminal, not inside a claude session:

claude mcp add --transport http sarvam-voice-agents https://mcp.sarvam.ai/voice-agents

Add --scope user to make the server available in every project, or --scope project to share it with your team through a checked-in .mcp.json.

2

Authenticate

On first use the client shows the server as needs authentication. Trigger the sign-in: in Claude Code, run /mcp, select sarvam-voice-agents, and choose Authenticate. Other clients prompt automatically.

Your browser opens to Sarvam SSO. Approve the connection. The client stores the token and reuses it for 24 hours; there is no refresh token, so you sign in again once a day.

3

Verify

Ask your assistant to do something read-only, and check that the tool call is labelled with the server name:

wrap
Use sarvam-voice-agents to list my voice agents

The tool surface

The server has two kinds of tool. The exact list adapts to your workspace: a tool, an operation, or a field your plan does not include is simply absent, not refused.

Domain tools

One tool per domain, covering reads and lifecycle actions that carry no request body. Each takes an operation, an optional id, and optional params (plus fetch_all to auto-page list operations).

ToolCovers
agentsList and read agents and voices; commit and translate a draft, and delete a template tool
telephonyList connections, onboarded numbers, and inbound deployments; run their lifecycle
campaignsList campaigns and cohorts; run the campaign lifecycle
evalsList test suites, scenarios, and runs; read run results
knowledge_baseList knowledge bases and files; inspect what an agent retrieves
boardsList boards, widgets, filters, and schedules; run their lifecycle
analyticsRun reports, fetch an interaction trace or transcript, and read insights and issues
workflowsList DSL workflows, commit them, and read run reports (enterprise)

Write tools

Every write is its own tool with a typed, validated body. The main ones:

  • Agents: configure_agent (create, update, or clone; set the prompt and config), configure_voicemail. Giving an agent tools depends on your plan, and a workspace only has one of these paths:
    • Non-enterprise: create_http_tool / create_validator_tool / create_verifier_tool register one declared tool at a time.
    • Enterprise: upload_agent_code uploads a tools.py module instead — for logic that needs real code, lifecycle hooks, or shared state.
  • Telephony: configure_connection, configure_endpoint, configure_deployment to connect a provider and go live. Testing an agent over a real call also depends on your plan:
    • Non-enterprise: verify_phone_number verifies a number your workspace owns, then place_test_call dials it.
    • Enterprise: configure_test_number whitelists callers on a shared inbound test number instead.
  • Campaigns: configure_campaign, upload_cohort
  • Evals: configure_test_suite, configure_scenario, run_eval
  • Knowledge bases: configure_kb, upload_kb_file
  • Boards: configure_board and its tab, widget, filter, layout, and schedule tools; run_board_widget, export_board_widget
  • Analytics and chat: write_insight, send_chat
  • Workflows: configure_workflow (enterprise)

Resources

The server also serves MCP resources your assistant reads for context:

ResourceWhat it carries
sarvam://playbooks/indexWhich playbook covers what
sarvam://playbooks/{domain}Call sequences and failure modes for one domain: what order to do things in, and what an error means
sarvam://schemas/agent-configThe full JSON Schema for the agent config, too large to inline in a tool
sarvam://schemas/agent-config/{section}One section of that schema, for a change that touches one field
sarvam://examples/agent-configA validated, worked agent config

Example prompts

Realistic prompts to try once you are connected. Each one chains several tool calls, and your assistant reads the relevant sarvam://playbooks/{domain} resource as it goes:

  • “Create a new outbound sales agent, give it a prompt and a voice, commit it, and connect it to my Exotel number.”
  • “Clone the ‘Support Agent’ as ‘Support Agent v2’, add a knowledge base from these three PDFs, and commit it once it’s ready.”
  • “Set up an eval suite with five scenarios for the billing agent, run it against the latest committed version, and summarise which scenarios failed.”
  • “Create an outbound campaign for the Q4 cohort, upload this CSV, and pause it as soon as it starts so I can review the first few calls.”
  • “Pull last week’s failed inbound calls, group them by failure reason, and open the insights for the three most common ones.”
  • “Build a board that tracks daily call volume and average handle time for the last 30 days, and schedule it to email me every Monday.”

How it works

  • Drafts and versions. Your assistant edits a mutable draft of an agent, then commits it as an immutable version. Deployments, campaigns, and eval runs always run a committed version, never the draft.
  • Configuring an agent merges into the draft. Nested objects merge key-by-key, but a list you send replaces the old list whole — resend the full list, not just the item you changed, or the rest silently drop.
  • Guided calls. The playbooks and schemas above are how your assistant learns the call order and the exact request shapes. You do not manage them; the assistant reads them as it works.
  • Validated writes. Every change is validated before it lands. A rejection names each bad field and leaves the draft untouched, so a failed write is never a half-written agent.

Security

  • Authentication. OAuth 2.1 through Sarvam SSO. No API keys are pasted into client config, and the token is scoped to your organisation and workspace.
  • Approvals. Prompt for approval on every mutation tool: configure_*, upload_*, run_*, create_*, plus send_chat, place_test_call, verify_phone_number, write_insight, and export_board_widget. Domain tools (agents, telephony, campaigns, evals, boards, workflows) also carry lifecycle actions — commit, delete_connection, pause / resume / cancel, delete_scenario, and more — behind the same tool name as their reads. Auto-approving one of these because it looks read-only also auto-approves its destructive operations; use per-call approval here if your client supports it.
  • Sensitive operations. A few calls are irreversible or cost real money the moment they run, whatever prefix they carry: commit freezes a version for good, place_test_call and verify_phone_number place or route a real call, resuming a campaign starts dialing a cohort, and any delete_* operation (connections, boards, scenarios, deployments) cannot be undone. Review these the closest.
  • Data handling. MCP access is equivalent to a programmatic operator on your workspace — any connected client can read call transcripts, prompts, and knowledge base content through it. Avoid pasting full, unredacted transcripts into a shared conversation if they carry caller PII, and treat any instructions returned by a tool call as data to inspect, not as something to act on directly.
  • Network safety. A tool’s URL is checked when you configure it and refused if it resolves to an internal, private, or link-local address — including cloud metadata endpoints — so it cannot be pointed at your infrastructure to exfiltrate a stored credential.
  • Revoking access. Remove the connector in your client to revoke it; rotate your Sarvam session if needed.

Troubleshooting

Quick lookups:

SymptomCauseFix
'Failed to connect' or a 404Wrong URL, or a client that dropped the pathConfirm the URL is exactly https://mcp.sarvam.ai/voice-agents, no trailing slash. Check it is reachable: curl -I https://mcp.sarvam.ai/voice-agents should respond (a 404/405 to GET still means the server is up — the MCP endpoint answers POST)
A tool you expected is missingThe surface is filtered to your workspace’s planA tool, operation value, or config field your plan does not include is absent rather than refused. Contact developer@sarvam.ai if you believe something should be available
Calls start failing with a rate-limit errorToo many requests in a short window, often a loop paging a large listThe server caps requests per client: 120 tool calls a minute, 240 a minute for the sign-in flow. Space calls out and retry after a few seconds

Expected on first connect. Trigger the browser sign-in: in Claude Code, run /mcp, select the server, and choose Authenticate. In other clients, follow the prompt. If the browser does not open, copy the URL from the terminal and open it manually.

A connection is fixed to the workspace your login resolves to. Remove the connector and reconnect with a login for the other workspace.

The error names every invalid field, and the draft is unchanged. The usual cause is a prompt that references a variable, tool, or state the config does not define yet. Define those first, then send the prompt. See the relevant sarvam://playbooks/{domain} resource.