MCP tools

The Model Context Protocol (MCP) integration allows your Vapi assistant to dynamically access tools from MCP servers during calls. This enables your assistant to:

1. Connect to any MCP-compatible server
2. Access tools dynamically at runtime
3. Execute actions through the MCP server

This powerful integration allows your assistant to leverage a wide range of tools without requiring individual integrations for each service.

Prerequisites

Before you can use the MCP integration, you need to:

1. Have access to the Vapi Dashboard
2. Have an assistant created in Vapi
3. Have access to an MCP server URL (e.g., from Make, Zapier, Composio, or other MCP providers)

Setup Steps

1. Obtain MCP Server URL

First, you need to obtain an MCP server URL from your chosen provider:

1. Sign up for an MCP-compatible service (e.g., Make, Zapier, Composio)
2. Navigate to the MCP configuration section of your provider
3. Generate or copy your MCP server URL

2. Create and Configure MCP Tool

After obtaining your MCP server URL, create and configure the tool:

1. Go to Dashboard > Tools page
2. Click the Create Tool button
3. Select MCP from the available options
4. Provide a name and description explaining when it should be invoked
5. Configure the tool with the following required field:
   • Server URL: The URL of your MCP server

The Dashboard labels this field Server URL. In an API request, configure the same value as server.url.

3. Add Tool to Assistant

Now, add the MCP tool to your assistant:

1. Navigate to Dashboard > Assistants page
2. Select your assistant
3. Go to the Tools tab
4. In the tools dropdown, select your MCP tool
5. Click Publish to save your changes

How MCP Works

The MCP integration follows these steps during a call or chat session:

1. When a call or chat starts, Vapi connects to your configured MCP server using Streamable HTTP protocol by default, fetches the list of available tools, and dynamically adds them to your assistant’s available tools
2. The assistant can then use these tools during the interaction
3. Each time the model invokes a specific MCP tool, Vapi creates a new connection to the MCP server and sends the request with the X-Call-Id/X-Chat-Id header to identify the call or chat
4. The MCP server executes the action and returns the result
5. This process repeats for every tool invocation, meaning multiple MCP sessions are created per call or chat

Request Headers

MCP requests from Vapi include identifying headers to help with context and debugging:

• X-Call-Id: Included in requests during voice calls to identify the specific call
• X-Chat-Id: Included in requests during chat interactions to identify the specific chat
• X-Session-Id: Included in requests during chat interaction if the chat is part of a session

Tool Configuration

MCP Tool

This tool uses the following configuration options:

Required:

• server.url: The URL of your MCP server (e.g., https://mcp.zapier.com/api/mcp/s/********/mcp)

Optional:

• server.headers: Custom headers to include in requests to the MCP server
• metadata: Additional configuration options for the MCP connection
  • protocol: Communication protocol to use. Options are:
    • "shttp" (default): Uses Streamable HTTP protocol
    • "sse": (deprecated) Uses Server-Sent Events protocol

Example Usage

Here’s how the MCP tool can be used in your assistant’s configuration:

Default Configuration (Streamable HTTP)

{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful personal assistant named Alex. You can help users with various tasks through voice commands. You have access to tools that allow you to perform actions on the user's behalf.\n\nWhen a user requests an action, check if any of the available tools can help accomplish that task.\n\nCommon tasks you can help with include:\n- Scheduling appointments and meetings\n- Sending messages or emails\n- Creating or updating documents\n- Managing to-do lists and reminders\n- Searching for information\n- Making reservations\n- Ordering food or services\n- Checking account balances or transaction history\n- Controlling smart home devices\n\nAlways be polite, professional, and helpful. If a tool fails or isn't available, explain the situation to the user and suggest alternatives if possible."
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "function": {
          "name": "mcpTools"
        },
        "server": {
            "url": "https://mcp.zapier.com/api/mcp/s/********/mcp"
        }
      }
    ]
  }
}

Custom Configuration (SSE Protocol)

If you need to use Server-Sent Events protocol instead:

{
  "model": {
    "provider": "openai",
    "model": "gpt-4",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful personal assistant named Alex..."
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "function": {
          "name": "mcpTools"
        },
        "server": {
            "url": "https://mcp.zapier.com/api/mcp/s/********/mcp",
            "headers": {
              "Authorization": "Bearer your-token",
              "X-Custom-Header": "your-value"
            }
        },
        "metadata": {
          "protocol": "sse"
        }
      }
    ]
  }
}

Best Practices

1. Protocol Selection: Use the default Streamable HTTP protocol. SSE is deprecated and should be used only when required by the server
2. Dynamic Tool Awareness: Be aware that the available tools may change between calls
3. Clear Instructions: Provide clear instructions in your assistant’s system message about how to handle dynamic tools
4. Error Handling: Include fallback responses for cases where tools fail or are unavailable
5. User Communication: Explain to users what tools you’re using and what actions you’re taking
6. Security: Treat the MCP server URL as a credential and keep it secure

Example MCP Providers

Make MCP

Make MCP can expose active, on-demand scenarios as tools and can expose account-management tools when the token has the corresponding scopes.

See Connect Vapi to Make to compare MCP with API Request and Function tools.

Zapier MCP

Zapier offers an MCP server that provides access to thousands of app integrations:

1. Go to https://mcp.zapier.com/mcp/?client=vapi?
2. Generate your MCP server URL
3. Add the URL to your MCP tool configuration
4. Your assistant will now have access to Zapier’s extensive integration network

Composio MCP

Composio also offers an MCP server for integration:

1. Log in to the Composio dashboard at dashboard.composio.dev
2. Select the tool you want to integrate (e.g., Gmail)
3. Enable the MCP server for the selected tool by connecting your account using authentication flow
4. Create a server and copy the generated URL
5. Add this URL as the Server URL in the Dashboard, or as server.url through the API
6. Your assistant will now have access to the specific Composio tool integration

References

• Model Context Protocol Introduction
• Zapier MCP
• Make MCP