Use Vapi MCP on Cursor – Installation Guide and Demo – Its awesome! walks you through getting Vapi’s new MCP server running inside the Cursor IDE so you can create calls or build agents without leaving the editor, and Henryk Brzozowski’s video shows practical steps to make setup smooth. You’ll see how to configure Cursor to launch the MCP server and how using it directly in the IDE speeds up development.
The article outlines two setup options: one that runs npx @vapi-ai/mcp-server directly and another that uses cmd /c for Windows, with both requiring you to set VAPI_TOKEN in the env section of the mcpServers JSON. You’ll also get quick tips on starting the server and using it to call or build agents from within Cursor.
Prerequisites
Before you start, make sure you have the basic environment and accounts set up so the installation and demo go smoothly. This section lists the platforms, Node.js requirements, account needs, network considerations, and recommended development environment choices you should check off before integrating Vapi MCP into Cursor.
Supported platforms and Cursor IDE versions required to run Vapi MCP
You can run the Vapi MCP server from Cursor on the common desktop platforms: Linux, macOS, and Windows. Cursor itself receives frequent updates, so you should use a recent release of the Cursor IDE that supports project-level server/process configuration. If you’re unsure which Cursor version you have, open Cursor and check its About or Help menu for the version string. Newer Cursor builds support the mcpServers configuration block described below; if your Cursor is very old, upgrade before proceeding to avoid compatibility issues.
Node.js and npm requirements and recommended versions
The MCP server is distributed as an npm package and is launched via npx, so you need a recent Node.js and npm installation. Aim for an active LTS Node.js version (for example, Node 16 or Node 18 or newer) and a matching npm (npm 8+). If you use very old Node/npm, npx behavior may differ. Confirm npx is available on your PATH by running npx –version in a terminal. If npx is missing, install a suitable Node.js release that includes npm and npx.
Access to a Vapi account and how to obtain a VAPI_TOKEN
To operate the MCP server you need a Vapi account with a token that authorizes API calls. Sign in to your Vapi account and find the developer or API tokens area in your account settings where you can create personal access tokens. Generate a token with the minimal scopes needed for the MCP workflows you plan to run, copy the token value, and treat it like a password: store it securely, and do not commit it to git. The token will be referenced as VAPI_TOKEN in your Cursor configuration or environment.
Network requirements: firewall, ports, and local development considerations
When the MCP server launches it will open a port to accept requests from Cursor and other local tooling. Ensure your local firewall allows loops on localhost and that corporate firewall policies do not block the port chosen by the server. If you run multiple MCP instances, pick different ports or allow the server to allocate an available port. For cloud or remote development setups, ensure any necessary port forwarding or SSH tunnels are configured so Cursor can reach the MCP server. For local development, the server typically binds to localhost; avoid binding to 0.0.0.0 unless you understand the security implications.
Recommended development environment: terminal, Windows vs. macOS vs. Linux caveats
Work in a terminal you’re comfortable with. On macOS and Linux, bash or zsh terminals are fine; on Windows, use cmd, PowerShell, or Windows Terminal. Windows sometimes requires an explicit cmd /c wrapper when launching console commands from GUI processes—this is why the Windows-specific mcpServers example below uses cmd /c. Also on Windows, be mindful of CRLF line endings in files and Windows file permission quirks. If you use WSL on Windows, you can prefer the Linux-style configuration but be careful about where Cursor and Node are running (host vs WSL) to avoid PATH mismatches.
Preparing Cursor for MCP Integration
This section explains how Cursor uses a project configuration to spawn external servers, where to place the configuration, and what to validate before you try to launch the MCP server.
How Cursor’s mcpServers configuration works and where to place it
Cursor lets you define external processes that should be managed alongside a project through an mcpServers configuration block inside your project settings. This block instructs Cursor how to spawn a process (command and args) and which environment variables to provide. Place this block in your project configuration file (a Cursor project or workspace settings file). Typical places are a top-level cursor.json or a .cursor/config.json in your project root depending on your Cursor setup. The key point is to add the mcpServers block to the project-specific configuration file that Cursor reads when opening the workspace.
Creating or editing your Cursor project configuration to add an MCP server entry
Open your project configuration file in Cursor (or your editor) and add an mcpServers object containing a named server entry for the Vapi MCP server. Name the entry with something recognizable like “vapi-mcp-server” or “vapi”. Paste the JSON structure for the command, args, and env as shown in later sections. Save the file and then restart or reload Cursor so it picks up the new server declaration and attempts to spawn it automatically.
Backing up existing Cursor settings before adding new server configuration
Before you edit Cursor configuration files, make a quick backup of the existing file(s). Copy the file to a safe location or commit the current state to version control (but avoid committing secrets). That way, if your changes cause Cursor to behave unexpectedly, you can restore the previous configuration quickly.
Permissions and file paths that may affect Cursor launching the MCP server
Cursor needs permission to spawn processes and to access the configured Node/npm runtime. Check that your user account has execute permission for the Node and npm binaries and that Cursor is launched with a user context that can run npx. On Linux and macOS ensure the project files and the configuration file are readable by your user. On Windows, if Cursor runs elevated or under a different account, confirm environmental differences won’t break execution. Also make sure antivirus or endpoint protection isn’t blocking npx downloads or process creation.
Validating Cursor can execute npx commands from its environment
Before relying on Cursor to launch the MCP server, validate that the environment Cursor inherits can run npx. Open a terminal from the same environment you launch Cursor from and run npx –version and npx -y @vapi-ai/mcp-server –help (or a dry run) to verify npx resolves and can download packages. If Cursor is launched by a desktop launcher, it might not pick up shell profile modifications—start Cursor from a terminal to ensure it inherits the same PATH and environment variables.
MCP Server Configuration Options for Cursor
Here you get two ready-to-use JSON options for the Cursor mcpServers block: one suited for Linux/macOS and one adapted for Windows. Both examples set VAPI_TOKEN in the env block; use placeholders or prefer system environment injection for security.
Option 1 JSON example for Linux/macOS environments
This JSON is intended for Unix-like environments where you can call npx directly. Paste it into your Cursor project configuration to register the MCP server:
{ “mcpServers”: { “vapi-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@vapi-ai/mcp-server” ], “env”: { “VAPI_TOKEN”: “Your key here” } } } }
Option 2 JSON example adapted for Windows (cmd /c) environments
On Windows, GUI-launched processes sometimes require cmd /c to run a compound command line reliably. Use this JSON in your Cursor configuration on Windows:
{ “mcpServers”: { “vapi”: { “command”: “cmd”, “args”: [ “/c”, “npx”, “-y”, “@vapi-ai/mcp-server” ], “env”: { “VAPI_TOKEN”: “Your key here” } } } }
Option 1: { “mcpServers”: { “vapi-mcp-server”: { “command”: “npx”, “args”: [ “-y”, “@vapi-ai/mcp-server” ], “env”: { “VAPI_TOKEN”: “Your key here” } } } }
This is the explicit Unix-style example again so you can copy-paste it into your config. It instructs Cursor to run the npx command with arguments that automatically accept prompts (-y) and install/run the @vapi-ai/mcp-server package, while providing VAPI_TOKEN in the environment.
Option 2: { “mcpServers”: { “vapi”: { “command”: “cmd”, “args”: [ “/c”, “npx”, “-y”, “@vapi-ai/mcp-server” ], “env”: { “VAPI_TOKEN”: “Your key here” } } } }
This Windows variant wraps the npx invocation inside cmd /c to ensure the command line is interpreted correctly by the Windows shell when Cursor launches it. The env block again provides the VAPI_TOKEN to the spawned process.
Explaining each field: command, args, env and how Cursor uses them to spawn the MCP server
- command: the executable Cursor runs directly. It must be reachable from Cursor’s PATH. For Unix-like systems you typically use npx; on Windows you may use cmd to invoke complex commands.
- args: an array of command-line arguments passed to the command. For npx, args include -y and the package name @vapi-ai/mcp-server. When using cmd, args begins with /c followed by the command to execute.
- env: an object mapping environment variable names to values provided to the spawned process. Inclusion here ensures the server receives VAPI_TOKEN and any other required settings. Cursor merges or overrides environment variables for the spawned process based on this block. Cursor reads this configuration when opening the project and uses it to spawn the MCP server as a child process under the Cursor-managed session.
Installing Vapi MCP via Cursor
This section walks you through adding the configuration, letting Cursor run npx to install and start the server, what npx -y does, and how to verify the server started.
Step-by-step: adding the mcpServers block to Cursor configuration (where to paste it)
Open your project’s Cursor settings file (cursor.json or .cursor/config.json) and paste one of the provided mcpServers blocks into it. Use the Unix example for macOS/Linux and the cmd-wrapped example for Windows. Replace “Your key here” with your actual token placeholder approach, or leave a placeholder and use an OS-level env so you don’t commit secrets. Save the file, then restart Cursor so it re-reads the configuration and attempts to spawn the server.
Running Cursor to auto-install and start the MCP server using npx
When Cursor starts with the mcpServers block present, it will spawn the configured command. npx will then fetch the @vapi-ai/mcp-server package (if not cached) and execute it. Cursor’s output panel or server logs will show npx progress and the MCP server startup logs. This process both installs and runs the MCP server in one step.
What the npx -y @vapi-ai/mcp-server command does during installation
npx downloads the package @vapi-ai/mcp-server from the npm registry (or uses a cached local copy) and executes its entry point. The -y flag typically skips interactive confirmation prompts. The server starts immediately after download and executes with the environment variables Cursor provided. Because npx runs the package in a temporary context, this can be used for ephemeral launches; installing a global or local package is optional if you want persistence.
Verifying that the MCP server process started successfully from Cursor
Watch Cursor’s server process logs or the integrated terminal area for messages indicating the MCP server is up and listening. Typical confirmation includes a startup message that shows the listening port and a ready state. You can also check running processes on your machine (ps on Unix, Task Manager or Get-Process on Windows) to confirm a node process corresponding to the package is active. Finally, test the endpoint expected by Cursor by initiating a simple create-call or a health check using the Cursor UI if it exposes one.
Tips for persistent installs vs ephemeral launches inside Cursor
If you want a persistent installation, consider installing @vapi-ai/mcp-server in your project (npm install –save-dev @vapi-ai/mcp-server) and then change the command to run node ./node_modules/.bin/@vapi-ai/mcp-server or reference the local binary. Ephemeral launches via npx are convenient for demos and quick starts but will redownload if cache expires. For CI or repeatable developer setups, prefer a local install tracked in package.json.
Running the MCP Server Manually and From Cursor
Understand the differences between letting Cursor manage the process and running it manually for testing and debugging.
Differences between letting Cursor manage the process and manual local runs
When Cursor manages the process it ties server lifecycle to your project session: Cursor can stop, restart, and show logs. Manual runs give you full terminal control and let you iterate quickly without restarting Cursor. Cursor-managed runs are convenient for integrated workflows, while manual runs are preferable when you need to debug startup problems or want persistent background services.
How to run the MCP server manually with the same environment variables for testing
Open a terminal and run the same command you configured in Cursor, setting VAPI_TOKEN in the environment. For example on macOS/Linux:
export VAPI_TOKEN=”your-token” npx -y @vapi-ai/mcp-server
On Windows PowerShell:
$env:VAPI_TOKEN = “your-token” npx -y @vapi-ai/mcp-server
This reproduces the Cursor-managed environment so you can check startup logs and verify token handling before integrating it back into Cursor.
Windows-specific command example using cmd /c and why it’s needed
If you want to emulate Cursor’s Windows behavior, run:
cmd /c “set VAPI_TOKEN=your-token&& npx -y @vapi-ai/mcp-server”
The cmd /c wrapper ensures the command line and environment are handled in the same way Cursor would when it launches cmd as the process.
How to confirm the correct VAPI_TOKEN was picked up by the server process
The server typically logs that a token was present or that authentication succeeded on first handshake—watch for such messages. You can also trigger an API call that requires authentication and check for a successful response. If you prefer not to expose the token in logs, verify by making an authenticated request from Cursor or curl and observing the expected result rather than the token itself.
Graceful shutdown and restart procedures when making configuration changes
To change configuration or rotate tokens, stop the MCP server gracefully via Cursor’s server controls or by sending SIGINT (Ctrl+C) in the terminal where it runs. Wait for the server to clean up, update environment values or the Cursor config, then restart the server. Avoid killing the process abruptly to prevent state corruption or orphaned resources.
Using Environment Variables and Token Management
Managing your VAPI_TOKEN and other secrets safely is critical. This section covers secure storage, injecting into Cursor config, token rotation, and differences between local and CI environments.
Where to store your VAPI_TOKEN securely when using Cursor (env files, OS env)
Prefer OS environment variables or a local env file (.env) that is gitignored to avoid committing secrets. You can export VAPI_TOKEN in your shell profile for local development and ensure .env is listed in .gitignore. Avoid placing plain tokens directly in committed configuration files.
How to inject secrets into Cursor’s mcpServers env block safely
Avoid pasting real tokens into the committed config. Instead, use placeholders in the config and set the VAPI_TOKEN in the environment that launches Cursor. If Cursor supports interpolation, you can reference system env variables like VAPI_TOKEN directly; otherwise launch Cursor from a shell where VAPI_TOKEN is exported so the spawned process inherits it.
Rotating tokens: steps to update VAPI_TOKEN without breaking running agents
To rotate a token, generate a new token in your Vapi account, set it into your environment or update your .env file, then gracefully restart the MCP server so it picks up the new value. If you run agents that maintain long-lived connections, coordinate rotation to avoid interrupted runs: deploy the new token, restart the server, and confirm agent health.
Local vs CI: differences in handling credentials when running tests or demos
In CI, store tokens in the CI provider’s secret store and inject them into the build environment (never echo tokens into logs). Local demos can use local env variables or a developer-managed .env file. CI tends to be ephemeral and reproducible; make sure your CI pipeline uses the same commands as Cursor would and that secrets are provided at runtime.
Validating token scope and common authentication errors to watch for
If an agent creation or API call fails with unauthorized or forbidden errors, verify the token’s scope includes the operations you’re attempting. Check for common mistakes like copying a token with surrounding whitespace, accidentally pasting a partial token, or using an expired token. Correct scope and freshness are the main culprits for authentication issues.
Creating Calls and Building Agents from Cursor
Once the MCP server is running, Cursor can communicate with it to create calls or full agents. This section explains how that interaction typically looks and how to iterate quickly.
How Cursor communicates with the MCP server to create API calls or agents
Cursor sends HTTP or RPC requests to the MCP server endpoints to create calls, agents, or execute agent steps. The MCP server then talks to the Vapi backend using the provided VAPI_TOKEN to perform actions on your behalf. Cursor’s UI exposes actions that trigger these endpoints, letting you author agent logic and run it from the editor.
Example workflow: create a new agent within Cursor using Vapi MCP endpoints
A simple workflow: open Cursor, create a new agent definition file or use the agent creation UI, then invoke the “create-agent” action which sends a JSON payload to the MCP server. The server validates the request, uses your token to create the agent on Vapi or locally, and returns a response describing the created agent ID and metadata. You can then test the agent by sending sample inputs from Cursor.
Sample payloads and typical responses when invoking create-call or create-agent
Sample create-call payload (illustrative): { “type”: “create-call”, “name”: “hello-world”, “input”: { “text”: “Hello” }, “settings”: { “model”: “default” } }
Typical successful response: { “status”: “ok”, “callId”: “call_12345”, “result”: { “output”: “Hello, world!” } }
Sample create-agent payload (illustrative): { “type”: “create-agent”, “name”: “my-assistant”, “definition”: { “steps”: […agent logic…] } }
Typical response: { “status”: “created”, “agentId”: “agent_67890”, “metadata”: { “version”: “1.0” } }
These examples are generic; actual fields depend on the MCP server API. Use Cursor’s response pane to inspect exact fields returned.
Using Cursor editor features to author agent logic and test from the same environment
Author agent definitions in Cursor’s editor, then use integrated commands or context menus to send the current buffer to the MCP server for creation or testing. The tight feedback loop means you can modify logic, re-run the create-call or run-agent action, and observe results in the same workspace without switching tools.
Tips for iterating quickly: hot reloading, logs, and live testing within Cursor
Keep logs visible in Cursor while you iterate. If the MCP server supports hot reload of agent definitions, leverage that feature to avoid full restarts. Use small, focused tests and clear log statements in your agent steps to help diagnose behavior quickly. Maintain test inputs and expected outputs as you iterate to ensure regressions are caught early.
Demo Walkthrough: Step-by-Step Example
This walkthrough describes a short demo you can run in Cursor once your configuration is ready.
Preparation: ensure Cursor is open and mcpServers configuration is added
Open Cursor with the project that contains your mcpServers block. Confirm the configuration is saved and that you have exported VAPI_TOKEN in your shell or added it via an environment mechanism Cursor will inherit.
Start the MCP server from Cursor and watch installation logs
Start or reload the project in Cursor so it spawns the MCP server. Watch the installation lines from npx, then the MCP server startup logs which indicate readiness and the listening port. If you see errors, address them (missing npx, permission, or token issues).
Create a simple call or agent from Cursor and show the generated output
Use Cursor’s command to create a simple call—send a small payload like “Hello” via the create-call action. Observe the returned callId and output in Cursor’s response pane. If you create an agent, check the returned agentId and metadata.
Verify agent behavior with sample inputs and examine responses
Run a few sample inputs through the agent using Cursor’s test features or by sending requests directly to the server endpoint. Inspect responses for correctness and verify the agent uses the expected model and settings. If something is off, update the definition and re-run.
Recording or sharing the demo: best practices (timestamps, logging, reproducibility)
If you plan to record or share your demo, enable detailed logging and include timestamps in your logs so viewers can follow the sequence. Use a reproducible environment: include package.json and a documented setup in the project so others can repeat the demo. Avoid sharing your VAPI_TOKEN in recordings.
Troubleshooting and Common Issues
Here are common problems you may encounter and practical steps to resolve them.
What to do if Cursor fails to start the MCP server: common error messages and fixes
If Cursor fails to start the server, check for errors like “npx: command not found” (install Node/npm or adjust PATH), permission denied (fix file permissions), or network errors (check your internet for package download). Look at Cursor’s logs to see the exact npx failure message and address it accordingly.
Diagnosing permission or path issues when Cursor runs npx
If npx works in your terminal but not in Cursor, start Cursor from the same terminal so it inherits the PATH. Alternatively, use an absolute path to npx in the command field. On macOS, GUI apps sometimes don’t inherit shell PATH; launching from terminal usually resolves this.
Handling port conflicts and how to change the MCP server port
If the MCP server fails due to port already in use, check the startup logs to see the attempted port. To change it, set an environment variable like PORT or pass a CLI flag if the MCP server supports it. Update the mcpServers env or args accordingly and restart.
Interpreting server logs and where to find them in Cursor sessions
Cursor surfaces process stdout and stderr in its server or process panel. Open that panel to see startup messages, request logs, and errors. Use these logs to identify authentication failures, misconfigured payloads, or runtime exceptions.
If agent creation fails: validating request payloads, token errors, and API responses
If create-agent or create-call requests fail, inspect the request payload for required fields and correct structure. Check server logs for 401 or 403 responses that indicate token issues. Verify the VAPI_TOKEN has the right scopes and isn’t expired, and retry after correction.
Conclusion
You now have a complete overview of how to install, configure, run, and debug the Vapi MCP server from within the Cursor IDE. You learned the required platform and Node prerequisites, how to place and format the mcpServers block for Unix and Windows, how to manage tokens securely, and how to create calls and agents from within Cursor. Follow the tips for persistent installs, safe token handling, and quick iteration to keep your workflow smooth. Try the demo steps, iterate on agent logic inside Cursor, and enjoy the fast feedback loop that running Vapi MCP in your editor provides. Next steps: run a small agent demo, rotate tokens safely in your environment, and explore advanced agent capabilities once you’re comfortable with the basic flow. Have fun building!
If you want to implement Chat and Voice Agents into your business to reduce missed calls, book more appointments, save time, and make more revenue, book a discovery call here: https://brand.eliteaienterprises.com/widget/bookings/elite-ai-30-min-demo-call