How to Add MCP Server to Cursor, VS Code, Claude Code, Cline

You copy a five-line JSON snippet from a README, paste it into the wrong file in Cursor, restart the editor, and no tools appear. You find the right file, paste again, and nothing loads because that client wants servers, not mcpServers. None of this is MCP being hard: the clients disagree on paths, key names, transport fields, and who else a config reaches.

This page installs one server in the five clients people ask about most: Cursor, VS Code, Claude Code, Windsurf, Cline. Claude Desktop is a different file, covered in how to add an MCP server to Claude — that post is Claude Desktop only, so if you are on Claude Code, stay here.

MCP config file location by client

Everything you have to get right fits in one table: the MCP config file location per client, the top-level key it expects, who else the file reaches, and how it handles secrets.

Client	Config path	Top-level key	Scope model	Secrets
Cursor	macOS/Linux ~/.cursor/mcp.json, Windows %USERPROFILE%\.cursor\mcp.json; project .cursor/mcp.json	mcpServers	User + project (git)	Literal env
VS Code	.vscode/mcp.json; user file via the MCP: Open User Configuration command, or code --add-mcp	servers (+ inputs)	Workspace + user	${input:...} prompt
Claude Code	.mcp.json at repo root, plus CLI scopes	mcpServers	local / project / user	${VAR}, ${VAR:-default}
Windsurf	macOS/Linux ~/.codeium/windsurf/mcp_config.json, Windows %USERPROFILE%\.codeium\windsurf\mcp_config.json	mcpServers	User-level	Literal env
Cline	globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json under macOS ~/Library/Application Support/Code/User/, Windows %APPDATA%\Code\User\, Linux ~/.config/Code/User/	mcpServers	Per install (global)	Literal env

Verified as of July 2026; these client schemas change often, so check your version's docs before concluding a server is broken.

Two rules fall out of it. Cursor, Claude Code, Windsurf and Cline all speak mcpServers, so snippets port between them with small edits; VS Code does not, so treat it as a separate format. And only Cursor and Claude Code have a project scope that lands in git, which is where the sharp edge is.

How to add MCP server to Cursor: global versus project scope

Cursor reads ~/.cursor/mcp.json for servers you want everywhere and .cursor/mcp.json in a repo for that project, same schema in both. Keep server names distinct between the two files — behavior when the same name appears in both is not documented, so do not rely on one overriding the other.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code"]
    },
    "example-remote": { "url": "https://mcp.example.com/mcp" }
  }
}

Every example here uses npx -y, which resolves whatever version is published at launch. Convenient, and also the mechanism behind MCP rug pulls, so pin a version for anything you depend on.

Verification is not "the editor didn't error": open Settings, find the MCP section, and confirm the server is connected and lists tool names. Zero tools on a connected server is the common silent failure, usually a wrong argument.

VS Code: .vscode/mcp.json, agent mode, and typed transports

VS Code uses a different shape on purpose: servers live under servers, each declares an explicit type, and anything you do not want written into the file goes through an inputs prompt.

{
  "inputs": [
    { "id": "api-token", "type": "promptString", "password": true }
  ],
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    },
    "example-remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

Two things trip people up. MCP tools surface in agent mode in Chat; in ask mode you will typically see none, so check the mode before blaming the config. And VS Code puts start, stop and restart controls above each server block: use those instead of reloading the window, read the output channel when a server refuses to start, and confirm the tools loaded from that status line plus the tools picker in Chat. For a server you want in every workspace, run MCP: Open User Configuration from the command palette, or use code --add-mcp '{"name":"fs","command":"npx","args":["-y","pkg"]}'.

Claude Code: claude mcp add and what project scope means

Claude Code's CLI is the one worth reaching for here, because it makes scope explicit instead of an accident of which file you opened. Pass --scope deliberately: claude mcp add defaults to local scope when no flag is given.

# user scope: available in every project on this machine
claude mcp add --scope user filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/code

# project scope: writes .mcp.json at the repo root, shared via git
claude mcp add --scope project docs -- npx -y example-docs-server

# remote server over streamable HTTP
claude mcp add --transport http example-remote https://mcp.example.com/mcp

claude mcp list

The scopes are local (this project, this machine, not shared), project (the committed .mcp.json), and user (all your projects). Hand-editing .mcp.json gives the same result in the familiar mcpServers shape, and claude mcp list reports what actually connected.

