> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaanivoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use the Vaani MCP Server to expose Vaani Voice AI APIs as tools over the Model Context Protocol — manage agents, calls, transcripts and campaigns from any MCP client

## 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.

<Note>
  You need a Vaani API key (`vaani_...`). Generate one from the Vaani Dashboard → API Keys.
  See [Generate API Key](/getting-started/generate-api-key).
</Note>

## Quickstart: Claude Desktop Config

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

<Steps>
  <Step title="Get your Vaani API key">
    Generate a key from the Vaani Dashboard → API Keys.
  </Step>

  <Step title="Edit Claude Desktop config">
    Open **Settings** → **Developer** tab → **Edit Config**.
  </Step>

  <Step title="Add the Vaani MCP server block">
    Insert this into your `claude_desktop_config.json`, replacing `vaani_...` with your API key:

    ```json theme={null}
    {
      "mcpServers": {
        "vaani": {
          "command": "npx",
          "args": ["-y", "vaani-research-mcp"],
          "env": { "VAANI_API_KEY": "vaani_..." }
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Desktop">
    Save and restart Claude Desktop.
  </Step>
</Steps>

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

**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`.

<Warning>
  `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.
</Warning>

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

***

## Integration Options

#### Local (stdio)

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

```bash theme={null}
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`).

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

#### Claude Code

```bash theme={null}
claude mcp add vaani --env VAANI_API_KEY=vaani_... -- npx -y vaani-research-mcp
```

#### Cursor

Settings → MCP → Add new global MCP server:

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

#### VS Code (Copilot MCP)

Add to `.vscode/mcp.json`:

```json theme={null}
{
  "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:

* [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)
* [Python](https://github.com/modelcontextprotocol/python-sdk)
* [Java](https://github.com/modelcontextprotocol/java-sdk)
* [Kotlin](https://github.com/modelcontextprotocol/kotlin-sdk)
* [C#](https://github.com/modelcontextprotocol/csharp-sdk)

#### 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

```javascript theme={null}
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();
```

<Note>
  For more detailed examples and complete client implementations, see the
  [MCP Client Quickstart](https://modelcontextprotocol.io/quickstart/client). To inspect the
  server interactively, run it under the MCP Inspector:
  `VAANI_API_KEY=vaani_... npx @modelcontextprotocol/inspector npx -y vaani-research-mcp`.
</Note>

## References

* [npm package](https://www.npmjs.com/package/vaani-research-mcp)
* [GitHub repo](https://github.com/mohammad-vaaniresearch/vaani-mcp)
* [Model Context Protocol docs](https://modelcontextprotocol.io)
* [API reference](/api-reference/introduction)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.