How to Install an MCP Server in Claude, Cursor and VS Code

To install an MCP server, you tell your MCP client how to start it (for a local stdio server) or where to reach it (for a remote HTTP server). Claude Desktop reads claude_desktop_config.json. Claude Code uses the claude mcp add command or a .mcp.json file. Cursor reads .cursor/mcp.json. VS Code now writes new servers to ~/.copilot/mcp-config.json or a workspace .mcp.json, both using mcpServers; its older .vscode/mcp.json uses servers.

Below are the exact paths and formats for each client, checked against their official docs. If you are not sure what an MCP server is yet, read our intro to MCP servers first. Not sure which kind you have? See local vs remote MCP servers.

Client	Config file	Top-level key	Env variable syntax
Claude Desktop	claude_desktop_config.json	mcpServers	values in an env object
Claude Code	claude mcp add, or .mcp.json	mcpServers	${VAR}
Cursor	.cursor/mcp.json, ~/.cursor/mcp.json	mcpServers	${env:NAME}
VS Code (current)	~/.copilot/mcp-config.json, .mcp.json	mcpServers	${NAME}
VS Code (older)	.vscode/mcp.json	servers	${env:NAME}
Devin Desktop (formerly Windsurf)	.devin/mcp_config.json, ~/.config/devin/mcp_config.json	mcpServers	see its docs

Before you install: a 60-second check

An MCP server either runs on your machine with your permissions or receives your data over the network. Before you paste any config:

• Check who publishes the server and that the package links to the repo you expect.
• Read the full command and arguments. Pin a version (package@1.2.3) instead of running whatever is latest.
• Give it the narrowest access that works: one folder, not your home directory, and read-only tokens where you can. Our guide to least privilege for AI agents explains how.
• Read the tool descriptions once it is connected. Hidden instructions there are a real attack, covered in our guide to MCP tool poisoning.

Our full MCP server security guide has the complete vetting checklist. In the AgenticMart MCP server directory, any listing can get a free automated scan; each listing page shows its scan status. A clean scan is not a safety guarantee.

Test the server with MCP Inspector first

Before you wire a server into a client, run it in the official MCP Inspector. You see its tools and can call them by hand, and if it fails you get the error directly instead of a silent missing server. The Inspector needs Node 22.19.0 or newer and runs through npx:

# npm package
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# PyPI package
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git

# Remote HTTP server
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

Add --cli for a scriptable client, for example --cli ... --method tools/list to print the tool list and exit. The Inspector stores OAuth tokens and stdio env values in the OS keychain when one exists, and otherwise in an unencrypted ~/.mcp-inspector/secrets.json, so be careful with real keys on shared or headless machines.

Claude Desktop

Local (stdio) servers

Open Settings > Developer > Edit Config. This opens or creates the config file:

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

Add your server under mcpServers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects/notes"
      ]
    }
  }
}

On Windows, escape backslashes in paths, for example "C:\\Users\\you\\projects\\notes". Use absolute paths. Pass secrets through an env object rather than in args:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server@1.4.2"],
      "env": { "EXAMPLE_API_KEY": "your-key" }
    }
  }
}

Save the file, then fully quit and restart Claude Desktop. The server's tools appear under the connectors menu in the chat input.

If a server does not show up, check the logs. MCP logs live in ~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows and ~/.config/Claude/logs on Linux. mcp.log covers connections, and mcp-server-NAME.log holds each server's stderr. These details come from the official connect local servers guide.

Remote servers