Project scope is the part worth internalizing. A committed .mcp.json is an instruction to every teammate's agent. Claude Code asks for approval before using project-scoped servers, the right default, but that prompt is all that stands between a merged pull request and a new tool surface running on a colleague's laptop with their credentials. Review a config diff the way you review a new dependency.

Windsurf and Cline: same idea, different addresses

Windsurf uses one user-level file at ~/.codeium/windsurf/mcp_config.json in the mcpServers shape, reachable from the Cascade panel's MCP settings, which holds the refresh control and the tool list to check after saving. Its remote entries have historically used serverUrl rather than url, so if a URL server never connects, check that key against your version's docs first.

Cline stores servers in cline_mcp_settings.json inside the extension's global storage, and the path follows the host editor, so open it from the MCP Servers panel rather than typing it by hand. That panel is also where you confirm the result: each server shows a connection indicator and the tools it exposes. Cline's config exposes two fields worth knowing: disabled, which keeps an entry without loading it, and autoApprove, tools that run without asking you first.

autoApprove is fine on a read-only tool you call fifty times an hour and dangerous on anything that writes, sends, or fetches a URL. Auto-approving a tool that pulls in arbitrary web content supplies the first leg of the lethal trifecta, with no human on the intermediate step.

Remote and HTTP servers across clients

A local stdio server is a process your client spawns; a remote server is a URL it connects to, and the wiring differs per client.

• Cursor, Windsurf, Cline: a URL key in the server object (Windsurf has historically used serverUrl — check your version's docs). Where the client supports OAuth, authentication typically runs as a browser flow on first connect; support and UX vary by client and version.
• VS Code: "type": "http" or "sse" alongside url; the editor holds the tokens.
• Claude Code: --transport http or sse, and the /mcp command shows server status and handles authentication.

When you scan a remote endpoint at /scan, be honest about what you learned. A live scan reads the surface the server advertises right now and is reported as coverage: live. It is not comparable to a package scan that reads source: there is no source, and the surface can change between requests without a version number moving.

Environment variables and secrets

Two clients give you a real answer. VS Code has inputs, which prompts and keeps the value out of the file. Claude Code expands ${VAR} and ${VAR:-default} from your environment, so a config can reference ${GITHUB_TOKEN} and stay committable. Cursor, Windsurf and Cline expect literal values in env.

That is how the failure nobody plans for happens: a project-scoped .cursor/mcp.json with a real API key, committed, reviewed by people who read it as configuration rather than a credential, and now in the history of every clone. Never put a literal secret in a git-tracked file: use the variable form where the client supports it, keep secret-bearing entries in the user-scope file where it does not, and add the config path to your pre-commit secret scan. If CI gates dependencies, gate MCP configs too, since the free HTTP API and the GitHub Action grade a target and can fail the build like a vulnerable dependency.

Setup mistakes that look like client bugs

• Trailing commas. Strict JSON forbids them, and a malformed file can fail to load with no visible error, so validate the JSON first. (VS Code's mcp.json is parsed as JSONC and does accept comments and trailing commas.)
• PATH not inherited. Depending on the client and how it was launched, the editor may not see the PATH your shell exports from .zshrc, so npx, uvx, or a version-manager shim goes missing. Use an absolute path when a server runs in the terminal but not the editor.
• Wrong scope. Editing the user-level file while a project file defines the same server, or using Claude Code's local scope and expecting a teammate to get it.
• Wrong key name. mcpServers pasted into VS Code, which wants servers. The file parses, so no error, just no servers.
• Relative paths. An argument like ./data resolves against the client's working directory, not your project. Use absolute paths or ${workspaceFolder}.

How to add MCP server to Cursor and check it before you restart

Every step above ends with "restart and see." Do one thing first: paste the finished config, the whole JSON object with every server in it, into /scan, which grades each entry A to F with no model anywhere in the scoring, so identical input returns an identical grade and every finding cites its evidence. Live remote endpoints are the exception to that repeatability, since their advertised surface can move between requests; for the walkthrough, see how to scan an MCP server.

Read the grade as your exposure, not the author's reputation: a server that reads your whole home directory and can reach the network is high blast radius whoever wrote it. Still choosing what to install? Start from the registry, tens of thousands of pre-scanned npm, PyPI and remote servers with the overwhelming majority graded A, and pick one that already carries a grade before the tools go live in your editor.

npx mcptrustchecker