How to Set Up MCP Servers in Cursor — Complete Guide

Cursor ships with built-in support for the Model Context Protocol (MCP), which means your AI assistant can interact directly with databases, APIs, browsers, and other external tools while you code. Instead of copying data back and forth, you configure an MCP server once and Cursor handles the rest.

This guide walks through the entire setup process: where the config file lives, what the format looks like, how to add multiple servers, and what to do when things break.

What Are MCP Servers?

MCP (Model Context Protocol) is an open standard created by Anthropic that lets AI models talk to external tools and services through a structured interface. An MCP server is a lightweight process that exposes a set of "tools" — functions the AI can call to perform actions like querying a database, reading files, running browser tests, or creating GitHub issues.

When you connect an MCP server to Cursor, the AI agent gains the ability to use those tools during your coding sessions. You ask it to "check the Supabase logs" or "run the Playwright tests," and it actually does it — no manual switching required.

Where Cursor Stores Its MCP Config

Cursor reads MCP server configurations from a file called mcp.json. You have two options for where to place it:

Project-level config (recommended)

your-project/
  .cursor/
    mcp.json

Create a .cursor directory in your project root and put mcp.json inside it. This approach is ideal because you can commit the file to version control (minus any secrets) and share the same MCP setup across your team.

Global config

Cursor also supports a global MCP config that applies to all projects. On macOS, this lives at:

~/.cursor/mcp.json

On Windows:

%USERPROFILE%\.cursor\mcp.json

The global config is useful for servers you always want available, like a GitHub MCP server. Project-level configs take priority when both exist, and the two are merged at runtime.

The Config Format

The mcp.json file uses a straightforward JSON structure. Here is a minimal example with a single server:

{
  "mcpServers": {
    "supabase-mcp": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "YOUR_SUPABASE_ACCESS_TOKEN"
      }
    }
  }
}

Let's break down each field.

mcpServers

The top-level object that contains all your server definitions. Each key inside it is the name you give to a particular server. The name is arbitrary — pick something descriptive that you will recognize in Cursor's UI.

command

The executable that starts the MCP server process. Common values are:

• "npx" — for servers published as npm packages
• "uvx" or "python" — for Python-based servers
• "node" — for running a local JavaScript file directly
• "docker" — for containerized servers

args

An array of command-line arguments passed to the command. For npm-based servers, you typically use ["-y", "@package/name"] where the -y flag tells npx to auto-confirm the install prompt. Some servers accept additional arguments for configuration:

"args": ["-y", "@anthropic/mcp-server-github", "--repo", "my-org/my-repo"]

env

An object of environment variables passed to the server process. This is where API keys, access tokens, and other secrets go. The server process receives these variables in its environment, keeping them out of the command-line arguments (which might show up in process listings).

Important: avoid committing real secrets to version control. Use placeholder values in the committed file and override them locally, or use a .env file alongside a .gitignore entry.

Adding Multiple Servers

Most real setups involve more than one MCP server. Just add more keys under mcpServers:

{
  "mcpServers": {
    "supabase-mcp": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "YOUR_SUPABASE_ACCESS_TOKEN"
      }
    },
    "github-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    },
    "playwright-mcp": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-playwright"]
    }
  }
}

This config gives Cursor access to three tools at once: Supabase for database operations, GitHub for repository management, and Playwright for browser automation. The AI agent sees all available tools and picks the right one based on your request.

A few things to keep in mind when running multiple servers:

• Token budget: each MCP server's tool definitions consume tokens from the context window. Running too many servers at once can eat into the space available for your actual code and conversation. Stick to the servers you actively need for the current project.
• Startup time: servers start as separate processes. More servers means a slightly longer initialization when Cursor boots up or reloads the config.
• Naming conflicts: if two servers expose tools with the same name, behavior can be unpredictable. Check the tool names in each server's documentation before combining them.

HTTP and SSE Transport Servers

Not all MCP servers run as local processes. Some are hosted remotely and communicate over HTTP using Server-Sent Events (SSE) for streaming responses. For these servers, you use the url field instead of command and args:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

You can also pass headers for authentication when connecting to remote servers:

{
  "mcpServers": {
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Remote servers are convenient when the service is managed by a third party or when you want to avoid installing dependencies locally. The trade-off is network latency — local stdio servers respond faster since everything runs on your machine.

Cursor also supports the newer Streamable HTTP transport, which uses standard HTTP POST requests instead of SSE. The config format is the same url field. Cursor determines the transport type automatically based on the server's response.

Step-by-Step Setup Walkthrough

Here is the full process from scratch:

1. Create the config directory

Open a terminal in your project root:

mkdir -p .cursor

2. Create the config file

touch .cursor/mcp.json

3. Add your server configuration

Open .cursor/mcp.json in any editor and paste your config. Starting with a single server is a good idea:

{
  "mcpServers": {
    "supabase-mcp": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_your_token_here"
      }
    }
  }
}

