What an MCP server actually does

By default, Claude, Cursor, and Windsurf can only work with text you paste into the chat. An MCP server punches a hole in that limitation — it lets the AI call functions on your behalf, reading from and writing to systems outside the conversation window.

A filesystem MCP server lets the AI read and write local files. A GitHub MCP server lets it open PRs and search your repos. A database MCP server lets it run SQL queries against your live data. Each server exposes a set of tools — named functions the AI can call when it decides they're relevant. You configure which servers are active; the AI decides when and how to use them.

All four major AI clients (Claude Desktop, Cursor, Windsurf, VS Code Copilot) support MCP. The protocol is standardized, but the config file location and format differ slightly across clients. This guide covers all of them.

Prerequisites

Before adding your first MCP server, make sure you have:

• Node.js 18+ or Python 3.10+ — most MCP servers are distributed as npm or pip packages. Run node --version or python3 --version to check. Install from nodejs.org or python.org if needed.
• Your AI client installed and signed in — Claude Desktop, Cursor, Windsurf, or VS Code with the GitHub Copilot extension.
• A text editor — you'll be editing JSON config files. Any editor works.

Most servers install with a single npx or uvx command, no global install required. The config file tells your AI client how to launch the server process — typically a command and a list of arguments.

Claude Desktop

Claude Desktop is the simplest client to configure. MCP servers are defined in a single JSON file. The file may not exist yet — you'll create it the first time.

Step 1: Find your config file

The config file lives at a fixed OS path:

On macOS, you can open it directly from Terminal:

open -a "TextEdit" ~/Library/Application\ Support/Claude/claude_desktop_config.json

Or open the directory in Finder: open ~/Library/Application\ Support/Claude/

Step 2: Add the mcpServers block

The config file is a JSON object with an mcpServers key. Each entry is a named server with a command, args, and optional env object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Desktop"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

The key under mcpServers (e.g., "filesystem") is the name you'll see in Claude's interface. The command is the executable to run. The args array contains arguments passed to that command. The env object sets environment variables — use this for API keys and secrets instead of hardcoding them in args.

Step 3: Restart Claude Desktop

Config changes are not picked up while Claude Desktop is running. Quit the app completely (not just close the window — on macOS, right-click the Dock icon and choose Quit) and relaunch it.

Step 4: Verify the server is active

After restarting, open a new conversation. You should see a hammer icon or a tools indicator in the input area. Click it to see which MCP servers are connected and what tools they expose. If you don't see it, open the developer console (Help → Developer Tools) and look for error messages related to MCP server startup.

Cursor

Cursor supports MCP servers in both Composer (Agent mode) and Chat. You can configure servers globally via a JSON file or per-project via a project-level file.

Method 1: Global config file

The global MCP config lives at:

The format is identical to Claude Desktop — an mcpServers object with named server entries:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    }
  }
}

Method 2: Cursor Settings UI

Open Cursor Settings (Cmd+, on macOS, Ctrl+, on Windows), navigate to Features → MCP Servers, and click Add new MCP server. This writes to the same ~/.cursor/mcp.json file — both methods modify the same config.

Project-level config

For project-specific servers, create a .cursor/mcp.json file in your project root. Cursor merges global and project configs, with project-level entries taking precedence on name conflicts.

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "./data/project.db"
      ]
    }
  }
}

Verify in Cursor

Reload the window (Cmd+Shift+P → Developer: Reload Window). In Composer (Agent mode), you should see MCP tool calls appearing when the agent decides to use them. In the settings UI, connected servers show a green dot next to their name.

Windsurf

Windsurf uses the Cascade panel for AI interactions, and MCP servers integrate directly into it. Configuration is similar to Cursor.

Config file location

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Note the fetch server example using uvx — Windsurf works with both npm-based servers (using npx) and Python-based servers (using uvx, the uv package runner). Make sure uvx is installed if you use Python servers: pip install uv.

Adding servers via the Cascade panel

Windsurf also offers a UI path. Open the Cascade panel, click the plug icon in the top-right, and select Configure MCP. This opens the config file in the editor. After saving, click Refresh in the Cascade panel — no full restart required for config changes.

