How to Set Up MCP Servers in Cursor — Complete Guide

Cursor has built-in MCP support, which means your AI assistant can interact directly with databases, APIs, browsers, and other tools while you code. You configure a server once in a JSON file and Cursor handles the rest -- no extensions, no plugins, no middleware.

TL;DR: Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global config) with your server definitions. Reload Cursor after saving. The format is nearly identical to Claude Desktop's config.

graph TD
    A[Create .cursor/mcp.json] --> B[Add server config]
    B --> C[Reload Cursor]
    C --> D{Server connected?}
    D -->|Yes| E[Ask AI to use a tool]
    D -->|No| F[Check troubleshooting below]

Where Cursor Stores Its MCP Config

Project-level config (recommended)

your-project/
  .cursor/
    mcp.json

Create a .cursor directory in your project root and put mcp.json inside it. Commit it to version control (minus secrets) to share the setup across your team.

Global config

On macOS: ~/.cursor/mcp.json On Windows: %USERPROFILE%\.cursor\mcp.json

The global config is useful for servers you always want available, like GitHub MCP. Project-level configs take priority when both exist.

The Config Format

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"
      }
    }
  }
}

Field breakdown

• mcpServers: Top-level object containing all server definitions. Each key is a name you choose.
• command: The executable ("npx", "uvx", "python", "node", "docker").
• args: Command-line arguments. The -y flag auto-confirms the npx install prompt.
• env: Environment variables (API keys, tokens). Never commit real secrets to version control.

Adding Multiple Servers

Supabase MCP | npm | Tools: 25 | ~12,875 tokens

GitHub MCP | npm | Tools: 20 | ~10,300 tokens

Playwright MCP | npm | Tools: 20 | ~10,300 tokens

{
  "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", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    },
    "playwright-mcp": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

Things to keep in mind with multiple servers:

• Token budget: Each server's tool definitions consume context tokens. Stick to servers you actively need. See how to cut MCP token costs.
• Startup time: More servers means slightly longer initialization on reload.
• Naming conflicts: If two servers expose identically-named tools, behavior is unpredictable.

HTTP and SSE Transport Servers

For remote MCP servers, use the url field instead of command/args:

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

Cursor also supports Streamable HTTP transport and determines the type automatically. Note: Windsurf uses serverUrl instead of url -- if you're migrating configs between editors, watch for this difference.

Step-by-Step Setup

1. Create the config directory and file

mkdir -p .cursor
touch .cursor/mcp.json

2. Add your server configuration

Start with a single server to verify the setup works:

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

3. Reload Cursor

Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux) > "Reload Window"

4. Verify the connection

Open Cursor's MCP settings panel. Your server should show a green status. Test it: "List all tables in my Supabase project." If the agent calls Supabase MCP tools and returns results, everything is working.

Troubleshooting Common Issues

"Server failed to start"

• Node.js is installed and npx is in your PATH
• Package name in args is spelled correctly
• You have network access (npx downloads packages on first run)

Test manually: npx -y @supabase/mcp-server-supabase

Environment variables not working

• Variable names are case-sensitive
• Copy token fresh from the service dashboard -- trailing spaces cause silent failures
• No trailing whitespace or newline characters in the value

Server starts but tools are not visible

• Check the server's docs for required config before tools are exposed
• Confirm you reloaded Cursor after editing the config
• Some tools only appear in agent mode, not basic chat

JSON syntax errors

• No trailing commas: {"a": 1,} is invalid
• Double quotes only: {'a': 1} is invalid
• Run through a JSON validator if unsure

For more solutions, see the MCP troubleshooting guide and how to fix connection errors.

Managing Secrets Safely

• Placeholder values: Commit with "YOUR_TOKEN_HERE" and document which tokens developers need
• .gitignore: Add .cursor/mcp.json if it contains only secrets
• Environment variable references: Check current Cursor version for support -- the feature set evolves quickly

Next Steps

• Start with one or two servers and add more as you identify workflow gaps. Supabase for database, GitHub for PR management, and Playwright for E2E testing is a solid starting trio.
• Keep servers updated: npx -y @package/name always fetches the latest version.
• Monitor token usage: if responses get cut off, you may have too many MCP servers active.

The same servers work in Claude Code, Continue.dev, and Windsurf -- only the config format and file path change. Browse pre-built stacks to find the right combination for your role.