4. Reload Cursor

After saving the file, reload Cursor to pick up the new configuration. You can do this by:

• Running the "Reload Window" command from the command palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
• Or simply closing and reopening the project

5. Verify the server is connected

Open Cursor's MCP settings panel (look for the MCP section in Settings, or check the status indicator in the bottom bar). You should see your server listed with a green status indicating it connected successfully.

You can also test it by asking the AI agent to use a tool from that server. For the Supabase example, try: "List all tables in my Supabase project." If the agent calls the Supabase MCP tools and returns results, everything is working.

Troubleshooting Common Issues

"Server failed to start"

This usually means the command is not found or the package failed to install. Check that:

• Node.js is installed and npx is available in your PATH
• The package name in args is spelled correctly
• You have network access to download the package (npx fetches it on first run)

Try running the command manually in your terminal to see the actual error:

npx -y @supabase/mcp-server-supabase

"Connection refused" or timeout errors

For remote (HTTP/SSE) servers, verify:

• The URL is correct and the server is actually running
• Any required authentication headers are included
• Your firewall or VPN is not blocking the connection

Environment variables not working

If a server starts but fails to authenticate:

• Double-check that your token or API key is correct — copy it fresh from the service's dashboard
• Make sure the variable name matches exactly what the server expects (case-sensitive)
• Confirm there are no trailing spaces or newline characters in the value

Server starts but tools are not visible

Some servers require specific arguments or environment variables before they expose their tools. Read the server's documentation for required configuration. Also confirm you reloaded Cursor after editing the config.

JSON syntax errors

The config file must be valid JSON. Common mistakes include:

• Trailing commas after the last item in an object or array
• Missing quotes around keys or string values
• Using single quotes instead of double quotes

Run your config through a JSON validator if you are unsure. Most code editors will highlight syntax errors automatically.

Multiple servers conflicting

If Cursor behaves strangely after adding a new server, try disabling it temporarily by removing its entry from mcp.json and reloading. This helps isolate whether the issue is with that specific server or a conflict between servers.

Managing Secrets Safely

Hardcoding API keys in mcp.json works for personal projects but becomes a problem once you share the repo. A few strategies:

Use placeholder values and document them: commit the config with "YOUR_TOKEN_HERE" values and add a note in your README about which tokens are needed.

Use environment variable references: some MCP clients support referencing system environment variables in the config. Check whether Cursor supports this in its current version, as the feature set evolves quickly.

Add to .gitignore: if your config contains only secrets and no shareable settings, add .cursor/mcp.json to .gitignore. Team members can maintain their own local copy.

Generate Configs for Your Stack

Putting together the right combination of MCP servers for your workflow — and getting the config format right for your specific client — takes some trial and error. If you work across multiple projects or use different AI coding tools, the config format changes between each one (Cursor uses mcp.json, Claude Desktop uses claude_desktop_config.json, VS Code uses settings.json, and so on).

stackmcp.dev lets you pick a pre-built stack of MCP servers tailored to your role (frontend developer, fullstack engineer, data scientist, etc.), select your client, and generate a ready-to-use config file. It handles the format differences and lists the environment variables you need to fill in, so you can go from zero to a working MCP setup in a couple of minutes instead of piecing together documentation from multiple repos.

Next Steps

Once your MCP servers are running in Cursor, a few things worth exploring:

• Try different server combinations: start with one or two servers and add more as you identify gaps in your workflow. A Supabase server for database work, a GitHub server for PR management, and a Playwright server for end-to-end testing is a solid starting point for web development.
• Check server documentation for advanced options: many servers accept additional arguments that unlock features beyond the defaults. The Supabase MCP server, for example, supports project-specific scoping and migration management.
• Keep servers updated: MCP servers are actively developed. Running npx -y @package/name always fetches the latest version, but if you pin versions (removing the -y flag and specifying a version), remember to update periodically.
• Monitor token usage: if you notice Cursor's responses getting cut off or losing context, you might be running too many MCP servers at once. Each server's tool definitions take up space in the context window. Trim your active servers to the ones you actually need for the task at hand.

MCP support in Cursor is still evolving, with new features and servers appearing regularly. The fundamentals covered here — the config file location, the JSON format, stdio vs. HTTP transports — are stable and will serve you well regardless of what gets added next.