Remote servers are added as custom connectors, not in the JSON file. Go to Settings > Connectors, click Add, choose Add custom connector, paste the server URL (for example https://example.com/mcp) and complete the sign-in. You can then enable or disable individual tools in the connector settings. See the remote servers guide for screenshots.

Claude Code

Claude Code manages servers with the claude mcp command. The full reference is in the Claude Code MCP docs.

Add a local stdio server

Everything after -- is the command that starts the server:

claude mcp add --transport stdio --env AIRTABLE_API_KEY=your-key airtable -- npx -y airtable-mcp-server

Add a remote HTTP server

claude mcp add --transport http notion https://mcp.notion.com/mcp

# With a static header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

SSE is deprecated, so use --transport http. From Claude Code v2.1.265, --transport http tries HTTP first and switches to SSE if the server only accepts SSE; on earlier versions pass --transport sse for SSE-only servers (Claude Code MCP docs).

Choose a scope

Scope	Flag	Where it is stored	Who gets it
Local (default)	--scope local	~/.claude.json, under the project path	You, in this project only
Project	--scope project	.mcp.json in the project root	Everyone who clones the repo
User	--scope user	~/.claude.json	You, in every project

A project-scoped .mcp.json looks like this:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    },
    "database-tools": {
      "command": "npx",
      "args": ["-y", "@example/db-server"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}

Note that a url entry needs a type (http, sse or ws). The ${VAR} syntax reads from your environment, so you can commit the file without committing secrets. Claude Code asks for approval before using project-scoped servers from a repo.

Manage servers

claude mcp list          # all servers and their health
claude mcp get notion    # details for one server
claude mcp remove notion # remove it

Inside a session, run /mcp to check status, sign in to OAuth servers, reconnect or toggle servers.

Cursor

Cursor reads two files, documented in the Cursor MCP docs:

• Project: .cursor/mcp.json in the project root
• Global: ~/.cursor/mcp.json in your home directory

Both use mcpServers:

{
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server@1.4.2"],
      "env": { "API_KEY": "${env:API_KEY}" }
    },
    "remote-tools": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" }
    }
  }
}

Cursor supports stdio, SSE and Streamable HTTP. HTTP+SSE is classed as Deprecated in the 2026-07-28 MCP spec, so prefer a Streamable HTTP URL when the server offers one. Cursor uses ${env:NAME} for environment variables. It asks for approval before running MCP tools by default. You can switch a server off without deleting it from the settings UI.

VS Code

VS Code (with GitHub Copilot) changed its MCP setup in 2026. The VS Code MCP configuration reference now says to use its portable files for new Copilot configurations, not .vscode/mcp.json, and marks the Local harness, which uses the editor's own MCP client, as deprecated and due for removal in February 2027.

Recommended: the portable mcpServers files

File	Scope
~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json)	You, in every workspace ("Copilot Global")
.mcp.json in the workspace root	Everyone who opens the repo; offered when the experimental chat.mcp.workspaceRootConfig.enabled setting is on

Both use the same mcpServers key as Claude and Cursor:

{
  "mcpServers": {
    "local-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/mcp-server@1.4.2"],
      "tools": ["*"]
    },
    "remote-tools": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "tools": ["*"]
    }
  }
}

type is stdio, http (Streamable HTTP, preferred) or sse (legacy). For secrets, reference environment variables with the braced form ${NAME} (or ${NAME:-default} for a non-secret default) and set them in the environment of the host that runs the server. Bare $NAME is treated as literal text, and the inputs prompts from the old format are not supported here.

The easiest route is the Command Palette: MCP: Add Server walks you through an HTTP URL or a stdio command, then asks where to save it (Copilot Global, or the workspace .mcp.json when offered).

Older format: .vscode/mcp.json

Existing projects may still have .vscode/mcp.json or a profile mcp.json. These editor-managed files use servers instead of mcpServers, ${env:NAME} for environment variables, and support an inputs block that prompts for a token and stores it securely:

{
  "inputs": [
    { "type": "promptString", "id": "api-token", "description": "API token", "password": true }
  ],
  "servers": {
    "issueTracker": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

The reference says the Copilot harness does not read these files directly, so plan to move servers to the portable format. Do not copy inputs or ${input:...} into a portable file; they are not supported there.

Devin Desktop (formerly Windsurf)

The Windsurf MCP docs now redirect to Devin Desktop. Its MCP configuration docs list these files, all with a top-level mcpServers key:

• Project (shared): .devin/mcp_config.json
• User: ~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on Windows)
• Local, gitignored: .devin/mcp_config.local.json

A local server takes command, args and env. A remote server takes url, optional headers, and transport set to "http" or "sse".

Python servers with uvx

Many Python MCP servers are published to PyPI and started with uvx, which runs a package in a temporary environment without a separate install step. Put uvx in command and the package name and arguments in args. For example, the git server used in the Inspector docs:

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/Users/you/code/my-repo"]
    }
  }
}

