WACrew

Blog

Cursor MCP setup: how to connect tools to your editor with mcp.json

How to configure MCP servers in Cursor with mcp.json, per project or global. Examples with npx, remote servers, environment variables, tool approval and logs.

Updated 4 min read
On this page
  1. Two ways to install a server
  2. Where mcp.json lives
  3. A local server started by a command
  4. A remote server by URL
  5. Variables without leaking secrets
  6. A real example: WhatsApp inside Cursor
  7. Using the tools in chat
  8. When something doesn't work
  9. Cursor or Claude Code?
  10. Summary

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:

FileApplies to
.cursor/mcp.json at the project rootThat project only
~/.cursor/mcp.json in your home folderEvery 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:

  1. Open the Output panel (Cmd+Shift+U on a Mac).
  2. Pick MCP Logs from the list.
  3. Look for connection errors, authentication errors or the server crashing.

Common causes:

  • npx not found. Apps launched from the Dock or the Start menu don't always see the same PATH as your terminal. Put the full path to npx in command (which npx tells 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 use envFile for 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.