How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more

What an MCP server is

An MCP server is a program that exposes tools to an agent over the Model Context Protocol: query a database, open a page in a browser, file a GitHub issue. The agent decides when to call a tool; the client (Claude Code, Cursor and so on) asks you for permission.

There are two kinds you will meet. A stdio server runs locally as a process, so the config holds a command and arguments. An HTTP (streamable HTTP) server lives at a URL, so the config holds the URL and auth headers. The third transport, SSE, is marked deprecated in the Claude Code docs.

Ready-made servers are in the MCP servers section and the best MCP servers list.

Commands and config files by agent

Checked against official docs on 2026-10-24.

Sources: Claude Code, Codex, Cursor, VS Code, Gemini CLI, Devin Desktop, Kiro, Zed.

How to add an MCP server to Claude Code

A local stdio server. Everything after -- is the launch command:

claude mcp add --scope project --env API_KEY=... my-server -- npx -y <server-package>

A remote HTTP server:

claude mcp add --transport http my-remote https://example.com/mcp --header "Authorization: Bearer ..."

--scope decides who sees it. The default, local, keeps the server private to you in this project and writes to ~/.claude.json. user enables it in every project. project writes .mcp.json at the repo root; commit that file and the whole team gets the server. If you already have a JSON entry, pass it as is with claude mcp add-json.

Claude Code warns when a tool returns more than 10,000 tokens and caps output at 25,000 by default (MAX_MCP_OUTPUT_TOKENS).

Example mcpServers JSON

A .mcp.json with one local and one remote server. Names and the package are placeholders; treat it as a template:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "<server-package>"],
      "env": { "API_KEY": "${API_KEY}" }
    },
    "my-remote": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
    }
  }
}

In Claude Code an entry with url but no type is an error, because it gets read as stdio. ${VAR} and ${VAR:-default} expand in command, args, env, url and headers, which keeps tokens out of the repo.

Why an MCP config does not port between agents

• VS Code expects servers, not mcpServers. It will ignore a file copied from Cursor. A portable .mcp.json at the workspace root only works behind the experimental chat.mcp.workspaceRootConfig.enabled setting.
• Codex uses TOML: [mcp_servers.name] with command and args, or url and bearer_token_env_var. Startup timeout defaults to 10 seconds, tool calls to 60.
• Gemini CLI treats url as SSE; streamable HTTP goes in httpUrl. Claude Code uses type: http plus url instead.
• Devin Desktop reads remote addresses from serverUrl and allows 100 tools in total across all servers.
• Cursor interpolates with ${env:NAME}, ${userHome} and ${workspaceFolder}, not the Claude Code ${VAR} form.
• Zed keeps servers under context_servers in its own settings.

If you run two or more agents, generate the configs from one source. rulesync, ruler and block/ai-rules all write MCP entries into each agent's native file. More in the config formats guide.

Security checks before you connect a server

An MCP server runs code on your machine or calls your accounts with your token. So:

• Claude Code asks for approval before starting project servers from .mcp.json in an interactive session; leave that on;
• Cursor asks before each tool call by default;
• in Gemini CLI, trust: true turns confirmations off entirely, so reserve it for servers you wrote;
• keep tokens in environment variables, never in a file that goes to git.

An open-source server with an active repo is easier to reason about than a closed binary. Every card in the catalog shows license, stars and last update in its trust passport.