How to Set Up MCP Servers in Claude Code, Claude Desktop, and Cursor

MCP servers extend what AI coding tools can do — giving them access to files, databases, GitHub, and more. The setup process differs slightly between tools, and the documentation can be scattered.

This guide covers everything in one place: how to configure MCP servers in Claude Desktop, Claude Code, Cursor, Windsurf, and ChatGPT Desktop, plus the most common issues you'll run into.

---

What You Need

• Node.js 18 or higher (check: node --version)
• The AI tool you're configuring (Claude Desktop, Claude Code, Cursor, etc.)
• About 10 minutes

Most MCP servers are distributed as npm packages and run with npx. You don't need to install them globally — npx handles it automatically.

---

Claude Desktop Setup

Claude Desktop uses a JSON config file that lists all your MCP servers.

Step 1: Find the config file

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

If the file doesn't exist, create it.

Step 2: Add your servers

Here's a complete example with three servers — filesystem access, GitHub, and Planu for spec management:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_your_token_here"
      }
    },
    "planu": {
      "command": "npx",
      "args": ["--prefer-online", "-y", "@planu/cli@latest"]
    }
  }
}

Step 3: Restart Claude Desktop

After saving the config file, quit Claude Desktop completely and reopen it. You'll see a hammer icon in the bottom of the chat interface when MCP servers are active.

Verifying the connection

Type "list your available tools" in a new Claude Desktop conversation. Claude will describe what tools are available from your MCP servers.

---

Claude Code Setup (Recommended)

Claude Code has the simplest MCP setup — a single command.

Add a server:

claude mcp add planu -- npx -y @planu/cli@latest

General syntax:

claude mcp add <name> -- <command> [args...]

List configured servers:

claude mcp list

Remove a server:

claude mcp remove <name>

Add a server with environment variables:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_your_token -- npx -y @modelcontextprotocol/server-github

Claude Code stores MCP config in ~/.claude/config.json. The claude mcp commands are the recommended way to edit this — don't edit the JSON directly unless you know what you're doing.

Project-level MCP config

Claude Code also supports project-level MCP servers via a .mcp.json file in your project root. This is useful for servers that are specific to one project (like a database connection):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Commit this file to your repo so the whole team gets the same server configuration.

---

Cursor Setup

Cursor manages MCP servers through its settings UI or a config file.

Option A: Through Cursor Settings

1. Open Cursor → Settings → Features → MCP
2. Click "Add New MCP Server"
3. Enter the server name and command
4. Click Save and restart Cursor

Option B: Config file

Cursor reads from ~/.cursor/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/project/path"]
    },
    "planu": {
      "command": "npx",
      "args": ["--prefer-online", "-y", "@planu/cli@latest"]
    }
  }
}

After saving, restart Cursor. The MCP indicator in the status bar shows how many servers are connected.

Cursor Agent mode required

MCP tools are only available when using Cursor's Agent mode (previously called Composer). They don't work in the regular chat or inline edit modes.

---

Windsurf Setup

Windsurf (by Codeium) uses a similar JSON config approach.

Config file location: ~/.windsurf/mcp_config.json

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_api_key"
      }
    },
    "planu": {
      "command": "npx",
      "args": ["--prefer-online", "-y", "@planu/cli@latest"]
    }
  }
}

Restart Windsurf after saving. MCP servers are accessible in the Cascade agent panel.

---

ChatGPT Desktop Setup

ChatGPT Desktop (OpenAI) added MCP support in early 2026. The config is managed through the app's settings.

Config file: ~/Library/Application Support/ChatGPT/mcp_config.json (macOS)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/project/path"]
    }
  }
}

Go to ChatGPT Desktop → Settings → Advanced → MCP Servers to manage configurations through the UI.

---

Troubleshooting Common Issues

"Server failed to start" or no tools appear

1. Check that Node.js is installed: node --version (needs 18+)
2. Try running the server manually to see the error:

   npx -y @planu/cli@latest

3. Check that npx is in your PATH. If you installed Node via nvm, make sure the shell your AI tool launches uses the same PATH.

Tools appear but don't work

• Environment variables may not be set. In Claude Desktop, they must be in the env block inside mcpServers, not as system env vars.
• File paths must be absolute. ~/projects does not work — use /workspace/projects.

npx is slow on first run

With a global install, Planu starts in <50ms — no cold start, no download on every run. Install once and every subsequent start is instant:

npm install -g @planu/cli

Permissions errors on macOS

Some MCP servers require filesystem permissions. Go to System Settings → Privacy & Security → Files and Folders, and make sure your AI tool (Claude Desktop, Cursor, etc.) has access to the directories your MCP server needs.

---

Quick Reference

Tool	Config file	Notes
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	Restart app after changes
Claude Code	~/.claude/config.json (use claude mcp add)	Supports project-level .mcp.json
Cursor	~/.cursor/mcp.json	Agent mode required
Windsurf	~/.windsurf/mcp_config.json	Cascade agent panel
ChatGPT Desktop	~/Library/Application Support/ChatGPT/mcp_config.json	macOS path

---

Next Steps

Now that your MCP servers are running:

• 10 Best MCP Servers for Developers in 2026 — which servers are worth installing
• Getting Started with Planu — set up spec management for your AI workflow
• SDD Workflow Guide — how to structure work across sessions