Claude Code MCP servers: how to add one, where the config lives, and which to use

To add an MCP server to Claude Code, run claude mcp add: for a remote server, claude mcp add --transport http notion https://mcp.notion.com/mcp, and for a local one, claude mcp add playwright -- npx -y @playwright/mcp@latest. By default the server is saved in local scope, private to you and this project, in ~/.claude.json; add --scope project to write it to a .mcp.json file at the repository root that your team shares through git, or --scope user to use it in every project. Type /mcp in a session to check status and sign in to servers that use OAuth.

Key takeaways

• Remote servers: use --transport http. SSE still works but is deprecated.
• Local servers: everything after -- is the command that starts the server.
• Three scopes: local (default) and user are stored in ~/.claude.json; project is .mcp.json in the repository, and teammates approve it on first use.
• Context cost: tool search is on by default, so MCP tools load only when needed; tool output warns at 10,000 tokens and stops at 25,000.
• Trust: Anthropic says to verify you trust each server, because servers that fetch outside content can carry prompt injection.

How do you add an MCP server to Claude Code?

From Anthropic's MCP guide (Anthropic):

• Remote (HTTP): claude mcp add --transport http notion https://mcp.notion.com/mcp. Add --header "Authorization: Bearer your-token" for a server that takes an API key.
• Local (stdio): claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server. The -- matters: without it, Claude Code tries to read the server's own flags as its options.
• From JSON: claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp"}'.
• From the Claude desktop app: claude mcp add-from-claude-desktop imports its servers (macOS and WSL).

Manage them with claude mcp list, claude mcp get <name> and claude mcp remove <name>. Inside a session, /mcp shows each server's status and tools, and lets you sign in, reconnect or switch one off.

SSE is deprecated. Anthropic's docs say "The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead," and the MCP specification's standard transports are now stdio and Streamable HTTP.

Where is the Claude Code MCP config file?

• Local scope (the default): ~/.claude.json, under the project's path. Private to you, this project only.
• Project scope: .mcp.json at the repository root, committed to git. Claude Code asks each person to approve its servers the first time.
• User scope: ~/.claude.json, at the top level. Private to you, every project.

On Windows the file is %USERPROFILE%\.claude.json. When the same name appears in more than one place, local beats project and project beats user. Claude Code doesn't read mcpServers from settings.json or a .mcp.json inside ~/.claude, a common mistake.

A .mcp.json with one remote and one local server:

{
  "mcpServers": {
    "api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

${VAR} and ${VAR:-default} expand from your environment, so keys stay out of git. An entry with a url must say "type": "http"; one with no type is treated as a local command.

How do MCP servers sign in?

Remote servers that use OAuth: add the server, then choose Authenticate in /mcp or run claude mcp login <name>. Claude Code stores the tokens and refreshes them; claude mcp remove deletes them. Servers that take an API key get it through --header (remote) or --env (local). A fixed Authorization header turns OAuth off for that server.

Limits and settings worth knowing

From Anthropic's docs (Anthropic, environment variables):

• Tool search is on by default: MCP tools are deferred and loaded when Claude needs them, so a dozen servers don't fill the context. ENABLE_TOOL_SEARCH=false loads everything upfront, and "alwaysLoad": true exempts one server.
• Output: a warning when a tool returns more than 10,000 tokens, and a cap of 25,000 (MAX_MCP_OUTPUT_TOKENS raises it).
• Startup: MCP_TIMEOUT, 30 seconds by default. Raise it if a first npx download is slow.
• Resources: type @ to reference one, for example @github:issue://123.
• Prompts from a server show up as slash commands.
• Claude Code as a server: claude mcp serve lets another MCP client use Claude Code's tools.

Which MCP servers should you add?

Official servers from the vendors, each listed under its own name in the MCP Registry:

• GitHub: https://api.githubcopilot.com/mcp/ with a personal access token.
• Sentry: https://mcp.sentry.dev/mcp, OAuth.
• Notion: https://mcp.notion.com/mcp.
• Stripe: https://mcp.stripe.com.
• Linear: https://mcp.linear.app/mcp.
• Figma: https://mcp.figma.com/mcp.
• Playwright (Microsoft), a local server for driving a browser: npx -y @playwright/mcp@latest.

Connectors you add on claude.ai also load in Claude Code when you sign in with your Claude account. Anthropic reviews connectors in its directory, but it "does not security-audit or manage any MCP server," and the registry is in preview. Prefer servers published by the vendor itself.

How do you add an MCP server to Codex?

Codex keeps MCP servers in ~/.codex/config.toml, shared by the CLI, the editor extension and the ChatGPT desktop app (OpenAI). Add one with codex mcp add context7 -- npx -y @upstash/context7-mcp, or --url for a remote server. In the file, each server is a [mcp_servers.<name>] table with command and args, or url. More in How to use Codex.

Why won't my MCP server connect?

• Check the status: claude mcp list shows Connected, Needs authentication, Failed or Pending approval, and claude mcp get <name> gives the error.
• Local servers: run the command yourself first, use absolute paths, and check the -- is there.
• Slow start: set MCP_TIMEOUT=60000.
• Edited .mcp.json: restart Claude Code.
• Debug: claude --debug=mcp writes a log; claude --safe-mode starts with all MCP off to rule it out.
• Windows: current versions run npx directly; the old cmd /c wrapper is only needed on older releases.

MCP servers in a shared room

A project-scope .mcp.json gives everyone the same servers, but each person still runs their own session. Poly (usepoly.co) is a shared browser room where a team works with one Claude Code or Codex agent; each member connects their own tools, and a connector only acts on its owner's prompts and asks its owner before changing anything. Free to start. What is Poly?