MCP Server

Overview

The Vaani MCP Server (vaani-research-mcp) exposes Vaani Voice AI APIs as tools via the Model Context Protocol (MCP), so you can create agents, trigger calls, read transcripts and run campaigns from any MCP-compatible assistant (like Claude Desktop) or agent framework. It runs locally over stdio — no hosted infrastructure needed. Use it to connect your AI workflows to real-world telephony, automate voice tasks, and build richer conversational agents.

You need a Vaani API key (vaani_...). Generate one from the Vaani Dashboard → API Keys. See Generate API Key.

Quickstart: Claude Desktop Config

Fastest way to get started: connect Claude Desktop to the Vaani MCP Server.

Get your Vaani API key

Generate a key from the Vaani Dashboard → API Keys.

Edit Claude Desktop config

Open Settings → Developer tab → Edit Config.

Add the Vaani MCP server block

Insert this into your claude_desktop_config.json, replacing vaani_... with your API key:

{
  "mcpServers": {
    "vaani": {
      "command": "npx",
      "args": ["-y", "vaani-research-mcp"],
      "env": { "VAANI_API_KEY": "vaani_..." }
    }
  }
}

Restart Claude Desktop

Save and restart Claude Desktop.

Claude Desktop on Windows may need "command": "cmd" with "args": ["/c", "npx", "-y", "vaani-research-mcp"].

Example prompt:

“Create a friendly Hindi appointment-reminder agent, then call +919876543210 with it.”

Core Tools

The Vaani MCP Server exposes these actions as MCP tools:

Tool	Description	Example Usage
`create_agent`	Create a new voice agent from a display name + system prompt	Add a new agent for a use case
`update_agent_section`	Update one section: `persona`, `training`, `experience`, `analysis`, `deployment`	Change an agent’s tone or guardrails
`trigger_call`	Place a real outbound call (`agent_id`, `contact_number`, `name`, `metadata`, `modify_agent`)	Call a customer with an agent
`start_webrtc_session`	Start a browser/app voice session; returns `token`, `room_name`, `connection_url`	Open a live voice session
`list_calls`	List calls (paged, optional `agent_id` filter)	Review call activity
`get_call_details`	Summary, entities and evaluation for one call	Check result of a call
`get_call_transcript`	Full transcript for one call (truncated with a note when long)	Read what was said on a call
`create_campaign`	Create an outbound campaign	Launch a reminder campaign
`campaign_action`	`start` / `pause` / `resume` / `cancel` a campaign	Pause a running campaign

Also bundled:

Resource vaani://docs — links to every page of this API reference.
Prompt build_voice_agent — guides agent design (use case, language, tone, guardrails, disposition fields) before calling create_agent.

trigger_call, campaign start and campaign cancel place real calls that cost real money. Confirm the target number and agent with the user before calling. Phone numbers are validated as E.164 before anything is sent.

create_campaign currently sends JSON, but POST /api/campaigns/create requires multipart/form-data with a csv_file upload (see Create Campaign). File-upload support is planned — until then, create campaigns via the API or dashboard.

Integration Options

Local (stdio)

Run the MCP server on your own machine. No install needed — clients launch it on demand:

npx -y vaani-research-mcp

Requirements: Node.js 18+. Authentication: VAANI_API_KEY environment variable. Optional: VAANI_API_BASE to override the API URL, VAANI_READ_ONLY=true to expose only the read-only tools (list_calls, get_call_details, get_call_transcript).

Use this for clients or SDKs that support local command-based (stdio) MCP servers.

Claude Code

claude mcp add vaani --env VAANI_API_KEY=vaani_... -- npx -y vaani-research-mcp

Cursor

Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "vaani": {
      "command": "npx",
      "args": ["-y", "vaani-research-mcp"],
      "env": { "VAANI_API_KEY": "vaani_..." }
    }
  }
}

VS Code (Copilot MCP)

Add to .vscode/mcp.json:

{
  "servers": {
    "vaani": {
      "command": "npx",
      "args": ["-y", "vaani-research-mcp"],
      "env": { "VAANI_API_KEY": "vaani_..." }
    }
  }
}

Custom MCP Client Integration

You can use any MCP-compatible client (SDKs available for multiple languages).

Install an MCP client SDK

Choose a language:

Configure your connection

Connect over stdio by spawning npx -y vaani-research-mcp with VAANI_API_KEY set.

Use MCP tools

List tools, create agents, trigger calls, read transcripts — via your SDK.

Example: query tools with Node.js

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "vaani-research-mcp"],
  env: { ...process.env, VAANI_API_KEY: process.env.VAANI_API_KEY },
});

const client = new Client({ name: "vaani-example", version: "1.0.0" });
await client.connect(transport);

// Discover tools
const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

// Create an agent
const created = await client.callTool({
  name: "create_agent",
  arguments: {
    agent_display_name: "support-bot",
    system_prompt: "You are a helpful customer support agent.",
  },
});
console.log(created.content[0].text);

await client.close();

For more detailed examples and complete client implementations, see the MCP Client Quickstart. To inspect the server interactively, run it under the MCP Inspector: VAANI_API_KEY=vaani_... npx @modelcontextprotocol/inspector npx -y vaani-research-mcp.

Getting Started

Guides

Overview

Quickstart: Claude Desktop Config

Core Tools

Integration Options

Local (stdio)

Claude Code

Cursor

VS Code (Copilot MCP)

Custom MCP Client Integration

Install an MCP client SDK

Configure your connection

Use MCP tools

Example: query tools with Node.js

References

​Overview

​Quickstart: Claude Desktop Config

​Core Tools

​Integration Options

​Local (stdio)

​Claude Code

​Cursor

​VS Code (Copilot MCP)

​Custom MCP Client Integration

​Install an MCP client SDK

​Configure your connection

​Use MCP tools

​Example: query tools with Node.js

​References

Overview

Quickstart: Claude Desktop Config

Core Tools

Integration Options

Local (stdio)

Claude Code

Cursor

VS Code (Copilot MCP)

Custom MCP Client Integration

Install an MCP client SDK

Configure your connection

Use MCP tools

Example: query tools with Node.js

References