Skip to content
Agent Search Engine.
Submit a tool
Menu

Guide · MCP setup

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

Identify the server's launch command or hosted URL, its authentication requirements and the configuration scope. Each client stores these differently. These local and hosted examples were checked against the linked client documentation.

By Agent Search Engine · Client documentation reviewed 2026-09-23 · sources

Documentation and decision review ·

Check the actual client, protocol and permission boundary

The current MCP specification is dated July 28, 2026. A specification release does not establish support in your installed client and server. Check their versions, selected transport and documented compatibility together; a working connection does not grant permission to use every available tool.

Local stdio starts code on your machine; hosted HTTP sends requests to a service. Inspect the executable or endpoint, credentials, accessible resources and tool allowlists before connecting. MCP standardizes a tool interface; A2A describes communication between agents. Neither label proves that two products will work together.

  • Start with a harmless read on a resource you control. Inspect the returned data and requested scopes before enabling writes.
  • Check where tool arguments, results and logs go, how to revoke the connection, and any service or model charges.
  • Use the current documentation for your client. The worked launch examples below retain their earlier review date; this protocol and permission review does not recertify every package command or client version.

Primary sources: MCP specification, July 28, 2026 · A2A specification · Codex MCP configuration. Documentation review does not establish hands-on performance or compatibility.

Choose tools for building and checking an MCP connection →

Download the MCP connection checklist · CSV. Record your actual client version, server, authentication, scope, discovered tools and errors. All ten client/transport test rows start as not run; the guide's September 23 documentation review does not establish compatibility with every current version. Keep secrets out of the sheet.

Before connecting: access and data

This record's specific permissions have not been reviewed by ASE. Read the publisher's documentation before copying setup or connecting.

  • List the accounts, files and services the enabled tools can read, change or execute. Check your actual credentials and discovered tools.
  • Use narrowly scoped credentials and read-only mode where supported. Review proposed writes before approving them; a generated configuration does not apply these limits for you.
  • Local launch is not local-only data processing. External services receive requests, and your client may pass tool results to its model provider. Check both destinations before sharing private data.
  • Keep keys and browser session files out of shared config, repositories and screenshots. Know how to disconnect the server and separately revoke its credentials or account sessions.

Access guidance reviewed 2026-10-11. Local execution, account permissions, data destinations and revocation are separate checks from configuration syntax. The worked examples retain their original launch commands; no access restrictions are applied automatically.

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:

Before connecting: access and data

Brave's connector sends search/context requests to Brave's API. Local stdio launch does not keep queries on your machine.

Publisher documentation checked ; recheck due . These are documented capabilities, not a tested connection or security assessment.

Can read
  • Search, context and summarization results returned through the enabled Brave tools.
Can change
  • The checked toolset is retrieval-oriented, rather than general browser or account editing. API requests can still consume plan usage.
Code and process execution
  • The client launches a local server for stdio. Retrieval tools do not establish that the process is sandboxed.
Credentials and account state
  • A Brave API key supplied through BRAVE_API_KEY or the documented key-file option. Treat it as a secret.
Data destinations
  • Queries and parameters reach Brave's API; optional context location headers can include location. Your client may forward results to its model provider.
Limits of this check
  • No local-only, provider-retention or zero-cost assurance was checked. Stdio is the default; HTTP exposure needs separate review.
Limit access before connecting
  • Use --enabled-tools/--disabled-tools or the corresponding BRAVE_MCP_ENABLED_TOOLS/BRAVE_MCP_DISABLED_TOOLS settings. Inspect discovered tools and current plan limits.
Disconnect and revoke access
  • Disconnect the server and revoke the API key in Brave's dashboard; generate a replacement if needed. Removing local config alone does not revoke the key.
  • List the accounts, files and services the enabled tools can read, change or execute. Check your actual credentials and discovered tools.
  • Use narrowly scoped credentials and read-only mode where supported. Review proposed writes before approving them; a generated configuration does not apply these limits for you.
  • Local launch is not local-only data processing. External services receive requests, and your client may pass tool results to its model provider. Check both destinations before sharing private data.
  • Keep keys and browser session files out of shared config, repositories and screenshots. Know how to disconnect the server and separately revoke its credentials or account sessions.

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:

Before connecting: access and data

This record's specific permissions have not been reviewed by ASE. Read the publisher's documentation before copying setup or connecting.

  • List the accounts, files and services the enabled tools can read, change or execute. Check your actual credentials and discovered tools.
  • Use narrowly scoped credentials and read-only mode where supported. Review proposed writes before approving them; a generated configuration does not apply these limits for you.
  • Local launch is not local-only data processing. External services receive requests, and your client may pass tool results to its model provider. Check both destinations before sharing private data.
  • Keep keys and browser session files out of shared config, repositories and screenshots. Know how to disconnect the server and separately revoke its credentials or account sessions.

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 only after reviewing its publisher, credentials and access scope. 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. Use test credentials and harmless read-only calls after the same access review; this is a debugging tool, not a sandbox. It 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 practical guides

Everyday AI / Decision guide

How to choose an AI tool for your everyday work

Choose AI tools by the job, setup, data, language and total cost. Compare two candidates with a free worksheet and practical tests, without coding.

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

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
Browse all guides →