Verify in Windsurf

After adding servers, look for the MCP tools indicator in the Cascade panel footer. Cascade will automatically call available tools when relevant — you'll see tool call output inline in the conversation.

VS Code with Copilot

VS Code supports MCP through the GitHub Copilot extension in Agent mode. You need VS Code 1.99+ and the Copilot extension.

Workspace-level config

Create a .vscode/mcp.json file in your project root. This is committed with the project and shared with your team:

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

VS Code's format uses "servers" (not "mcpServers") and requires an explicit "type": "stdio" field. The ${workspaceFolder} and ${env:VARIABLE_NAME} placeholders expand at runtime.

User-level config

For servers you want available in all projects, add them to your VS Code user settings (Cmd+Shift+P → Preferences: Open User Settings (JSON)):

"github.copilot.chat.mcp.enabled": true,
"mcp": {
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]
    }
  }
}

Enable Agent mode

MCP tools are only available in Agent mode — not in Ask or Edit modes. Switch to Agent mode using the dropdown in the Copilot Chat panel. You'll see a tools indicator showing connected MCP servers once Agent mode is active.

Common errors and fixes

spawn ENOENT: command not found

The most common error. It means the command in your config isn't on the PATH when the AI client launches. Fix it by using the full absolute path to the command:

which npx       # → /usr/local/bin/npx
which node      # → /usr/local/bin/node
which uvx       # → /Users/yourname/.local/bin/uvx

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname"]
    }
  }
}

This is especially common on macOS when using nvm, asdf, or Homebrew-managed Node installations, since GUI apps launched from the Dock don't inherit your shell's PATH.

Server not appearing after config change

Claude Desktop and Cursor require a full restart after config changes — closing and reopening a window is not enough. On macOS, right-click the Dock icon and choose Quit, then relaunch. In Windsurf, use the Cascade panel's Refresh button instead.

JSON syntax error: invalid config

Standard JSON does not allow trailing commas. This is the most common syntax mistake. A trailing comma after the last item in an object or array will silently fail on some clients:

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": [] },   ← remove this comma
  }
}

Validate your JSON at jsonlint.com or run cat your-config.json | python3 -m json.tool before restarting.

Permission denied on file paths

On macOS 13+, filesystem access is governed by TCC (Transparency, Consent, Control). If a server tries to read a directory your AI client hasn't been granted permission for, it will fail silently or return an empty result. Fix it via System Settings → Privacy & Security → Full Disk Access, and add your AI client app to the list.

Server keeps disconnecting

Intermittent disconnects usually mean the server process is crashing. Check the developer console in Claude Desktop (Help → Developer Tools → Console) for server crash logs. Common causes: missing environment variables (API key not set), wrong package name (typo in args), or a Node.js version incompatibility. Run the server command manually in your terminal to see the raw error output:

npx -y @modelcontextprotocol/server-github
# Look for startup errors before the process exits

stdio vs HTTP transport mismatch

Most published MCP servers use stdio transport — they run as a subprocess of your AI client. Some servers offer HTTP+SSE transport for remote access. If you're connecting to a remote MCP server, use "url" instead of "command" in your config:

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

5 servers to install first

With 25,000+ MCP servers indexed on AgentRank, starting from scratch is overwhelming. These five are the highest-signal entry points — well-maintained, genuinely useful, and straightforward to configure. Scores from the AgentRank index, March 2026.

The official reference servers from Anthropic (@modelcontextprotocol/server-filesystem, @modelcontextprotocol/server-github, @modelcontextprotocol/server-sqlite, and others) are bundled in the Python SDK repo and published separately on npm. They're the safest starting point — actively maintained, well-documented, and designed exactly for this use case.

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

Finding more servers

The AgentRank leaderboard ranks every MCP server by a composite quality signal: stars, freshness, issue health, contributor count, and inbound dependents. It's updated nightly from 25,000+ GitHub repositories.

Browse by category to find servers relevant to your stack: Database · DevOps · Code Generation · Productivity · Security · AI/ML · Browser Automation