> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/tools/mcp/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# MCP tools

> Learn what the Vapi MCP tool does, when to use it, how Vapi fetches and calls an MCP server's tools, and how to create an MCP tool in the Dashboard or with cURL.

The MCP tool connects a voice agent to an external [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server. When a call starts, Vapi asks the server which tools it has and gives each one to the model as a normal tool. When the model calls one of them, Vapi forwards the request to the server and returns the result to the model.

## When to use an MCP tool

Use an MCP tool when:

* **A server already provides the actions you need.** This can be a provider such as Zapier, Make, or Composio, or an MCP server you run yourself.
* **You want many actions from one setup.** One MCP tool gives the voice agent the server's whole set of tools, with no per-tool setup in Vapi.
* **The actions change often.** When the server adds or changes a tool, new calls pick up the change automatically.

Use a [Function tool](/tools/custom-tools) or an [API Request tool](/tools/api-request) instead when:

* **You need one specific action with a fixed name, description, and parameters** that you control in Vapi.
* **Authentication needs a different value on each call.** MCP tools can't use variables in anything the server needs to list its tools. For more information, see [Use variables in headers](/tools/mcp/configure#use-variables-in-headers).

## How MCP tools work

1. **The call or chat starts.** Vapi connects to the MCP server and requests its tool list once.
2. **Vapi adds the server's tools to the model.** Each tool gets a name prefix. The MCP tool itself is never shown to the model; it only tells Vapi which server to use. For more information, see [Tool names the model sees](/tools/mcp/configure#tool-names-the-model-sees).
3. **The model calls a tool.** Vapi opens a new MCP session, sends the tool call, and closes the session. Every tool call uses its own session.
4. **The server's result goes back to the model**, which uses it to reply to the caller.

Vapi requests the tool list only at the start of each call or chat. It doesn't refresh the list during a conversation, so changes on the server show up on the next call.

Pinned assistant versions and squad members also get the server's current tool list when the call starts, not the list from when the version was saved.

Creating or updating an MCP tool doesn't contact the server. The first request happens when a call or chat uses the tool.

## Prerequisites

* An MCP server URL. The server must support Streamable HTTP, or Server-Sent Events (SSE) for older servers. For Zapier, Composio, and Make, see [MCP providers](/tools/mcp/providers).
* Any authentication the server needs. See [Authentication](/tools/mcp/configure#authentication).

## Create an MCP tool

#### Dashboard

#### Create the tool

Go to **Tools**, click **Create Tool**, and select **MCP**.

#### Name the tool

Under **Tool Settings**, enter a **Tool Name** and **Description** so you and your team can identify this MCP tool.

#### Enter the server URL

Under **Server Settings**, enter the **Server URL**.

#### Set the timeout (optional)

Set **Timeout** to how long Vapi waits for each request to the server. The default is 20 seconds.

#### Add authentication (optional)

If the server needs authentication, select a saved credential under **Authorization**, or add the auth header under **HTTP Headers**. See [Authentication](/tools/mcp/configure#authentication).

#### Add other headers (optional)

Under **HTTP Headers**, add any other headers your server needs. Header values can use variables, which Vapi fills in for tool calls only. See [Use variables in headers](/tools/mcp/configure#use-variables-in-headers).

#### Encrypt sensitive arguments (optional)

Under **Encryption Settings**, add the argument paths to encrypt. This needs a custom credential with encryption enabled. See [Encrypt sensitive arguments](/tools/mcp/configure#encrypt-sensitive-arguments).

#### Choose the protocol (optional)

Under **MCP Settings**, keep **Streamable HTTP** unless your server only supports SSE. See [Transport](/tools/mcp/configure#transport).

#### Add spoken messages (optional)

Under **Messages**, click **Add Message** to set what the caller hears while a tool runs. These messages apply to every tool from the server. See [Spoken messages during tool calls](/tools/mcp/messages-and-results#spoken-messages-during-tool-calls).

#### Save and check the connection

Save the tool. Vapi then queries your MCP server for its list of tools and shows them in the **Available Tools** section, below **MCP Settings**. If the list is empty, check the URL and authentication, save again, and click refresh.

#### Add the tool to your voice agent

Open your assistant, add the MCP tool to its tools, and publish.

#### cURL

Create the tool. Only `type` and `server.url` are required:

```bash
curl -X POST https://api.vapi.ai/tool \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mcp",
    "server": {
      "url": "https://mcp.example.com/mcp"
    }
  }'
```

This example sets every common option:

```bash
curl -X POST https://api.vapi.ai/tool \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mcp",
    "server": {
      "url": "https://mcp.example.com/mcp",
      "timeoutSeconds": 30,
      "headers": {
        "Authorization": "Bearer YOUR_MCP_SERVER_TOKEN",
        "X-Customer-Id": "{{customerId}}"
      }
    },
    "metadata": {
      "protocol": "shttp"
    },
    "messages": [
      { "type": "request-start", "content": "Let me check that for you." }
    ],
    "toolMessages": [
      {
        "name": "create_ticket",
        "messages": [
          { "type": "request-complete", "content": "Your ticket is created." }
        ]
      }
    ]
  }'
```

To authenticate with a saved credential instead of a header, replace the `Authorization` header with `"credentialId": "YOUR_CREDENTIAL_ID"` in `server`. For every field, see the [Configuration reference](/tools/mcp/configure#configuration-reference).

Then add the returned tool ID to your assistant's `model.toolIds`:

```json
{
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "toolIds": ["YOUR_MCP_TOOL_ID"]
  }
}
```

You can also define the tool inline in `model.tools` with the same fields.

## Next steps

* [Configure MCP tools](/tools/mcp/configure): set authentication, headers, variables, encryption, and transport.
* [MCP tool messages and results](/tools/mcp/messages-and-results): control what the caller hears and what the model receives.
* [Troubleshoot MCP tools](/tools/mcp/troubleshooting): fix common problems and follow best practices.
* [MCP providers](/tools/mcp/providers): connect Zapier, Composio, or Make.

> Give a voice agent the tools from any MCP server, fetched when each call starts

## Docs

- [Configure MCP tools](https://docs.vapi.ai/tools/mcp/configure.md): Configure a Vapi MCP tool's fields, header or credential authentication, context headers, variables, argument encryption, tool names, and transport.
- [MCP tool messages and results](https://docs.vapi.ai/tools/mcp/messages-and-results.md): Set spoken messages for all or individual MCP tools in Vapi, and learn how an MCP server's content, structuredContent, and isError reach the model.
- [Troubleshoot MCP tools](https://docs.vapi.ai/tools/mcp/troubleshooting.md): Troubleshoot Vapi MCP tools, including missing tools, failed tool list requests, unfilled variables, credential and encryption errors, and messages that don't play.
- [MCP providers](https://docs.vapi.ai/tools/mcp/providers.md): Connect a Vapi MCP tool to Zapier, Composio, or Make MCP servers, with the server URL, auth header, and links to each provider's setup documentation.