MCP integration

Overview

The Model Context Protocol (MCP) integration transforms your IDE’s AI assistant into a Vapi expert. Once configured, your IDE gains complete, accurate knowledge of Vapi’s APIs, features, and best practices - eliminating AI hallucinations and outdated information.

In this guide, you’ll learn to:

Set up MCP in supported IDEs
Understand what knowledge is provided
Use your enhanced IDE effectively
Troubleshoot common issues

Quick start

Run the setup command to auto-configure all supported IDEs:

vapi mcp setup

Or configure a specific IDE:

vapi mcp setup cursor   # For Cursor
vapi mcp setup windsurf # For Windsurf  
vapi mcp setup vscode   # For VSCode with Copilot

What is MCP?

Model Context Protocol is a standard that allows AI assistants to access structured knowledge and tools. When you set up MCP for Vapi:

Your IDE’s AI gains access to complete Vapi documentation
Code suggestions become accurate and up-to-date
Examples use real, working Vapi patterns
API hallucinations are eliminated

Supported IDEs

Cursor

AI-first code editor with deep MCP integration

Setup: Creates .cursor/mcp.json

Windsurf

Codeium’s AI-powered IDE

Setup: Creates .windsurf/mcp.json

VSCode

With GitHub Copilot extension

Setup: Configures Copilot settings

How it works

What gets configured

The MCP setup creates configuration files that connect your IDE to the Vapi MCP server:

Cursor

Windsurf

VSCode

File: .cursor/mcp.json

{
  "servers": {
    "vapi-docs": {
      "command": "npx",
      "args": ["@vapi-ai/mcp-server"]
    }
  }
}

What knowledge is provided

Your IDE gains access to:

Complete API Reference - Every endpoint, parameter, and response
Code Examples - Working samples for all features
Integration Guides - Step-by-step implementation patterns
Best Practices - Recommended approaches and patterns
Latest Features - Always up-to-date with new releases
Troubleshooting - Common issues and solutions

Using your enhanced IDE

Example prompts

Once MCP is configured, try these prompts in your IDE:

Creating assistants

Prompt: “How do I create a voice assistant with Vapi?”

Your IDE will provide accurate code like:

import { VapiClient } from "@vapi-ai/server-sdk";
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
const assistant = await client.assistants.create({
  name: "Customer Support",
  model: {
    provider: "openai",
    model: "gpt-4",
    systemPrompt: "You are a helpful customer support agent..."
  },
  voice: {
    provider: "11labs",
    voiceId: "rachel"
  }
});

Webhook handling

Prompt: “Show me how to handle Vapi webhooks”

Get complete webhook examples:

app.post('/webhook', async (req, res) => {
  const { type, call, assistant } = req.body;
  
  switch (type) {
    case 'call-started':
      console.log(`Call ${call.id} started`);
      break;
    case 'speech-update':
      console.log(`User said: ${req.body.transcript}`);
      break;
    case 'function-call':
      // Handle tool calls
      const { functionName, parameters } = req.body.functionCall;
      const result = await handleFunction(functionName, parameters);
      res.json({ result });
      return;
  }
  
  res.status(200).send();
});

Advanced features

Prompt: “How do I set up call recording with custom storage?”

Get detailed implementation:

const assistant = await client.assistants.create({
  name: "Recorded Assistant",
  recordingEnabled: true,
  artifactPlan: {
    recordingEnabled: true,
    videoRecordingEnabled: false,
    recordingPath: "s3://my-bucket/recordings/{call_id}"
  },
  credentialIds: ["aws-s3-credential-id"]
});

Best practices

Be specific

Ask detailed questions about Vapi features:

✅ “How do I transfer calls to a human agent in Vapi?”
❌ “How do I transfer calls?”

Request examples

Ask for working code samples:

“Show me a complete example of…”
“Generate a working implementation of…”

Check versions

Specify SDK versions when needed:

“Using @vapi-ai/web v2.0, how do I…”
“What’s the latest way to…”

Configuration options

Check status

View current MCP configuration:

vapi mcp status

Output:

MCP Configuration Status:
✓ Cursor: Configured (.cursor/mcp.json)
✗ Windsurf: Not configured
✓ VSCode: Configured (workspace settings)
Vapi MCP Server: v1.2.3 (latest)

Update server

Keep the MCP server updated:

# Update to latest version
npm update -g @vapi-ai/mcp-server
# Or reinstall
npm install -g @vapi-ai/mcp-server@latest

Remove configuration

Remove MCP configuration:

# Remove from all IDEs
vapi mcp remove
# Remove from specific IDE
vapi mcp remove cursor

How MCP tools work

The Vapi MCP server provides these tools to your IDE:

Search Documentation

Semantic search across all Vapi docs

Example: “How to handle voicemail detection”

Get Examples

Retrieve code samples for any feature

Example: “WebSocket connection example”

API Reference

Get detailed API endpoint information

Example: “POST /assistant parameters”

Implementation Guides

Step-by-step guides for complex features

Example: “Custom tool implementation guide”

Troubleshooting

MCP not working in IDE

If your IDE isn’t using the MCP knowledge:

Restart your IDE after configuration
Check the logs in your IDE’s output panel
Verify npm is accessible from your IDE
Ensure MCP server is installed globally

# Verify installation
npm list -g @vapi-ai/mcp-server

Permission errors

For permission issues:

# Install with proper permissions
sudo npm install -g @vapi-ai/mcp-server
# Or use a Node version manager
nvm use 18
npm install -g @vapi-ai/mcp-server

Outdated information

If you’re getting old API information:

Update the MCP server:

npm update -g @vapi-ai/mcp-server

Clear your IDE’s cache
Restart the IDE

Multiple workspaces

For different projects needing different configs:

MCP configuration is per-workspace
Run vapi mcp setup in each project
Configuration won’t conflict between projects

Advanced usage

Custom MCP configuration

Modify the generated MCP configuration for advanced needs:

{
  "servers": {
    "vapi-docs": {
      "command": "npx",
      "args": ["@vapi-ai/mcp-server"],
      "env": {
        "VAPI_MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Using with teams

Share MCP configuration with your team:

Commit the config files (.cursor/mcp.json, etc.)
Document the setup in your README
Include in onboarding for new developers

Example README section:

## Development Setup
This project uses Vapi MCP for enhanced IDE support:
1. Install Vapi CLI: `curl -sSL https://vapi.ai/install.sh | bash`
2. Set up MCP: `vapi mcp setup`
3. Restart your IDE

Next steps

Now that MCP is configured:

Create assistants: Build your first voice AI
Test webhooks locally: Debug webhooks with tunneling services
Manage resources: Use CLI commands

Pro tip: After setting up MCP, try asking your IDE to “Create a complete Vapi voice assistant with error handling and logging” - watch it generate production-ready code with all the right patterns!