Pin a version the same way you would with npm (mcp-server-git==VERSION), and if a GUI client cannot find uvx, use its full path.

Docker-based servers

Some servers ship as Docker images. The client runs docker run -i --rm IMAGE as the command, and you mount only the folders the server needs. The filesystem server README shows this pattern: command is docker, args start with run, -i and --rm, add one --mount type=bind,src=HOST_PATH,dst=/projects/NAME per folder (append ,ro for read-only), and end with the image mcp/filesystem and /projects. Keep -i, since stdio needs an open stdin, and do not add -t.

Troubleshooting

• Server missing after restart. Validate the JSON. A trailing comma breaks the whole file.
• Command not found. GUI apps may not see your shell's PATH. Use the full path to node, npx or uvx.
• Works in a terminal, fails in the client. Run the exact command and arguments from the config by hand and read stderr.
• Remote server returns 401. You are not signed in or the token is wrong. In Claude Code run /mcp to authenticate; elsewhere check the Authorization header and that the token has not expired.
• Remote server returns 405 on GET. This is expected for servers on the 2026-07-28 revision, which removed the GET stream endpoint; the Streamable HTTP spec tells such servers to answer GET with 405. Clients talk to it with POST, so a 405 from a browser or curl GET does not mean the server is down.
• TLS errors behind a corporate proxy. A proxy that inspects HTTPS presents its own certificate, which Node-based clients may not trust. Ask IT for the proxy's CA certificate and point Node at it with the NODE_EXTRA_CA_CERTS environment variable (Node.js docs).
• Server corrupts its own output. A stdio server must only write protocol messages to stdout. Logging with console.log or print breaks it. This is a bug in the server, not your config.

FAQ

Where is the MCP config file for Claude Desktop?

On macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows it is %APPDATA%\Claude\claude_desktop_config.json. On Linux it is ~/.config/Claude/claude_desktop_config.json. The fastest way to open it is Settings, then Developer, then Edit Config.

Can I use the same MCP config in Claude, Cursor and VS Code?

Mostly. Claude Desktop, Claude Code, Cursor, Devin and VS Code's newer portable files (~/.copilot/mcp-config.json and .mcp.json) all use a top-level mcpServers key. VS Code's older .vscode/mcp.json uses servers. Environment variable syntax still differs: Cursor uses ${env:NAME}, while Claude Code and VS Code's portable files use ${NAME}.

Do I need to restart after adding an MCP server?

Claude Desktop needs a full quit and restart to load config changes. Claude Code picks up servers added with claude mcp add in new sessions, and /mcp lets you reconnect. Cursor and VS Code detect changes to their config files, but restarting the server from the MCP settings is a quick fix if tools do not appear.

Is it safe to install MCP servers with npx -y?

It works, but it runs whatever version is latest on every start, so a compromised release reaches you automatically. Pin an exact version and review changes before you upgrade. Checking the server's scan report and source first lowers the risk further.

Is .vscode/mcp.json deprecated?

The VS Code reference says new Copilot configurations should use ~/.copilot/mcp-config.json or a workspace .mcp.json instead of .vscode/mcp.json, and that the Local harness, which uses the editor's MCP client, will be removed in February 2027. Plan to move existing servers to the new files before then.

How do I test an MCP server before installing it?

Run it in the MCP Inspector, for example npx -y @modelcontextprotocol/inspector npx PACKAGE, and check its tools and their descriptions before adding it to a client.

Can I build my own MCP server instead?

Yes. Our tutorial on how to build your first MCP server walks through a small TypeScript server with two tools, testing and connecting it to Claude.