Cursor ships with an agent that reads your code, edits files and runs commands. With MCP, that agent can also talk to systems outside the editor: your database, your error tracker, internal docs or your clients' WhatsApp chats. Instead of pasting context into the chat every time, you connect the source once.
This guide shows how to set up MCP servers in Cursor, based on the official documentation. If the protocol itself is new to you, start with what is MCP.
Two ways to install a server
From the marketplace. The Customize screen in the sidebar lists official plugins you can add in one click. For community servers, cursor.directory collects options with an "Add to Cursor" button.
With an mcp.json file. For any server that is not in the marketplace, or when you want the configuration versioned with the project. That is the path this guide covers.
Where mcp.json lives
Cursor reads configuration from two places:
| File | Applies to |
|---|---|
.cursor/mcp.json at the project root | That project only |
~/.cursor/mcp.json in your home folder | Every project |
The rule of thumb is the same as in Claude Code. A tool that belongs to one repository goes in the project file. A tool you use everywhere goes in the global file. Personal credentials never go into a file you commit.
A local server started by a command
The most common setup is a server Cursor starts with npx:
{
"mcpServers": {
"server-name": {
"command": "npx",
"args": ["-y", "package-name"],
"env": {
"API_KEY": "value"
}
}
}
}
This uses the stdio transport: Cursor talks to the process over standard input and output. It works the same way with Python ("command": "python") or any binary.
Stdio servers also accept an envFile field that loads variables from a file, for example "${workspaceFolder}/.env".
A remote server by URL
For servers that run in the cloud, replace the command with a URL:
{
"mcpServers": {
"my-api": {
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:MY_TOKEN}"
}
}
}
}
Cursor supports the SSE and Streamable HTTP transports for remote servers, plus OAuth sign-in when the server offers it.
Variables without leaking secrets
mcp.json supports interpolation in command, args, env, url and headers. The two you will use most:
${env:NAME}reads an environment variable from your system;${workspaceFolder}points to the project root.
That way the project file can go into Git without carrying any key. Each person sets the token in their own shell or profile.
A real example: WhatsApp inside Cursor
The WACrew MCP server connects Cursor to a self-hosted WhatsApp panel. With the panel running, the configuration looks like this:
{
"mcpServers": {
"wacrew": {
"command": "npx",
"args": ["-y", "wacrew-mcp"],
"env": {
"WAC_CLOUD_URL": "${env:WAC_CLOUD_URL}",
"WAC_CLOUD_USER": "${env:WAC_CLOUD_USER}",
"WAC_CLOUD_PASS": "${env:WAC_CLOUD_PASS}"
}
}
}
}
Now you can ask Cursor's agent something like "read what the client sent in the project group and list the bugs they mentioned" while you work on that same codebase. For replies, the server follows the mode of each chat. In confirm mode, the default, the agent shows the text and waits for your OK before sending.
Using the tools in chat
Once configured, Cursor uses the MCP tools listed under Available Tools when they fit your request. You can also mention a tool by name.
By default, Cursor asks for approval before running each MCP tool, and you can expand the call to see its arguments. Tools follow the same run modes as terminal commands, so you can allow some automatically and keep approval on the ones that act outside your machine, like sending a message.
To turn a server off without deleting its configuration, open Customize and use the toggle next to it. Disabled servers don't load and don't show up in chat.
When something doesn't work
Cursor keeps MCP logs in the output panel:
- Open the Output panel (Cmd+Shift+U on a Mac).
- Pick MCP Logs from the list.
- Look for connection errors, authentication errors or the server crashing.
Common causes:
npxnot found. Apps launched from the Dock or the Start menu don't always see the samePATHas your terminal. Put the full path tonpxincommand(which npxtells you where it is).- An empty variable.
${env:NAME}only reads what exists in the environment Cursor was started from. Launch Cursor from a terminal after exporting the variable, or useenvFilefor stdio servers. - Invalid JSON. One trailing comma breaks the whole file. Validate before saving.
- Too many tools. With many servers on at once, the agent has a harder time picking the right tool. Turn off the ones you don't use in that project.
Cursor or Claude Code?
Both speak MCP, so the same server works in both. The difference is how you work. Cursor is an editor with an agent inside. Claude Code is a terminal agent you use next to any editor. Plenty of people use both: Cursor to edit with the code in view and Claude Code for long tasks in the terminal. For a full walkthrough of an MCP-powered agent, see build a WhatsApp AI agent with MCP.
Summary
In Cursor, MCP servers come from the marketplace or from mcp.json, either per project (.cursor/mcp.json) or global (~/.cursor/mcp.json). Local servers use command and args, remote ones use url. Secrets stay out of the file with ${env:NAME}, and the MCP logs in the Output panel show what went wrong.



