> For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://docs.sarvam.ai/llms.txt. > For full documentation content in one file, see https://docs.sarvam.ai/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server. # MCP Server > Connect Claude, Cursor, VS Code, and other AI clients to Sarvam Voice Agents over MCP to build, deploy, test, and analyse voice agents from your assistant. 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](https://modelcontextprotocol.io) 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 | Area | What you can do | | ------------------- | ------------------------------------------------------------------------------------------------------------------------- | | **Agents** | Create, clone, and configure agents (prompt, variables, tools, knowledge, voice, settings), and commit immutable versions | | **Telephony** | Connect providers, onboard numbers, run inbound deployments, and test an agent over a real call | | **Campaigns** | Create outbound campaigns, upload cohorts, and run the campaign lifecycle | | **Evals** | Define test suites and scenarios, run them against a committed version, and read the results | | **Knowledge bases** | Create knowledge bases, upload files, and run retrieval search | | **Boards** | Build custom analytics boards: widgets, SQL, filters, and scheduled deliveries | | **Analytics** | Pull 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](https://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 #### Add the server to your client Register `https://mcp.sarvam.ai/voice-agents` as an HTTP MCP server. Pick your client below. #### Claude Code Run this in your terminal, not inside a `claude` session: ```bash 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`. #### Cursor Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json { "mcpServers": { "sarvam-voice-agents": { "type": "http", "url": "https://mcp.sarvam.ai/voice-agents" } } } ``` Then open **Cursor Settings → MCP** and confirm the server is listed. #### VS Code Add to `.vscode/mcp.json` in your workspace: ```json { "servers": { "sarvam-voice-agents": { "type": "http", "url": "https://mcp.sarvam.ai/voice-agents" } } } ``` Reload the window, then start the server from the MCP view. #### Claude Desktop Open **Settings → Connectors → Add custom connector**, name it `Sarvam Voice Agents`, and paste the URL: ``` https://mcp.sarvam.ai/voice-agents ``` #### Other clients Any client that speaks the streamable-HTTP transport works. Use this server entry: ```json { "mcpServers": { "sarvam-voice-agents": { "type": "http", "url": "https://mcp.sarvam.ai/voice-agents" } } } ``` #### 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. #### Verify Ask your assistant to do something read-only, and check that the tool call is labelled with the server name: **`wrap`** ```text 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). | Tool | Covers | | ---------------- | ----------------------------------------------------------------------------------------- | | `agents` | List and read agents and voices; commit and translate a draft, and delete a template tool | | `telephony` | List connections, onboarded numbers, and inbound deployments; run their lifecycle | | `campaigns` | List campaigns and cohorts; run the campaign lifecycle | | `evals` | List test suites, scenarios, and runs; read run results | | `knowledge_base` | List knowledge bases and files; inspect what an agent retrieves | | `boards` | List boards, widgets, filters, and schedules; run their lifecycle | | `analytics` | Run reports, fetch an interaction trace or transcript, and read insights and issues | | `workflows` | List 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: | Resource | What it carries | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `sarvam://playbooks/index` | Which 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-config` | The 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-config` | A 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: | Symptom | Cause | Fix | | ------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `'Failed to connect'` or a `404` | Wrong URL, or a client that dropped the path | Confirm 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 missing | The surface is filtered to your workspace's plan | A tool, operation value, or config field your plan does not include is absent rather than refused. Contact [developer@sarvam.ai](mailto:developer@sarvam.ai) if you believe something should be available | | Calls start failing with a rate-limit error | Too many requests in a short window, often a loop paging a large list | The 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 | #### Status shows 'needs authentication' 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. #### I need to work in a different workspace A connection is fixed to the workspace your login resolves to. Remove the connector and reconnect with a login for the other workspace. #### A write was rejected 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. ## Related pages * [Quickstart](/conversations/quickstart): build your first agent in the dashboard * [Deploy with Code (API & SDK)](/conversations/deploy/deploy-with-code): integrate programmatically * [Tools](/conversations/build/tools): the tools you give an agent * [Agent versioning](/conversations/build/agent/versioning): drafts, commits, and versions * [API Reference](/conversations/api/introduction): the REST API behind the platform