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

One command adds a server. Where it's saved decides who else gets it. The commands, the JSON, the limits and the servers worth adding.

Published 2026-10-07 by Richard Kaminsky and Mitchell Lipyansky, the co-founders of Poly. Canonical: https://usepoly.co/claude-code-mcp
Poly is a multiplayer AI coding workspace: a shared room where your team works with one AI agent, together. Free to start: https://usepoly.co/

**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.

*Claude Code's MCP scopes, from Anthropic's docs, October 7, 2026.*

| Scope | Stored in | Loads in | Shared with the team |
| --- | --- | --- | --- |
| Local (default) | ~/.claude.json, under the project | This project | No |
| Project | .mcp.json in the repository | This project | Yes, through git, after approval |
| User | ~/.claude.json, top level | Every project | No |
| Managed | managed-mcp.json, set by an admin | Every project | Everyone in the organization |

## How do you add an MCP server to Claude Code?

From Anthropic's MCP guide ([Anthropic](https://code.claude.com/docs/en/mcp)):

- **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](https://code.claude.com/docs/en/mcp), [environment variables](https://code.claude.com/docs/en/env-vars)):

- **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](https://registry.modelcontextprotocol.io):

- **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](https://learn.chatgpt.com/docs/extend/mcp)). 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](/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?](/what-is-poly)

## Common questions

**How do I add an MCP server to Claude Code?**

Run claude mcp add --transport http <name> <url> for a remote server, or claude mcp add <name> -- <command> for a local one. Add --scope project to share it through a .mcp.json file, or --scope user for every project.

**Where is the MCP config file for Claude Code?**

Local and user servers are stored in ~/.claude.json (local ones under the project path). Project servers are in .mcp.json at the repository root. Claude Code does not read mcpServers from settings.json.

**What does the .mcp.json file look like?**

A JSON object with an mcpServers key; each server has a type (http or stdio) and either a url and optional headers, or a command, args and env. Environment variables expand with ${VAR}.

**Is SSE still supported in Claude Code MCP?**

It still works, but Anthropic's docs mark the SSE transport as deprecated and recommend HTTP servers. The MCP specification's standard transports are stdio and Streamable HTTP.

**How do I add an MCP server to Codex?**

Run codex mcp add <name> -- <command>, or use --url for a remote server. Codex stores servers in ~/.codex/config.toml under [mcp_servers.<name>], shared by the CLI, the editor extension and the ChatGPT desktop app.

More guides: https://usepoly.co/guides · Security: https://usepoly.co/security · Pricing: https://usepoly.co/pricing