mcp-vapi

MCP server for VAPI (Voice AI Platform) integration - Build and manage AI-powered voice calls through Claude.

Overview

mcp-vapi is a Model Context Protocol (MCP) server that enables Claude to interact with VAPI's voice AI platform. With this server, Claude can create phone calls, manage call sessions, and retrieve call analytics.

Features

Core Capabilities

• Create Phone Calls: Initiate outbound calls with AI assistants
• Manage Calls: End active calls, retrieve call details
• Call Analytics: List calls with pagination, get transcripts and metadata
• Assistant Management: Create, update, and manage AI assistants
• Phone Number Management: List and manage VAPI phone numbers
• Advanced Analytics: Access call transcripts, metrics, and recordings
• Call Routing: Configure business hours and after-hours routing
• Webhook Support: Deploy as AWS Lambda for VAPI webhook integration

Prerequisites

Before using this MCP server, you need:

1. VAPI Account: Sign up at vapi.ai
2. API Key: Get your API key from the VAPI dashboard
3. Assistant ID: Create at least one assistant in VAPI to handle calls

Installation

NPM Installation (Recommended)

# Install globally
npm install -g @chinchillaenterprises/mcp-vapi

# Or use with npx
npx @chinchillaenterprises/mcp-vapi

Add to Claude

claude mcp add vapi -s user -e VAPI_API_KEY=your-api-key -- npx @chinchillaenterprises/mcp-vapi

Local Development Installation

# Clone and build
cd mcp-vapi
npm install
npm run build

# Add to Claude
claude mcp add vapi-dev -s user -e VAPI_API_KEY=your-api-key -- node /absolute/path/to/mcp-vapi/dist/index.js

Manual Configuration

Edit your Claude configuration file:

{
  "mcpServers": {
    "vapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@chinchillaenterprises/mcp-vapi"],
      "env": {
        "VAPI_API_KEY": "your-vapi-api-key"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | VAPI_API_KEY | Yes | Your VAPI API key for authentication |

Available Tools

vapi_create_phone_call

Create a new outbound phone call with an AI assistant.

Parameters:

• phoneNumber (required): Phone number to call in E.164 format (e.g., "+1234567890")
• assistantId (required): VAPI Assistant ID to handle the call
• metadata (optional): Key-value pairs for call metadata

Example:

Create a phone call to +1234567890 using assistant ID abc123

vapi_get_call

Get detailed information about a specific call.

Parameters:

• callId (required): VAPI Call ID to retrieve

Example:

Get details for call ID call_xyz789

vapi_get_call_details

Get full details and transcript of a specific call.

Parameters:

• callId (required): VAPI Call ID to retrieve

Returns:

• Complete transcript (conversation between AI and caller)
• Recording URL (if recording is enabled)
• AI responses with timestamps
• Duration (total call time in seconds)
• Cost breakdown (per-minute charges, transcription costs, etc.)

Example:

Get full details and transcript for call ID call_xyz789
Show me the complete conversation from the last call
Get recording and cost breakdown for call_abc123

vapi_list_calls

List all phone calls made through VAPI with filtering options.

Parameters:

• limit (optional): Maximum number of calls to return (default: 20)
• status (optional): Filter by call status (completed/in-progress/failed)
• offset (optional): Offset for pagination (default: 0)

Returns:

• Call IDs
• Duration (in seconds)
• Cost (in USD)
• Timestamps (created, started, ended)
• Phone numbers (from and to)

Example:

List the last 10 calls
List all completed calls
Show failed calls from today

vapi_end_call

End an active call.

Parameters:

• callId (required): VAPI Call ID to end

Example:

End the call with ID call_xyz789

vapi_create_assistant

Create a new AI assistant in VAPI.

Parameters:

• name (required): Name of the assistant
• model (optional): LLM model to use (default: "gpt-3.5-turbo")
• voice (optional): Voice to use (default: "jennifer-playht")
• systemPrompt (optional): System prompt for the assistant
• firstMessage (optional): First message the assistant says
• metadata (optional): Key-value pairs for assistant metadata

Example:

Create a customer support assistant named "Support Bot" with GPT-4

vapi_list_assistants

List all assistants in your VAPI account.

Parameters:

• limit (optional): Maximum number to return (default: 20)
• offset (optional): Offset for pagination (default: 0)

Example:

List all my VAPI assistants

vapi_get_assistant

Get details of a specific assistant.

Parameters:

• assistantId (required): VAPI Assistant ID

Example:

Get details for assistant ID asst_abc123

vapi_update_assistant

Update an existing assistant's configuration.

Parameters:

• assistantId (required): VAPI Assistant ID to update
• name (optional): New name
• model (optional): New model
• voice (optional): New voice
• systemPrompt (optional): New system prompt
• firstMessage (optional): New first message
• metadata (optional): New metadata

Example:

Update assistant asst_abc123 to use GPT-4 model

vapi_list_phone_numbers

List available phone numbers in your VAPI account.

Parameters:

• limit (optional): Maximum number to return (default: 20)
• offset (optional): Offset for pagination (default: 0)

Example:

List all my VAPI phone numbers

vapi_get_phone_number

Get details of a specific phone number.

Parameters:

• phoneNumberId (required): VAPI Phone Number ID

Example:

Get details for phone number ID phone_xyz789

vapi_get_call_transcript

Get the transcript of a call.

Parameters:

• callId (required): VAPI Call ID

Example:

Get transcript for call ID call_abc123

vapi_get_call_analytics

Get detailed analytics and metrics for a call.

Parameters:

• callId (required): VAPI Call ID

Example:

Get analytics for call ID call_abc123

vapi_configure_routing

Configure call routing rules based on business hours.

Parameters:

• businessHours (required): Business hours configuration
  • startTime (required): Start time in HH:MM format (24-hour)
  • endTime (required): End time in HH:MM format (24-hour)
  • timezone (required): Timezone (e.g., 'America/New_York')
  • daysOfWeek (optional): Array of days when business hours apply
• businessHoursPhoneNumber (required): Phone number for business hours
• businessHoursAssistantId (optional): Assistant ID for business hours
• afterHoursAssistantId (required): Assistant ID for after hours
• afterHoursPhoneNumber (optional): Phone number for after hours
• holidays (optional): Array of holiday dates
• overrides (optional): Temporary routing overrides

Example:

Configure routing with business hours 9AM-5PM EST, using assistant asst_123 after hours

vapi_get_routing_config

Get the current call routing configuration.

Example:

Show me the current routing configuration

vapi_test_routing

Test what routing would return at a specific time.

Parameters:

• testDateTime (optional): ISO 8601 datetime to test (defaults to current time)

Example:

Test routing for next Monday at 8PM

Usage Examples

Basic Call Creation

"Create a phone call to +1234567890 using my customer support assistant"

Call Management

"List all recent calls"
"Get details for the most recent call"
"End the active call with ID call_abc123"

Advanced Scenarios

"Create a call to +1234567890 with metadata: customer_id=12345, priority=high"
"Show me all calls from today with their durations and costs"

Assistant Management

"Create a new customer support assistant with GPT-4"
"List all my assistants"
"Update the sales assistant to use a different voice"
"Get details for my main support assistant"

Analytics & Insights

"Get the transcript from the last customer call"
"Show me analytics for today's calls including duration and cost"
"Get detailed metrics for call ID call_abc123"

Call Routing Configuration

"Configure business hours from 9AM to 5PM EST Monday through Friday"
"Set after-hours assistant to asst_afterhours_123"
"Add Christmas and New Year as holidays"
"Test what assistant would handle a call next Saturday"

VAPI Assistant Setup

To use this MCP server effectively, you need to create assistants in VAPI:

1. Log into VAPI Dashboard: Go to vapi.ai
2. Create an Assistant:
   • Click "Create Assistant"
   • Configure the voice, model, and prompts
   • Copy the Assistant ID
3. Test Your Assistant: Use the dashboard to test before making calls

Example Assistant Configuration

{
  "name": "Customer Support Bot",
  "voice": "elevenlabs-sarah",
  "model": "gpt-4",
  "prompt": "You are a helpful customer support agent...",
  "functions": [
    // Add custom functions for your use case
  ]
}

Troubleshooting

Common Issues

1. "Invalid API Key" error:

   • Verify your VAPI_API_KEY is correct
   • Check that the key has necessary permissions

2. "Assistant not found" error:

   • Ensure the assistant ID exists in your VAPI account
   • Check that the assistant is active

3. "Invalid phone number" error:

   • Use E.164 format: +1234567890
   • Include country code
   • Remove any spaces or special characters

4. Call creation fails:

   • Check your VAPI account has sufficient credits
   • Verify phone number is valid
   • Ensure assistant is properly configured

Debug Mode

Run Claude with debug flag to see detailed logs:

claude --mcp-debug

Best Practices

1. Phone Number Format: Always use E.164 format (+1234567890)
2. Assistant Testing: Test assistants in VAPI dashboard first
3. Metadata Usage: Use metadata to track calls in your system
4. Error Handling: Check call status after creation
5. Cost Management: Monitor usage in VAPI dashboard

Webhook Deployment

The MCP-VAPI server can be deployed as an AWS Lambda function to handle VAPI webhook requests for dynamic call routing.

Quick Deploy

1. Build the Lambda package:

npm run build:lambda

2. Deploy with AWS SAM:

sam build
sam deploy --guided

3. Configure VAPI webhook with the generated URL

See DEPLOY.md for detailed deployment instructions.

Future Features (Roadmap)

• Real-time Events: WebSocket support for live call events
• Advanced Routing: Skills-based routing and queue management
• Phone Number Management: Purchase and manage phone numbers
• Batch Operations: Create multiple calls simultaneously
• Call Recording: Manage and retrieve call recordings
• Custom Functions: Define custom functions for assistants

Development

Building from Source

# Clone the repository
git clone https://github.com/chinchillaenterprises/ChillMCP.git
cd ChillMCP/mcp-vapi

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Adding New Features

The server uses:

• @modelcontextprotocol/sdk for MCP server implementation
• axios for HTTP requests to VAPI API
• zod for input validation
• TypeScript for type safety

Security Considerations

• API Key Security: Never commit your VAPI API key
• Phone Number Privacy: Be cautious with personal phone numbers
• Call Recording: Ensure compliance with recording laws
• Data Protection: Handle call metadata securely

License

MIT License - see the parent repository for details.

Support

For issues and feature requests, please visit the ChillMCP repository.

Built with ❤️ by Chinchilla Enterprises