From 83358b9daf07ab4647d50a963305b62bfad07cdb Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Mon, 9 Nov 2026 23:17:42 -0500 Subject: [PATCH 1/7] docs: lead the MCP server page with the hosted connection Make connecting to the hosted Streamable HTTP server the primary path and running the server locally the secondary one. Fold the duplicate "Integration Options" and custom-client sections into "Run the server locally" and "Use the server from your own code", mention the deprecated SSE endpoint only in the migration note, and list docs search among the core tools. Reword the CLI overview bullet to "Turn your agent into a Vapi expert". Co-Authored-By: Claude Opus 5.5 --- fern/cli/overview.mdx | 2 +- fern/sdk/mcp-server.mdx | 253 ++++++++++++++++------------------------ 2 files changed, 99 insertions(+), 156 deletions(-) diff --git a/fern/cli/overview.mdx b/fern/cli/overview.mdx index c40f06565..92a7b9c06 100644 --- a/fern/cli/overview.mdx +++ b/fern/cli/overview.mdx @@ -13,7 +13,7 @@ The Vapi CLI is the official command-line interface that brings world-class deve - Initialize Vapi in existing projects - Manage assistants, phone numbers, and calls from your terminal - Forward webhooks to your local development server -- Turn your IDE into a Vapi expert with MCP integration +- Turn your agent into a Vapi expert with the [Vapi MCP server](/sdk/mcp-server) ## Installation diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index 94d2b74ee..6e48765ea 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -1,33 +1,23 @@ --- title: Vapi MCP Server -subtitle: Connect Vapi to AI assistants with Model Context Protocol (MCP) +subtitle: Connect your coding agent to Vapi with Model Context Protocol (MCP) slug: sdk/mcp-server -description: Use the Vapi MCP Server to expose Vapi APIs as tools over the Model Context Protocol, managing assistants, phone numbers, and calls from any MCP client. +description: Connect Codex, Claude Code, Cursor, VS Code, or Claude Desktop to the hosted Vapi MCP server to search Vapi documentation and manage assistants, phone numbers, and calls. --- ## Overview -The **Vapi MCP Server** exposes Vapi APIs as tools via the Model Context Protocol (MCP), so you can manage assistants, phone numbers, and calls from any MCP-compatible AI assistant (like Claude Desktop) or agent framework. +The **Vapi MCP Server** gives AI agents Vapi tools over the Model Context Protocol (MCP). Once connected, your agent can search Vapi's documentation and manage your assistants, phone numbers, and calls. -Use this server to connect your AI workflows to real-world telephony, automate voice tasks, and build richer conversational agents. +Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP** transport. Add it in your agent's MCP settings; you don't need the Vapi CLI. You can also [run the server locally](#run-the-server-locally). - Looking to use MCP tools *inside* a Vapi assistant? See the [MCP Tool documentation](/tools/mcp) for integrating *external* MCP servers with your Vapi agents. + Looking to use MCP tools *inside* a Vapi assistant? See [MCP tools](/tools/mcp). - - Connect your coding agent directly to the hosted MCP server using its native MCP settings. The Vapi CLI is not required. For public agent skills and installation instructions, see [VapiAI/skills](https://github.com/VapiAI/skills). - - - - If an earlier CLI release configured `@vapi-ai/mcp-docs-server` in your agent, replace that legacy entry with the hosted connection below. Existing agent configurations are not removed automatically. - - -Use **Streamable HTTP** at `https://mcp.vapi.ai/mcp` for remote connections. The legacy HTTP+SSE transport is deprecated; migrate existing remote configurations to this endpoint. - ## Connect your agent -Get a [Vapi API key](/security-and-privacy/api-keys), then choose your client. These connections use the hosted server; you do not need to install the Vapi CLI or run a Vapi MCP server locally. +Get a [Vapi API key](/security-and-privacy/api-keys), then choose your agent. @@ -121,12 +111,12 @@ Get a [Vapi API key](/security-and-privacy/api-keys), then choose your client. T } ``` - Start `vapi` from **MCP: List Servers** and enter your API key when prompted. Use a **Local** chat session and enable its tools. VS Code does not forward servers that use input prompts to Copilot harness sessions. + Start `vapi` from **MCP: List Servers** and enter your API key when prompted. Then use a **Local** chat session and enable the server's tools. Other session types can't prompt for the key, so this server isn't available in them. See [VS Code MCP setup](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). - To connect through Claude Desktop's local stdio configuration, use `mcp-remote` as a bridge to the hosted server. This option requires Node.js and `npx` to be available to Claude Desktop. + Claude Desktop's configuration file runs local commands, so use `mcp-remote` as a bridge to the hosted server. This requires Node.js and `npx` to be available to Claude Desktop. Open **Settings → Developer → Edit Config**. Add this entry to `claude_desktop_config.json`, preserving any other servers: @@ -152,20 +142,49 @@ Get a [Vapi API key](/security-and-privacy/api-keys), then choose your client. T } ``` - Replace `YOUR_VAPI_API_KEY` with your Vapi API key and restart Claude Desktop. Keep this configuration private and update the key after rotating it. This starts a local adapter; Vapi's MCP server stays hosted. + Replace `YOUR_VAPI_API_KEY` with your Vapi API key and restart Claude Desktop. Keep this configuration private and update the key after rotating it. The bridge runs locally; Vapi's MCP server stays hosted. Once connected, try asking your agent: "List my Vapi assistants." ---- + + **Replacing an older setup?** If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, or the deprecated `https://mcp.vapi.ai/sse` endpoint, replace that entry with the hosted connection above. The hosted server includes documentation search. Existing agent configurations are not changed automatically. + -## Core Tools +## Run the server locally -The Vapi MCP Server exposes these actions as MCP tools: +You can run the open-source [Vapi MCP server](https://github.com/VapiAI/mcp-server) on your own machine instead of connecting to the hosted one, for example to develop against it. This requires Node.js. Your client starts the server as a subprocess and talks to it over stdio, so no HTTP endpoint is started. + +Add this entry to your client's MCP configuration in place of the hosted connection. The local server reads your API key from `VAPI_TOKEN`: + +```json +{ + "mcpServers": { + "vapi": { + "command": "npx", + "args": ["-y", "@vapi-ai/mcp-server"], + "env": { + "VAPI_TOKEN": "YOUR_VAPI_API_KEY" + } + } + } +} +``` -| Tool | Description | Example Usage | +In Claude Code, run: + +```bash +claude mcp add -e VAPI_TOKEN=YOUR_VAPI_API_KEY vapi -- npx -y @vapi-ai/mcp-server +``` + +## Core tools + +The Vapi MCP Server exposes these tools: + +| Tool | Description | Example usage | |------------------------|--------------------------------------------------|-----------------------------------------------| +| `ask_vapi_docs` | Search Vapi documentation | Ask how a Vapi feature works | | `list_assistants` | List all Vapi assistants | Show all configured assistants | | `create_assistant` | Create a new Vapi assistant | Add a new assistant for a use case | | `get_assistant` | Get a Vapi assistant by ID | View assistant config | @@ -177,136 +196,61 @@ The Vapi MCP Server exposes these actions as MCP tools: | `list_tools` | List all available Vapi tools | Tool discovery | | `get_tool` | Get details of a specific tool | Tool integration info | - - Scheduling calls: The create_call action supports scheduling with the optional scheduledAt parameter. - +To schedule a call, pass the optional `scheduledAt` parameter to `create_call`. `create_call` places a real phone call. ---- +## Use the server from your own code -## Integration Options +Connect any MCP client to `https://mcp.vapi.ai/mcp` over Streamable HTTP, and send your Vapi API key in the `Authorization: Bearer YOUR_VAPI_API_KEY` header. - - - Connect to the Vapi-hosted MCP server using the Streamable HTTP protocol. - - Recommended for most production use cases. - - - Use this for clients or SDKs that support Streamable HTTP transport. - - - - **Endpoint:** `https://mcp.vapi.ai/mcp` - - **Authentication:** Pass your Vapi API key as a bearer token: -
Authorization: Bearer YOUR_VAPI_API_KEY - - Configure the URL and authentication header directly in clients with remote MCP support. For a client that needs a local stdio adapter, use the [Claude Desktop tab](#connect-your-agent) above. - - - - The OpenAI responses API now supports MCP. Read more here. - - - ```typescript title="typescript" - import OpenAI from 'openai'; - // Replace with your actual OpenAI API key - const openai = new OpenAI({ apiKey: 'YOUR_OPENAI_API_KEY' }); - async function main() { - const response = await openai.responses.create({ - model: 'gpt-4.1', - tools: [ - { - type: 'mcp', - server_label: 'vapi-mcp', - server_url: 'https://mcp.vapi.ai/mcp', - headers: { "Authorization": "Bearer YOUR_VAPI_API_KEY" } - }, - ], - input: 'What vapi tools do you have available?', - }); - console.dir(response, { depth: null }); - } - main(); - ``` - ```python title="python" - import openai - # Replace with your actual OpenAI API key - openai.api_key = 'YOUR_OPENAI_API_KEY' - response = openai.responses.create( - model="gpt-4.1", - tools=[ - { - "type": "mcp", - "server_label": "vapi-mcp", - "server_url": "https://mcp.vapi.ai/mcp", - "headers": {"Authorization": "Bearer YOUR_VAPI_API_KEY"} - }, - ], - input="What vapi tools do you have available?", - ) - print(response) - ``` - - - - Run the MCP server on your own machine for development or testing. - - - **Start locally:** - ```bash - npx -y @vapi-ai/mcp-server - ``` - - **Authentication:** Set the `VAPI_TOKEN` environment variable to your API key. - - Example config for Claude: - ```json - { - "mcpServers": { - "vapi-mcp-server": { - "command": "npx", - "args": [ - "-y", - "@vapi-ai/mcp-server" - ], - "env": { - "VAPI_TOKEN": "YOUR_VAPI_API_KEY" - } - } - } - } - ``` - - Use this for clients or SDKs that support local command-based MCP servers. - - - The client launches this server as a subprocess and communicates over **stdio**. This configuration does not start an HTTP endpoint. - - +### OpenAI Responses API ---- +The OpenAI Responses API can call remote MCP servers. See [OpenAI's remote MCP guide](https://platform.openai.com/docs/guides/tools-remote-mcp). -## Custom MCP Client Integration - -You can use any MCP-compatible client (SDKs available for multiple languages). - - - - 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) - - - Set up your SDK to connect to https://mcp.vapi.ai/mcp using **Streamable HTTP** and authenticate with your Vapi API key in the Authorization: Bearer YOUR_VAPI_API_KEY header. - - - Query available tools, list assistants, create calls, etc, via your SDK. - - + +```typescript title="typescript" +import OpenAI from 'openai'; +// Replace with your actual OpenAI API key +const openai = new OpenAI({ apiKey: 'YOUR_OPENAI_API_KEY' }); +async function main() { + const response = await openai.responses.create({ + model: 'gpt-4.1', + tools: [ + { + type: 'mcp', + server_label: 'vapi-mcp', + server_url: 'https://mcp.vapi.ai/mcp', + headers: { "Authorization": "Bearer YOUR_VAPI_API_KEY" } + }, + ], + input: 'What vapi tools do you have available?', + }); + console.dir(response, { depth: null }); +} +main(); +``` +```python title="python" +import openai +# Replace with your actual OpenAI API key +openai.api_key = 'YOUR_OPENAI_API_KEY' +response = openai.responses.create( + model="gpt-4.1", + tools=[ + { + "type": "mcp", + "server_label": "vapi-mcp", + "server_url": "https://mcp.vapi.ai/mcp", + "headers": {"Authorization": "Bearer YOUR_VAPI_API_KEY"} + }, + ], + input="What vapi tools do you have available?", +) +print(response) +``` + ---- +### MCP client SDKs -### Example: Build a client with Node.js +Official MCP SDKs are available for [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), and [C#](https://github.com/modelcontextprotocol/csharp-sdk). This minimal Node.js client lists your assistants: ```javascript import { Client } from '@modelcontextprotocol/sdk/client/index.js'; @@ -318,7 +262,7 @@ dotenv.config(); const mcpClient = new Client({ name: 'vapi-client', version: '1.0.0' }); const transport = new StreamableHTTPClientTransport( new URL('https://mcp.vapi.ai/mcp'), - { requestInit: { headers: { Authorization: `Bearer ${process.env.VAPI_TOKEN}` } } } + { requestInit: { headers: { Authorization: `Bearer ${process.env.VAPI_API_KEY}` } } } ); async function main() { @@ -331,7 +275,7 @@ async function main() { main(); ``` -### Detailed example: Build a client with Node.js +This fuller example lists tools, assistants, and phone numbers, then creates a call: ```javascript #!/usr/bin/env node @@ -343,8 +287,8 @@ import dotenv from 'dotenv'; dotenv.config(); // Ensure API key is available -if (!process.env.VAPI_TOKEN) { - console.error('Error: VAPI_TOKEN environment variable is required'); +if (!process.env.VAPI_API_KEY) { + console.error('Error: VAPI_API_KEY environment variable is required'); process.exit(1); } @@ -358,7 +302,7 @@ async function main() { // Create Streamable HTTP transport for connection to remote Vapi MCP server const serverUrl = 'https://mcp.vapi.ai/mcp'; const headers = { - Authorization: `Bearer ${process.env.VAPI_TOKEN}`, + Authorization: `Bearer ${process.env.VAPI_API_KEY}`, }; const options = { requestInit: { headers: headers }, @@ -461,14 +405,13 @@ async function main() { main(); ``` - For more detailed examples and complete client implementations, see the [MCP Client Quickstart](https://modelcontextprotocol.io/quickstart/client). - ## References -- [Github repo](https://github.com/VapiAI/mcp-server) +- [Vapi MCP server on GitHub](https://github.com/VapiAI/mcp-server) +- [Vapi agent skills](https://github.com/VapiAI/skills) - [Model Context Protocol docs](https://modelcontextprotocol.io) -- [Vapi dashboard](https://dashboard.vapi.ai) - [MCP client quickstart](https://modelcontextprotocol.io/quickstart/client) +- [Vapi dashboard](https://dashboard.vapi.ai) From b36ff3abfcab458ac85751d6170b0c5f312fa213 Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Mon, 9 Nov 2026 23:20:22 -0500 Subject: [PATCH 2/7] docs: document documentation-only MCP access without an API key Carry over the useful part of #1409: agents that only need docs search can connect to https://docs.vapi.ai/_mcp/server (searchDocs, no API key), with an mcp-remote example for clients that need a stdio adapter. Link it from the migration note, since it is the like-for-like replacement for the retired @vapi-ai/mcp-docs-server. Co-Authored-By: Claude Opus 5.5 --- fern/sdk/mcp-server.mdx | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index 6e48765ea..45c72dbfc 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -149,7 +149,7 @@ Get a [Vapi API key](/security-and-privacy/api-keys), then choose your agent. Once connected, try asking your agent: "List my Vapi assistants." - **Replacing an older setup?** If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, or the deprecated `https://mcp.vapi.ai/sse` endpoint, replace that entry with the hosted connection above. The hosted server includes documentation search. Existing agent configurations are not changed automatically. + **Replacing an older setup?** If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, or the deprecated `https://mcp.vapi.ai/sse` endpoint, replace that entry with the hosted connection above. The hosted server includes documentation search. To keep documentation-only access without an API key, see [Search the docs without an API key](#search-the-docs-without-an-api-key). Existing agent configurations are not changed automatically. ## Run the server locally @@ -178,6 +178,23 @@ In Claude Code, run: claude mcp add -e VAPI_TOKEN=YOUR_VAPI_API_KEY vapi -- npx -y @vapi-ai/mcp-server ``` +## Search the docs without an API key + +For documentation search alone, connect your agent to Vapi's documentation MCP server at `https://docs.vapi.ai/_mcp/server`. It needs no API key and provides a `searchDocs` tool. The Vapi MCP server's `ask_vapi_docs` tool runs the same search. + +If your client can't connect to a remote server directly, run it through the `mcp-remote` adapter: + +```json +{ + "mcpServers": { + "vapi-docs": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://docs.vapi.ai/_mcp/server"] + } + } +} +``` + ## Core tools The Vapi MCP Server exposes these tools: From 89b33cd3d2777d66a7f79f621b2a6c7709bfe6b7 Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Tue, 10 Nov 2026 13:54:33 -0500 Subject: [PATCH 3/7] docs: list every MCP tool and restore the MCP tab sidebar The tools table listed 11 of the 29 tools the server registers, and the MCP tab rendered no sidebar. Tools: the hosted server pins @vapi-ai/mcp-server 0.1.0 and registers all of its tools, so hosted and local expose the same 29. The 18 that were missing are update_assistant, create_tool, update_tool, get_api_schema, search_skills, load_skill and the 12 simulation tools. Descriptions come from the tools' own registered descriptions. Grouped the table by area, since one flat 29-row table is hard to scan, and dropped the invented "Example usage" column. Sidebar: #1396 moved tools/mcp.mdx out of the MCP tab into the Documentation tab, leaving the tab with a single page. Fern renders no sidebar for a tab with one entry, so #fern-sidebar was display:none on this page while every other tab was display:flex. Adding a link back to MCP tools restores the sidebar and the cross-link #1396 removed. Verified against a local fern docs dev server. Co-Authored-By: Claude Opus 5 --- fern/docs.yml | 3 ++ fern/sdk/mcp-server.mdx | 81 +++++++++++++++++++++++++++++++++-------- 2 files changed, 69 insertions(+), 15 deletions(-) diff --git a/fern/docs.yml b/fern/docs.yml index 4bdd30dc2..c7969c8d4 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -1098,6 +1098,9 @@ navigation: - page: MCP server path: sdk/mcp-server.mdx icon: fa-light fa-server + - link: MCP tools + href: /tools/mcp + icon: fa-light fa-network-wired - tab: sdks layout: diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index 45c72dbfc..318381a7f 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -197,24 +197,75 @@ If your client can't connect to a remote server directly, run it through the `mc ## Core tools -The Vapi MCP Server exposes these tools: - -| Tool | Description | Example usage | -|------------------------|--------------------------------------------------|-----------------------------------------------| -| `ask_vapi_docs` | Search Vapi documentation | Ask how a Vapi feature works | -| `list_assistants` | List all Vapi assistants | Show all configured assistants | -| `create_assistant` | Create a new Vapi assistant | Add a new assistant for a use case | -| `get_assistant` | Get a Vapi assistant by ID | View assistant config | -| `list_calls` | List all calls | Review call activity | -| `create_call` | Create an outbound call (now or scheduled) | Initiate or schedule a call | -| `get_call` | Get details for a specific call | Check status or result of a call | -| `list_phone_numbers` | List all Vapi phone numbers | See available numbers | -| `get_phone_number` | Get details of a specific phone number | Inspect a phone number | -| `list_tools` | List all available Vapi tools | Tool discovery | -| `get_tool` | Get details of a specific tool | Tool integration info | +The Vapi MCP Server exposes these tools. The hosted server and the [local server](#run-the-server-locally) expose the same set. + +### Documentation and reference + +| Tool | Description | +|------------------|-----------------------------------------------------------------------------| +| `ask_vapi_docs` | Search Vapi documentation and return relevant passages with source URLs | +| `get_api_schema` | Look up a schema in the Vapi API reference, the OpenAPI spec the SDKs are generated from | +| `search_skills` | Find Vapi agent skills in the public `VapiAI/skills` repository | +| `load_skill` | Read a public Vapi skill or one of its supporting files | + +`load_skill` returns instructions for the agent to follow. It does not install skills or run scripts. + +### Assistants + +| Tool | Description | +|--------------------|------------------------------------| +| `list_assistants` | List all Vapi assistants | +| `get_assistant` | Get a Vapi assistant by ID | +| `create_assistant` | Create a new Vapi assistant | +| `update_assistant` | Update an existing Vapi assistant | + +### Calls + +| Tool | Description | +|---------------|------------------------------------| +| `list_calls` | List all calls | +| `get_call` | Get details for a specific call | +| `create_call` | Create an outbound call, now or scheduled | To schedule a call, pass the optional `scheduledAt` parameter to `create_call`. `create_call` places a real phone call. +### Phone numbers + +| Tool | Description | +|----------------------|----------------------------------------| +| `list_phone_numbers` | List all Vapi phone numbers | +| `get_phone_number` | Get details of a specific phone number | + +### Vapi tools + +| Tool | Description | +|---------------|-----------------------------------| +| `list_tools` | List all Vapi tools | +| `get_tool` | Get details of a specific tool | +| `create_tool` | Create a new Vapi tool | +| `update_tool` | Update an existing Vapi tool | + +### Simulations + +These tools drive [simulations](/observability/simulations-overview), which test an assistant against scripted callers. + +| Tool | Description | +|----------------------------------|-----------------------------------------------------------------------------| +| `list_simulation_personalities` | List simulation personalities, the simulated callers used in simulations | +| `create_simulation_personality` | Create a simulated caller that talks to the assistant under test | +| `list_simulation_scenarios` | List simulation scenarios, the scripts testers follow and the checks that decide pass or fail | +| `create_simulation_scenario` | Create a scenario: tester instructions plus the evaluations that decide pass or fail | +| `list_simulations` | List simulations, each pairing one scenario with one personality | +| `create_simulation` | Create a simulation that pairs a scenario with a personality | +| `list_simulation_suites` | List simulation suites, which are named groups of simulations | +| `create_simulation_suite` | Create a suite that groups simulations so they can be run together | +| `run_simulations` | Start a run of simulations or suites against an assistant or squad | +| `list_simulation_runs` | List simulation runs, newest first | +| `get_simulation_run` | Get a run with its status, item counts, and item summaries | +| `get_simulation_run_item` | Get one run item in full, including results, call snapshots, and transcript | + +`run_simulations` places real calls against the assistant you point it at. + ## Use the server from your own code Connect any MCP client to `https://mcp.vapi.ai/mcp` over Streamable HTTP, and send your Vapi API key in the `Authorization: Bearer YOUR_VAPI_API_KEY` header. From f487fe9c43c5600ac74593861b295efadd963561 Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Tue, 10 Nov 2026 17:05:42 -0500 Subject: [PATCH 4/7] docs: apply review feedback on the MCP server page Address stephenvapiai's review on #1410: - Name every agent tab plus tools and simulations in the page description, which feeds llms.txt. - Lowercase "server" in the title and body to match the nav label and the rest of the docs. - Trim the "Replacing an older setup?" callout to two sentences and lead with why the reader needs to act. - Rename "Core tools" to "Available tools", since the section now lists every tool. - Use the simulations docs' own term, "AI tester", in place of "scripted callers", "simulated callers", and "testers". - Correct the run_simulations note: simulations don't place phone calls, but each run is billed. - Move the create_call real-call warning into its own Info callout. - Avoid starting sentences with code identifiers. - Say "coding agent" in the CLI overview, since "agent" alone reads as a voice agent elsewhere in the docs. Co-Authored-By: Claude Opus 5 --- fern/cli/overview.mdx | 2 +- fern/sdk/mcp-server.mdx | 34 ++++++++++++++++++++-------------- 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/fern/cli/overview.mdx b/fern/cli/overview.mdx index 92a7b9c06..621e05eda 100644 --- a/fern/cli/overview.mdx +++ b/fern/cli/overview.mdx @@ -13,7 +13,7 @@ The Vapi CLI is the official command-line interface that brings world-class deve - Initialize Vapi in existing projects - Manage assistants, phone numbers, and calls from your terminal - Forward webhooks to your local development server -- Turn your agent into a Vapi expert with the [Vapi MCP server](/sdk/mcp-server) +- Turn your coding agent into a Vapi expert with the [Vapi MCP server](/sdk/mcp-server) ## Installation diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index 318381a7f..cff8e1f75 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -1,13 +1,13 @@ --- -title: Vapi MCP Server +title: Vapi MCP server subtitle: Connect your coding agent to Vapi with Model Context Protocol (MCP) slug: sdk/mcp-server -description: Connect Codex, Claude Code, Cursor, VS Code, or Claude Desktop to the hosted Vapi MCP server to search Vapi documentation and manage assistants, phone numbers, and calls. +description: Connect Codex, Claude Code, Hermes, Cursor, VS Code, or Claude Desktop to the Vapi MCP server to search the docs and manage assistants, calls, tools, and simulations. --- ## Overview -The **Vapi MCP Server** gives AI agents Vapi tools over the Model Context Protocol (MCP). Once connected, your agent can search Vapi's documentation and manage your assistants, phone numbers, and calls. +The **Vapi MCP server** gives AI agents Vapi tools over the Model Context Protocol (MCP). Once connected, your agent can search Vapi's documentation and manage your assistants, phone numbers, and calls. Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP** transport. Add it in your agent's MCP settings; you don't need the Vapi CLI. You can also [run the server locally](#run-the-server-locally). @@ -149,7 +149,7 @@ Get a [Vapi API key](/security-and-privacy/api-keys), then choose your agent. Once connected, try asking your agent: "List my Vapi assistants." - **Replacing an older setup?** If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, or the deprecated `https://mcp.vapi.ai/sse` endpoint, replace that entry with the hosted connection above. The hosted server includes documentation search. To keep documentation-only access without an API key, see [Search the docs without an API key](#search-the-docs-without-an-api-key). Existing agent configurations are not changed automatically. + **Replacing an older setup?** Existing configurations that use `@vapi-ai/mcp-docs-server` from an earlier CLI release, or the deprecated `https://mcp.vapi.ai/sse` endpoint, don't update automatically. Replace that entry with the hosted connection above, which includes documentation search, or see [Search the docs without an API key](#search-the-docs-without-an-api-key) for access without an API key. ## Run the server locally @@ -195,9 +195,9 @@ If your client can't connect to a remote server directly, run it through the `mc } ``` -## Core tools +## Available tools -The Vapi MCP Server exposes these tools. The hosted server and the [local server](#run-the-server-locally) expose the same set. +The Vapi MCP server exposes these tools. The hosted server and the [local server](#run-the-server-locally) expose the same set. ### Documentation and reference @@ -208,7 +208,7 @@ The Vapi MCP Server exposes these tools. The hosted server and the [local server | `search_skills` | Find Vapi agent skills in the public `VapiAI/skills` repository | | `load_skill` | Read a public Vapi skill or one of its supporting files | -`load_skill` returns instructions for the agent to follow. It does not install skills or run scripts. +The `load_skill` tool returns instructions for the agent to follow. It does not install skills or run scripts. ### Assistants @@ -227,7 +227,11 @@ The Vapi MCP Server exposes these tools. The hosted server and the [local server | `get_call` | Get details for a specific call | | `create_call` | Create an outbound call, now or scheduled | -To schedule a call, pass the optional `scheduledAt` parameter to `create_call`. `create_call` places a real phone call. +To schedule a call, pass the optional `scheduledAt` parameter to `create_call`. + + + The `create_call` tool places a real phone call. + ### Phone numbers @@ -247,14 +251,14 @@ To schedule a call, pass the optional `scheduledAt` parameter to `create_call`. ### Simulations -These tools drive [simulations](/observability/simulations-overview), which test an assistant against scripted callers. +These tools drive [simulations](/observability/simulations-overview), which test an assistant against an AI tester. | Tool | Description | |----------------------------------|-----------------------------------------------------------------------------| -| `list_simulation_personalities` | List simulation personalities, the simulated callers used in simulations | -| `create_simulation_personality` | Create a simulated caller that talks to the assistant under test | -| `list_simulation_scenarios` | List simulation scenarios, the scripts testers follow and the checks that decide pass or fail | -| `create_simulation_scenario` | Create a scenario: tester instructions plus the evaluations that decide pass or fail | +| `list_simulation_personalities` | List simulation personalities, which set how the AI tester behaves | +| `create_simulation_personality` | Create a personality that sets how the AI tester behaves | +| `list_simulation_scenarios` | List simulation scenarios, the AI tester's intent and the checks that decide pass or fail | +| `create_simulation_scenario` | Create a scenario: AI tester instructions plus the evaluations that decide pass or fail | | `list_simulations` | List simulations, each pairing one scenario with one personality | | `create_simulation` | Create a simulation that pairs a scenario with a personality | | `list_simulation_suites` | List simulation suites, which are named groups of simulations | @@ -264,7 +268,9 @@ These tools drive [simulations](/observability/simulations-overview), which test | `get_simulation_run` | Get a run with its status, item counts, and item summaries | | `get_simulation_run_item` | Get one run item in full, including results, call snapshots, and transcript | -`run_simulations` places real calls against the assistant you point it at. + + Each `run_simulations` tool call starts a billed simulation run. For more information, see [Simulations overview](/observability/simulations-overview). + ## Use the server from your own code From c5f3f8484363b69ef4ffa9303f6e330cddd040af Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Mon, 9 Nov 2026 23:28:11 -0500 Subject: [PATCH 5/7] docs: connect the hosted MCP server by signing in, not with an API key The hosted MCP server at mcp.vapi.ai/mcp becomes OAuth-only at the Nov 10 cutover: it stops accepting Vapi API keys in an Authorization header and stops serving /sse. - rewrite the six agent tabs to add the URL alone and sign in, using each client's own OAuth path (codex mcp login, claude mcp login, hermes auth: oauth, bare url for Cursor and VS Code, Claude Desktop custom connector) - add "How signing in works": the agent acts as the signed-in user with that user's role, one org per connection, get_connection_info to check it, and the actions Connect tokens can never reach (API keys, credentials, billing) - replace the SSE deprecation note with an upgrade note covering what to delete from an existing config - note that the local stdio server still uses VAPI_TOKEN, which makes it the option for unattended automation - rework "Use the server from your own code": mcp-remote as the simple path, SDK OAuth helpers, and an access token rather than an API key in the Node examples; drop the OpenAI example that passed an API key - add get_connection_info to the tools table Co-Authored-By: Claude Opus 5 --- fern/sdk/mcp-server.mdx | 193 ++++++++++++++++------------------------ 1 file changed, 77 insertions(+), 116 deletions(-) diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index cff8e1f75..1eed9705b 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -2,14 +2,14 @@ title: Vapi MCP server subtitle: Connect your coding agent to Vapi with Model Context Protocol (MCP) slug: sdk/mcp-server -description: Connect Codex, Claude Code, Hermes, Cursor, VS Code, or Claude Desktop to the Vapi MCP server to search the docs and manage assistants, calls, tools, and simulations. +description: Connect Codex, Claude Code, Hermes, Cursor, VS Code, or Claude Desktop to the Vapi MCP server by signing in with your Vapi account, to search the docs and manage assistants, calls, tools, and simulations. --- ## Overview The **Vapi MCP server** gives AI agents Vapi tools over the Model Context Protocol (MCP). Once connected, your agent can search Vapi's documentation and manage your assistants, phone numbers, and calls. -Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP** transport. Add it in your agent's MCP settings; you don't need the Vapi CLI. You can also [run the server locally](#run-the-server-locally). +Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP** transport. You connect by signing in with your Vapi account: your agent opens a browser, you sign in and pick an organization, and the agent receives a short-lived token. No API key is involved, and you don't need the Vapi CLI. You can also [run the server locally](#run-the-server-locally). Looking to use MCP tools *inside* a Vapi assistant? See [MCP tools](/tools/mcp). @@ -17,48 +17,50 @@ Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP* ## Connect your agent -Get a [Vapi API key](/security-and-privacy/api-keys), then choose your agent. +The hosted server uses OAuth, so there's nothing to copy and paste. Add the URL to your agent, then complete the sign-in in your browser. - For the Codex CLI, set your API key and register the remote server: + Register the remote server, then sign in: ```bash - export VAPI_API_KEY="YOUR_VAPI_API_KEY" - codex mcp add vapi --url https://mcp.vapi.ai/mcp \ - --bearer-token-env-var VAPI_API_KEY - codex mcp list + codex mcp add vapi --url https://mcp.vapi.ai/mcp + codex mcp login vapi ``` - Codex saves the connection in `~/.codex/config.toml` and reads the key from `VAPI_API_KEY` when it connects. Keep that variable available whenever you launch Codex. If you use the desktop app or IDE extension, its launch environment must also contain the variable. + Codex saves the connection in `~/.codex/config.toml` and registers itself with Vapi automatically. `codex mcp login` opens your browser; on a remote or headless machine, add `--no-browser` and paste the redirect URL back into the terminal. Start a new Codex session and use `/mcp` to inspect the connection. See [Codex MCP setup](https://developers.openai.com/codex/mcp). - Set your API key and add the server to your private user configuration: + Add the server to your private user configuration, then sign in: ```bash - export VAPI_API_KEY="YOUR_VAPI_API_KEY" - claude mcp add --transport http --scope user vapi \ - https://mcp.vapi.ai/mcp \ - --header 'Authorization: Bearer ${VAPI_API_KEY}' - claude mcp get vapi + claude mcp add --transport http --scope user vapi https://mcp.vapi.ai/mcp + claude mcp login vapi ``` - The single quotes preserve the environment-variable reference in `~/.claude.json`. Keep `VAPI_API_KEY` set whenever you launch Claude Code. Start a new session and use `/mcp` to check the connection. + You can also sign in from inside a session: run `/mcp`, select `vapi`, and follow the browser prompts. The same menu has **Clear authentication** if you need to sign in again or switch organizations. See [Claude Code MCP setup](https://code.claude.com/docs/en/mcp). - Register the hosted server with header authentication: + Add this entry to your active profile's `config.yaml`, preserving any other servers: - ```bash - hermes mcp add vapi --url https://mcp.vapi.ai/mcp --auth header + ```yaml + mcp_servers: + vapi: + url: "https://mcp.vapi.ai/mcp" + auth: oauth ``` - Confirm that the server requires authentication, then paste your Vapi API key at the masked **API key / Bearer token** prompt. Enter the key without the `Bearer` prefix. Select the tools you want to enable and finish saving the connection. + Then sign in: - Hermes saves the connection in your active profile's `config.yaml` and the key in its `.env` file. Start a new session, or run `/reload-mcp` in an existing session. To test the connection: + ```bash + hermes mcp login vapi + ``` + + Hermes handles registration and PKCE for you and stores the tokens under `~/.hermes/mcp-tokens/`. On a headless host, use `hermes mcp login vapi --flow device` to authorize with a code instead of a browser callback. Start a new session, or run `/reload-mcp` in an existing one, then: ```bash hermes mcp test vapi @@ -73,16 +75,13 @@ Get a [Vapi API key](/security-and-privacy/api-keys), then choose your agent. { "mcpServers": { "vapi": { - "url": "https://mcp.vapi.ai/mcp", - "headers": { - "Authorization": "Bearer YOUR_VAPI_API_KEY" - } + "url": "https://mcp.vapi.ai/mcp" } } } ``` - Replace `YOUR_VAPI_API_KEY` with your Vapi API key. Open Cursor's MCP settings and enable `vapi`, then start a new chat. Keep this user configuration private and update the header after rotating your key. + No headers or keys are needed. Open Cursor's MCP settings, enable `vapi`, and complete the Vapi sign-in in your browser when Cursor prompts you. Then start a new chat. See [Cursor MCP setup](https://cursor.com/docs/mcp). @@ -91,71 +90,53 @@ Get a [Vapi API key](/security-and-privacy/api-keys), then choose your agent. ```json { - "inputs": [ - { - "type": "promptString", - "id": "vapi-api-key", - "description": "Vapi API key", - "password": true - } - ], "servers": { "vapi": { "type": "http", - "url": "https://mcp.vapi.ai/mcp", - "headers": { - "Authorization": "Bearer ${input:vapi-api-key}" - } + "url": "https://mcp.vapi.ai/mcp" } } } ``` - Start `vapi` from **MCP: List Servers** and enter your API key when prompted. Then use a **Local** chat session and enable the server's tools. Other session types can't prompt for the key, so this server isn't available in them. + Start `vapi` from **MCP: List Servers**. VS Code opens a browser window for the Vapi sign-in on the first connection. Then enable the server's tools in a chat session. See [VS Code MCP setup](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). - Claude Desktop's configuration file runs local commands, so use `mcp-remote` as a bridge to the hosted server. This requires Node.js and `npx` to be available to Claude Desktop. + Claude Desktop connects to remote servers as a custom connector, so no local bridge is needed. - Open **Settings → Developer → Edit Config**. Add this entry to `claude_desktop_config.json`, preserving any other servers: + Open **Customize → Connectors**, click **+ Add**, then **Add custom connector**. Enter a name and `https://mcp.vapi.ai/mcp` as the remote MCP server URL, then click **Continue**. Leave the OAuth client option on **Register automatically**, finish with **Add**, then click **Connect** on the new connector and sign in to Vapi in your browser. - ```json - { - "mcpServers": { - "vapi": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "https://mcp.vapi.ai/mcp", - "--transport", - "http-only", - "--header", - "Authorization: Bearer ${VAPI_API_KEY}" - ], - "env": { - "VAPI_API_KEY": "YOUR_VAPI_API_KEY" - } - } - } - } - ``` + On Team and Enterprise plans, an organization Owner adds the connector under **Organization settings → Connectors**. - Replace `YOUR_VAPI_API_KEY` with your Vapi API key and restart Claude Desktop. Keep this configuration private and update the key after rotating it. The bridge runs locally; Vapi's MCP server stays hosted. + See [custom connectors via remote MCP](https://support.claude.com/en/articles/11175166-about-custom-connectors-via-remote-mcp). Once connected, try asking your agent: "List my Vapi assistants." +## How signing in works + +When your agent first connects, Vapi's server tells it where to sign in, and the agent opens that page in your browser. You sign in with your Vapi account — the same credentials, MFA, and SSO you use for the dashboard — and choose which organization the agent may act in. The agent then receives a short-lived access token and refreshes it as needed. + +What this means day to day: + +- **Your agent acts as you.** Every tool call runs with your own role and permissions in the organization you picked. A teammate connecting the same way sees only what their role allows. +- **One organization per connection.** To switch organizations, sign out and reconnect: `claude mcp logout vapi` then `claude mcp login vapi` in Claude Code, or the equivalent in your agent. Use the `get_connection_info` tool to check which user and organization the current connection is authorized as. +- **Some actions are always off-limits.** The hosted server can't read or create API keys, provider credentials, or billing settings, even if you're an admin. +- **Access follows your account.** Removing someone from your Vapi organization ends their agent's access; there's no separate key to find and rotate. + - **Replacing an older setup?** Existing configurations that use `@vapi-ai/mcp-docs-server` from an earlier CLI release, or the deprecated `https://mcp.vapi.ai/sse` endpoint, don't update automatically. Replace that entry with the hosted connection above, which includes documentation search, or see [Search the docs without an API key](#search-the-docs-without-an-api-key) for access without an API key. + **Upgrading from API key authentication?** Before November 10, 2026, the hosted server accepted a Vapi API key in an `Authorization: Bearer` header, and also served the `https://mcp.vapi.ai/sse` endpoint. Both have been removed. Replace your existing `vapi` entry with the configuration for your agent above — delete the `headers` block or `--bearer-token-env-var` flag, keep the same `https://mcp.vapi.ai/mcp` URL, and sign in. If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, replace that entry too; the hosted server includes documentation search. For documentation-only access with no sign-in at all, see [Search the docs without signing in](#search-the-docs-without-signing-in). Existing agent configurations are not changed automatically, and Vapi API keys continue to work for the [Vapi API](/api-reference) itself. ## Run the server locally You can run the open-source [Vapi MCP server](https://github.com/VapiAI/mcp-server) on your own machine instead of connecting to the hosted one, for example to develop against it. This requires Node.js. Your client starts the server as a subprocess and talks to it over stdio, so no HTTP endpoint is started. +The local server authenticates with a [Vapi API key](/security-and-privacy/api-keys) rather than sign-in, which also makes it the option for unattended automation. Because an API key carries full organization access, keep this configuration private. + Add this entry to your client's MCP configuration in place of the hosted connection. The local server reads your API key from `VAPI_TOKEN`: ```json @@ -178,9 +159,9 @@ In Claude Code, run: claude mcp add -e VAPI_TOKEN=YOUR_VAPI_API_KEY vapi -- npx -y @vapi-ai/mcp-server ``` -## Search the docs without an API key +## Search the docs without signing in -For documentation search alone, connect your agent to Vapi's documentation MCP server at `https://docs.vapi.ai/_mcp/server`. It needs no API key and provides a `searchDocs` tool. The Vapi MCP server's `ask_vapi_docs` tool runs the same search. +For documentation search alone, connect your agent to Vapi's documentation MCP server at `https://docs.vapi.ai/_mcp/server`. It needs no account and provides a `searchDocs` tool. The Vapi MCP server's `ask_vapi_docs` tool runs the same search. If your client can't connect to a remote server directly, run it through the `mcp-remote` adapter: @@ -197,7 +178,13 @@ If your client can't connect to a remote server directly, run it through the `mc ## Available tools -The Vapi MCP server exposes these tools. The hosted server and the [local server](#run-the-server-locally) expose the same set. +The Vapi MCP server exposes the tools below. The hosted server and the [local server](#run-the-server-locally) expose the same set, except for `get_connection_info`, which only the hosted server provides. + +### Connection + +| Tool | Description | +|-----------------------|-------------------------------------------------------------------------------------| +| `get_connection_info` | Show the Vapi user, organization, and OAuth client this connection is authorized as | ### Documentation and reference @@ -272,59 +259,31 @@ These tools drive [simulations](/observability/simulations-overview), which test Each `run_simulations` tool call starts a billed simulation run. For more information, see [Simulations overview](/observability/simulations-overview). +Which tools succeed depends on your role in the organization you signed in to. A call that your role doesn't permit fails with an authorization error. + ## Use the server from your own code -Connect any MCP client to `https://mcp.vapi.ai/mcp` over Streamable HTTP, and send your Vapi API key in the `Authorization: Bearer YOUR_VAPI_API_KEY` header. +Any MCP client can connect to `https://mcp.vapi.ai/mcp` over Streamable HTTP, but it has to complete the same browser sign-in; the server rejects Vapi API keys. Requests without a valid token are answered with `401` and a `WWW-Authenticate` challenge pointing at the server's metadata at `https://mcp.vapi.ai/.well-known/oauth-protected-resource/mcp`, which is how clients discover where to sign in. -### OpenAI Responses API + + Signing in requires a person at a browser, and the resulting tokens are short-lived. For unattended server-to-server automation, call the [Vapi API](/api-reference) directly with an API key, or [run the server locally](#run-the-server-locally) with `VAPI_TOKEN`. + -The OpenAI Responses API can call remote MCP servers. See [OpenAI's remote MCP guide](https://platform.openai.com/docs/guides/tools-remote-mcp). +The simplest option is the `mcp-remote` adapter, which performs the sign-in once, caches the tokens under `~/.mcp-auth`, and exposes the server over stdio: - -```typescript title="typescript" -import OpenAI from 'openai'; -// Replace with your actual OpenAI API key -const openai = new OpenAI({ apiKey: 'YOUR_OPENAI_API_KEY' }); -async function main() { - const response = await openai.responses.create({ - model: 'gpt-4.1', - tools: [ - { - type: 'mcp', - server_label: 'vapi-mcp', - server_url: 'https://mcp.vapi.ai/mcp', - headers: { "Authorization": "Bearer YOUR_VAPI_API_KEY" } - }, - ], - input: 'What vapi tools do you have available?', - }); - console.dir(response, { depth: null }); -} -main(); -``` -```python title="python" -import openai -# Replace with your actual OpenAI API key -openai.api_key = 'YOUR_OPENAI_API_KEY' -response = openai.responses.create( - model="gpt-4.1", - tools=[ - { - "type": "mcp", - "server_label": "vapi-mcp", - "server_url": "https://mcp.vapi.ai/mcp", - "headers": {"Authorization": "Bearer YOUR_VAPI_API_KEY"} - }, - ], - input="What vapi tools do you have available?", -) -print(response) +```bash +npx -y mcp-remote https://mcp.vapi.ai/mcp ``` - + +### Hosted agent platforms + +Platforms that call remote MCP servers on your behalf, such as the [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp), can use the hosted server, but they need an access token from the sign-in flow rather than a Vapi API key, and the server must be reachable from that platform's infrastructure. ### MCP client SDKs -Official MCP SDKs are available for [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), and [C#](https://github.com/modelcontextprotocol/csharp-sdk). This minimal Node.js client lists your assistants: +Official MCP SDKs are available for [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), and [C#](https://github.com/modelcontextprotocol/csharp-sdk). They include OAuth helpers that run the sign-in and refresh tokens for you; see the [MCP authorization spec](https://modelcontextprotocol.io/specification/basic/authorization) for how the flow works. + +If you already hold a valid access token, pass it to the transport. This minimal Node.js client lists your assistants: ```javascript import { Client } from '@modelcontextprotocol/sdk/client/index.js'; @@ -336,7 +295,7 @@ dotenv.config(); const mcpClient = new Client({ name: 'vapi-client', version: '1.0.0' }); const transport = new StreamableHTTPClientTransport( new URL('https://mcp.vapi.ai/mcp'), - { requestInit: { headers: { Authorization: `Bearer ${process.env.VAPI_API_KEY}` } } } + { requestInit: { headers: { Authorization: `Bearer ${process.env.VAPI_MCP_ACCESS_TOKEN}` } } } ); async function main() { @@ -349,6 +308,8 @@ async function main() { main(); ``` +`VAPI_MCP_ACCESS_TOKEN` is an access token from the sign-in flow, not a Vapi API key. It expires, so production clients should use an SDK OAuth provider that refreshes it instead of a token pasted into the environment. + This fuller example lists tools, assistants, and phone numbers, then creates a call: ```javascript @@ -360,9 +321,9 @@ import dotenv from 'dotenv'; // Load environment variables from .env file dotenv.config(); -// Ensure API key is available -if (!process.env.VAPI_API_KEY) { - console.error('Error: VAPI_API_KEY environment variable is required'); +// Ensure an access token from the sign-in flow is available +if (!process.env.VAPI_MCP_ACCESS_TOKEN) { + console.error('Error: VAPI_MCP_ACCESS_TOKEN environment variable is required'); process.exit(1); } @@ -376,7 +337,7 @@ async function main() { // Create Streamable HTTP transport for connection to remote Vapi MCP server const serverUrl = 'https://mcp.vapi.ai/mcp'; const headers = { - Authorization: `Bearer ${process.env.VAPI_API_KEY}`, + Authorization: `Bearer ${process.env.VAPI_MCP_ACCESS_TOKEN}`, }; const options = { requestInit: { headers: headers }, From 7b2af2dd9eef0e9b226b1af14a5c1d70833ee30c Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Tue, 10 Nov 2026 14:23:59 -0500 Subject: [PATCH 6/7] docs: restore the OpenAI Responses API example, corrected for OAuth Dropping this example in the OAuth rewrite left the page with no Python or TypeScript sample, which #1410 had. Restoring it keeps that coverage. The old example passed `headers: {"Authorization": "Bearer "}`. That was wrong twice over: the Responses API takes an `authorization` field and has no `headers` field, and the hosted server no longer takes API keys. The restored example uses `authorization` with an access token from the sign-in flow, and notes that the token is short-lived and that the API asks for approval unless `require_approval` is set. Also updates the OpenAI docs link, which now redirects to developers.openai.com/api/docs/guides/tools-connectors-mcp. Co-Authored-By: Claude Opus 5 --- fern/sdk/mcp-server.mdx | 48 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index 1eed9705b..4258515a7 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -277,7 +277,53 @@ npx -y mcp-remote https://mcp.vapi.ai/mcp ### Hosted agent platforms -Platforms that call remote MCP servers on your behalf, such as the [OpenAI Responses API](https://platform.openai.com/docs/guides/tools-remote-mcp), can use the hosted server, but they need an access token from the sign-in flow rather than a Vapi API key, and the server must be reachable from that platform's infrastructure. +Platforms that call remote MCP servers on your behalf, such as the [OpenAI Responses API](https://developers.openai.com/api/docs/guides/tools-connectors-mcp), can use the hosted server. Pass an access token from the sign-in flow in the `authorization` field, not a Vapi API key: + + +```typescript title="typescript" +import OpenAI from 'openai'; + +const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); + +const response = await openai.responses.create({ + model: 'gpt-4.1', + tools: [ + { + type: 'mcp', + server_label: 'vapi', + server_url: 'https://mcp.vapi.ai/mcp', + authorization: process.env.VAPI_MCP_ACCESS_TOKEN, + }, + ], + input: 'List my Vapi assistants.', +}); + +console.dir(response, { depth: null }); +``` +```python title="python" +import os +from openai import OpenAI + +client = OpenAI(api_key=os.environ["OPENAI_API_KEY"]) + +response = client.responses.create( + model="gpt-4.1", + tools=[ + { + "type": "mcp", + "server_label": "vapi", + "server_url": "https://mcp.vapi.ai/mcp", + "authorization": os.environ["VAPI_MCP_ACCESS_TOKEN"], + }, + ], + input="List my Vapi assistants.", +) + +print(response) +``` + + +The token is short-lived and the platform does not store it, so send a current one with every request. The Responses API also asks for your approval before calling a remote server unless you set `require_approval`. ### MCP client SDKs From 0f9e71d8ff1819075a17b7ac93808c4ad4ce6b8f Mon Sep 17 00:00:00 2001 From: Chris Garber Date: Tue, 10 Nov 2026 17:07:27 -0500 Subject: [PATCH 7/7] docs: apply review feedback on the OAuth sign-in changes Address stephenvapiai's review on #1411: - Point the Overview at "How signing in works" instead of describing the browser flow twice. - Give the Claude Desktop connector setup a Steps block, so each step is numbered and linkable. - Promote the upgrade callout to its own "Upgrade from API key authentication" section. It held required steps, which don't belong in a callout, and it now appears in the right-hand nav. - Split the sign-in, 401 challenge, and access token paragraphs into one idea per sentence. - Fix the MCP authorization spec link, which 404s without a version segment in the path. - Avoid starting a sentence with a code identifier. Co-Authored-By: Claude Opus 5 --- fern/sdk/mcp-server.mdx | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/fern/sdk/mcp-server.mdx b/fern/sdk/mcp-server.mdx index 4258515a7..a640a0364 100644 --- a/fern/sdk/mcp-server.mdx +++ b/fern/sdk/mcp-server.mdx @@ -9,7 +9,7 @@ description: Connect Codex, Claude Code, Hermes, Cursor, VS Code, or Claude Desk The **Vapi MCP server** gives AI agents Vapi tools over the Model Context Protocol (MCP). Once connected, your agent can search Vapi's documentation and manage your assistants, phone numbers, and calls. -Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP** transport. You connect by signing in with your Vapi account: your agent opens a browser, you sign in and pick an organization, and the agent receives a short-lived token. No API key is involved, and you don't need the Vapi CLI. You can also [run the server locally](#run-the-server-locally). +Vapi hosts the server at `https://mcp.vapi.ai/mcp`, using the **Streamable HTTP** transport. You connect by [signing in with your Vapi account](#how-signing-in-works), not with an API key, and you don't need the Vapi CLI. You can also [run the server locally](#run-the-server-locally). Looking to use MCP tools *inside* a Vapi assistant? See [MCP tools](/tools/mcp). @@ -106,7 +106,20 @@ The hosted server uses OAuth, so there's nothing to copy and paste. Add the URL Claude Desktop connects to remote servers as a custom connector, so no local bridge is needed. - Open **Customize → Connectors**, click **+ Add**, then **Add custom connector**. Enter a name and `https://mcp.vapi.ai/mcp` as the remote MCP server URL, then click **Continue**. Leave the OAuth client option on **Register automatically**, finish with **Add**, then click **Connect** on the new connector and sign in to Vapi in your browser. + + + Open **Customize**, then **Connectors**. Click **+ Add**, then click **Add custom connector**. + + + Enter a name, and enter `https://mcp.vapi.ai/mcp` as the remote MCP server URL. Click **Continue**. + + + Leave the OAuth client option on **Register automatically**, then click **Add**. + + + Click **Connect** on the new connector and sign in to Vapi in your browser. + + On Team and Enterprise plans, an organization Owner adds the connector under **Organization settings → Connectors**. @@ -118,7 +131,7 @@ Once connected, try asking your agent: "List my Vapi assistants." ## How signing in works -When your agent first connects, Vapi's server tells it where to sign in, and the agent opens that page in your browser. You sign in with your Vapi account — the same credentials, MFA, and SSO you use for the dashboard — and choose which organization the agent may act in. The agent then receives a short-lived access token and refreshes it as needed. +When your agent first connects, Vapi's server tells it where to sign in, and the agent opens that page in your browser. You sign in with your Vapi account and choose which organization the agent may act in. Sign-in uses the same credentials, MFA, and SSO as the dashboard. The agent then receives a short-lived access token and refreshes it as needed. What this means day to day: @@ -127,9 +140,19 @@ What this means day to day: - **Some actions are always off-limits.** The hosted server can't read or create API keys, provider credentials, or billing settings, even if you're an admin. - **Access follows your account.** Removing someone from your Vapi organization ends their agent's access; there's no separate key to find and rotate. - - **Upgrading from API key authentication?** Before November 10, 2026, the hosted server accepted a Vapi API key in an `Authorization: Bearer` header, and also served the `https://mcp.vapi.ai/sse` endpoint. Both have been removed. Replace your existing `vapi` entry with the configuration for your agent above — delete the `headers` block or `--bearer-token-env-var` flag, keep the same `https://mcp.vapi.ai/mcp` URL, and sign in. If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, replace that entry too; the hosted server includes documentation search. For documentation-only access with no sign-in at all, see [Search the docs without signing in](#search-the-docs-without-signing-in). Existing agent configurations are not changed automatically, and Vapi API keys continue to work for the [Vapi API](/api-reference) itself. - +## Upgrade from API key authentication + +Before November 10, 2026, the hosted server accepted a Vapi API key in an `Authorization: Bearer` header and also served the `https://mcp.vapi.ai/sse` endpoint. Both have been removed, and existing agent configurations don't update automatically. + +To upgrade an existing `vapi` entry: + +- Delete the `headers` block or the `--bearer-token-env-var` flag. +- Keep the same `https://mcp.vapi.ai/mcp` URL. +- Sign in using the steps for your agent in [Connect your agent](#connect-your-agent). + +If your agent uses `@vapi-ai/mcp-docs-server` from an earlier CLI release, replace that entry too, because the hosted server includes documentation search. For documentation-only access with no sign-in, see [Search the docs without signing in](#search-the-docs-without-signing-in). + +Vapi API keys still work for the [Vapi API](/api-reference). ## Run the server locally @@ -263,7 +286,7 @@ Which tools succeed depends on your role in the organization you signed in to. A ## Use the server from your own code -Any MCP client can connect to `https://mcp.vapi.ai/mcp` over Streamable HTTP, but it has to complete the same browser sign-in; the server rejects Vapi API keys. Requests without a valid token are answered with `401` and a `WWW-Authenticate` challenge pointing at the server's metadata at `https://mcp.vapi.ai/.well-known/oauth-protected-resource/mcp`, which is how clients discover where to sign in. +Any MCP client can connect to `https://mcp.vapi.ai/mcp` over Streamable HTTP, but it has to complete the same browser sign-in. The server rejects Vapi API keys. A request without a valid token gets a `401` response with a `WWW-Authenticate` challenge. The challenge points to the server's metadata at `https://mcp.vapi.ai/.well-known/oauth-protected-resource/mcp`, which tells the client where to sign in. Signing in requires a person at a browser, and the resulting tokens are short-lived. For unattended server-to-server automation, call the [Vapi API](/api-reference) directly with an API key, or [run the server locally](#run-the-server-locally) with `VAPI_TOKEN`. @@ -327,7 +350,7 @@ The token is short-lived and the platform does not store it, so send a current o ### MCP client SDKs -Official MCP SDKs are available for [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), and [C#](https://github.com/modelcontextprotocol/csharp-sdk). They include OAuth helpers that run the sign-in and refresh tokens for you; see the [MCP authorization spec](https://modelcontextprotocol.io/specification/basic/authorization) for how the flow works. +Official MCP SDKs are available for [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), and [C#](https://github.com/modelcontextprotocol/csharp-sdk). They include OAuth helpers that run the sign-in and refresh tokens for you; see the [MCP authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization) for how the flow works. If you already hold a valid access token, pass it to the transport. This minimal Node.js client lists your assistants: @@ -354,7 +377,7 @@ async function main() { main(); ``` -`VAPI_MCP_ACCESS_TOKEN` is an access token from the sign-in flow, not a Vapi API key. It expires, so production clients should use an SDK OAuth provider that refreshes it instead of a token pasted into the environment. +The `VAPI_MCP_ACCESS_TOKEN` variable holds an access token from the sign-in flow, not a Vapi API key. It expires, so production clients should use an SDK OAuth provider that refreshes it instead of a token pasted into the environment. This fuller example lists tools, assistants, and phone numbers, then creates a call: