Skip to content
Agent Search Engine.
Advertise
Menu

Guide · MCP setup

How to add an MCP server to Claude Code, Cursor, VS Code, Claude Desktop and Codex

Every MCP client wants the same two facts — how to start the server, or where to reach it — and each wants them in a slightly different file. Here is each one, checked against the client's own documentation, with one local and one hosted server worked through all five.

Independent · updated 2026-09-23 · sources

An MCP server reaches your client in one of two ways. A local server is a program your client starts on your machine and talks to over standard input and output (stdio); its README gives you a launch command such as npx -y some-package or uvx some-package, often with an API key passed as an environment variable. A hosted server runs somewhere else and is reached over HTTP; its README gives you a URL, usually ending in /mcp, and sign-in happens in your client. Find which one you have, then use the section for your client.

Claude Code

Add a local server with claude mcp add <name> -- <command>. Everything after the -- is the server's own command, passed through untouched; environment variables go before it as -e KEY=value. Add a hosted server with claude mcp add --transport http <name> <url>, and a header, if the server wants a token that way, with --header "Authorization: Bearer …".

The scope decides who sees the server. The default, local, is this project for you only; --scope project writes a .mcp.json at the project root that is meant to be committed and shared; --scope user makes it available in all your projects. Check your setup with claude mcp list, remove a server with claude mcp remove <name>, and use /mcp inside a session to see status and complete a hosted server's sign-in.

Cursor

Cursor reads ~/.cursor/mcp.json for servers available everywhere and .cursor/mcp.json in a project for that project only. Both hold a top-level mcpServers object: a local server takes command, args and env; a hosted one takes url and optional headers. Values can read your environment with "${env:NAME}", which keeps keys out of a file you might commit.

VS Code

VS Code keeps workspace servers in .vscode/mcp.json and personal ones in the user-profile mcp.json (run MCP: Open User Configuration). Its format differs in one way that matters: the top-level key is servers, not mcpServers, and each entry has a type of stdio or http. From a terminal you can also run code --add-mcp '{"name":…,"command":…,"args":[…]}'. For secrets, VS Code supports input variables that prompt you instead of storing the key in the file.

Claude Desktop

For a local server, open Settings from the Claude menu, choose Developer and click Edit Config. That opens claude_desktop_config.json — ~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows — which uses the same mcpServers shape as Cursor. Quit Claude Desktop completely and reopen it afterwards; it reads the file only at start-up.

A hosted server does not go in that file. In Claude Desktop or on claude.ai, open Settings, choose Connectors, click Add, pick Add custom connector, paste the URL and complete the server's sign-in.

Codex

Add a local server with codex mcp add <name> --env KEY=value -- <command> and a hosted one with codex mcp add <name> --url <url>, adding --bearer-token-env-var TOKEN_VAR when the server takes a bearer token. Both write to ~/.codex/config.toml (or a project's .codex/config.toml) as a [mcp_servers.<name>] table; codex mcp list shows what is configured and codex mcp login <name> signs in to a server that uses OAuth.

Worked example: a local server

Brave Search MCP Server launches with BRAVE_API_KEY=<your-api-key> npx -y @brave/brave-search-mcp-server. The same command in each client's format — replace <your-api-key> first:

Claude Code · Run in your terminal

claude mcp add brave-search-mcp -e 'BRAVE_API_KEY=<your-api-key>' -- npx -y @brave/brave-search-mcp-server

Cursor · ~/.cursor/mcp.json or .cursor/mcp.json

{
  "mcpServers": {
    "brave-search-mcp": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "<your-api-key>"
      }
    }
  }
}

VS Code · .vscode/mcp.json

{
  "servers": {
    "brave-search-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "brave-search-mcp": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "<your-api-key>"
      }
    }
  }
}

Codex · ~/.codex/config.toml

[mcp_servers.brave-search-mcp]
command = "npx"
args = ["-y", "@brave/brave-search-mcp-server"]
env = { BRAVE_API_KEY = "<your-api-key>" }

Worked example: a hosted server

Supabase MCP Server is reached at https://mcp.supabase.com/mcp and signs you in through the client. In Claude Desktop, add it as a custom connector instead:

Claude Code · Run in your terminal

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

Cursor · ~/.cursor/mcp.json or .cursor/mcp.json

{
  "mcpServers": {
    "supabase-mcp": {
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

VS Code · .vscode/mcp.json

{
  "servers": {
    "supabase-mcp": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Codex · Run in your terminal

codex mcp add supabase-mcp --url https://mcp.supabase.com/mcp

When a server doesn't show up

Check the file's key and syntax. A trailing comma or mcpServers in VS Code (which wants servers) makes the whole file fail quietly.

Run the command yourself. Paste the launch command into a terminal. If it fails there — a missing key, Node.js or uv not installed — it will fail in the client too. Desktop apps sometimes cannot find npx or uvx on their PATH; giving the full path to the executable fixes that.

Read the logs and restart. Claude Desktop writes MCP logs to ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. Restart the client after any change.

Test the server on its own. The official MCP Inspector (npx @modelcontextprotocol/inspector) connects to a server directly and shows its tools and responses, which separates a broken server from a broken client config.

Servers with copy-ready setup

Each of these pages in the index shows the configuration above, generated from the project's own README command, for all five clients. Ordered by GitHub stars.

Browse every MCP server in the index →

Frequently asked

Where does Cursor keep its MCP configuration?

In ~/.cursor/mcp.json for servers available in every project, or .cursor/mcp.json at a project's root for that project only. Both use a top-level mcpServers object; a local server takes command, args and env, and a hosted one takes url and optional headers.

Why does VS Code use "servers" when everyone else uses "mcpServers"?

VS Code's own format in .vscode/mcp.json (or the user-profile mcp.json) has a top-level servers object with a type of stdio or http on each entry. Cursor, Claude Desktop and Claude Code's .mcp.json use mcpServers. Copying a Cursor config into VS Code without renaming the key is a common reason a server silently fails to appear.

Where is Claude Desktop's config file?

Open Claude Desktop's settings from the Claude menu, go to Developer and click Edit Config. The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Quit Claude Desktop completely and reopen it after editing, because it only reads the file at start-up.

How do I add a hosted (remote) MCP server to Claude Desktop?

Not through the config file. In Claude Desktop or claude.ai, open Settings, choose Connectors, click Add and pick Add custom connector, then paste the server's URL and complete its sign-in. Claude Code, Cursor, VS Code and Codex take the URL directly, as shown above.

Do I need Node.js or Python installed?

It depends on the launcher in the server's command. npx and bunx need Node.js or Bun; uvx needs uv, which runs Python packages; docker needs Docker. A hosted server needs none of them, because your client only connects to a URL.

Is the SSE transport still supported?

Claude Code's documentation marks SSE as deprecated in favour of HTTP, while keeping it for older servers. Prefer a server's streamable HTTP endpoint (usually a URL ending in /mcp) when it offers one.

How do I keep API keys out of shared config files?

Don't commit a file that contains a real key. Cursor can read a value from your environment with "${env:NAME}", Codex can send a bearer token from an environment variable with bearer_token_env_var, VS Code supports input variables that prompt for secrets, and a project-scoped .mcp.json in Claude Code is meant to be committed, so keep keys out of it.

Sources

Checked against each client's documentation on September 23, 2026. Clients change their settings screens often; if a menu has moved, the file formats above are the stable part.

Building one instead? How to build an MCP server →

More stack guides

Decision models / Decision guide

What is Jev AI? Pricing, use cases and limits

TypeSafe's decision model explained: Choice, Score and Noul, the cost per evaluation, and what to test before trusting its answers.

Read the guide

RAG / Decision guide

How to build a RAG knowledge assistant

Platform or compose-it-yourself, then the seven layers — ingestion, chunking, vector store, retrieval, orchestration, memory, and eval.

Read the guide

Voice / Decision guide

Choose and evaluate a voice agent stack

Vapi, Retell, LiveKit and Pipecat: compare architectures, test twelve difficult call scenarios, and model the complete cost.

Read the guide

Coding / Decision guide

How to build a coding agent

Adopt an agent or build your own harness, then the layers — the agent loop, code context, safe execution, the model, memory, and review.

Read the guide

Browser / Decision guide

How to build a browser-automation agent

Perception is the hard part, not clicking. DOM vs vision vs VLA, then the runtime, the driver, the model, planning, and reliability.

Read the guide

Autonomous / Decision guide

How to build an autonomous agent

Autonomy is a control problem, not a capability problem. Adopt, build, or hand-roll — then framework, tools, memory, execution, orchestration, and governance.

Read the guide

MCP / Decision guide

How to build an MCP server

The protocol is trivial; tool design is the craft. Wrap, build, or aggregate — then SDK and transport, tool design, resources, reliability, and distribution.

Read the guide

Self-hosted / Decision guide

The self-hosted agent stack

Run agents on your own infrastructure. What you're actually protecting, the platform, the model question, safe execution, data, and boring ops.

Read the guide

Frameworks / Decision guide

How to choose an agent framework

Do you need one at all? The five archetypes — code-first, role-based, typed, TypeScript-native, visual — and the criteria that actually predict regret.

Read the guide

Workflow / Decision guide

How to build AI workflow automation

Most “agents” should be workflows with LLM steps. Triggers, the engine, the LLM step, approval gates, reliability — and when to graduate to an agent loop.

Read the guide