Claude MCP List and Add: Claude Code MCP Setup

Q: Where is the Claude Code MCP config file?

Local and user servers are stored in ~/.claude.json in your home folder. Project servers are in .mcp.json at the root of your project. Claude Code doesn't read MCP servers from settings.json, and .mcp.json doesn't go inside the .claude/ folder.

Q: How do I add an MCP server to Claude Code?

Run claude mcp add in your shell, not inside a session. For a remote server, pass the transport, a name and the URL: claude mcp add --transport http notion https://mcp.notion.com/mcp. For a local server, put the start command after --: claude mcp add example -- npx -y @example/mcp-server. Then run claude mcp list to check it connects, and /mcp to sign in if it asks.

Q: How do I add an MCP server to Claude Code for all projects?

Add --scope user: claude mcp add --transport http --scope user. The server then loads in every project. Keep that for servers you'd be happy to expose to any repo you open.

Q: Can I use my Claude Desktop MCP servers in Claude Code?

Yes. Run claude mcp add-from-claude-desktop on macOS or WSL and pick the servers to import. On native Windows the import isn't available, so copy each entry from claude_desktop_config.json with claude mcp add-json.

Q: How do I stop Claude Code from asking permission for every MCP tool call?

Add allow rules for the tools you trust, such as "mcp__github__get_*" in permissions.allow. Allow rules must name a server; "mcp__*" won't work as an allow rule. Some tools are marked by their server to always ask, and no rule skips those.

On this page

Claude Code MCP Server Setup: claude mcp add, list, Config and Fixes (Nov 2026)

To add an MCP server to Claude Code, run claude mcp add in your shell. To list your servers and see if each one is connected, run claude mcp list. Remote servers take a URL (claude mcp add --transport http notion https://mcp.notion.com/mcp). Local servers take a command after --. Add --scope project to share the server through .mcp.json, or --scope user to use it in every project. Inside a session, /mcp shows status and handles sign-in.

Every command and flag below is checked against the Claude Code MCP docs as of November 2026. One rule before you start: only add servers you've checked. A server's tools run with your access, so look it up first. Our 5-minute safety checklist and the MCP Inspector cover how.

The claude mcp commands at a glance

Run these in your shell, not inside a Claude Code session (except /mcp).

Command	What it does
`claude mcp add --transport http <name> <url>`	Add a remote server
`claude mcp add <name> -- <command> [args...]`	Add a local (stdio) server
`claude mcp add-json <name> '<json>'`	Add a server from a JSON config entry
`claude mcp add-from-claude-desktop`	Import servers from Claude Desktop (macOS and WSL only)
`claude mcp list`	List every configured server with its health status
`claude mcp get <name>`	Show one server's details, including any error
`claude mcp remove <name>`	Remove a server (add `--scope <scope>` if the name is in more than one)
`claude mcp login <name>` / `logout <name>`	Run or clear a server's OAuth sign-in from the shell
`claude mcp reset-project-choices`	Reset your approve/reject choices for `.mcp.json` servers
`/mcp` (inside a session)	Status, sign-in, reconnect, and turn servers on or off

Short forms: -s for --scope, -e for --env, -t for --transport, -H for --header.

claude mcp add: add a remote (HTTP) server

HTTP is the transport the docs recommend for remote servers:

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

If the server takes an API key or token, pass it as a header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

If the server signs you in with OAuth instead (most hosted servers, such as Sentry or Notion), add it without a header, then open /mcp in a session and pick the server. Your browser opens to sign in. You can also do it from the shell with claude mcp login <name>; over SSH, add --no-browser and paste the redirect URL back.

Notes:

SSE is deprecated. On Claude Code v2.1.265 or later, the same --transport http command falls back to SSE if the server only speaks SSE. On older versions, use --transport sse.
WebSocket (wss://) servers can't be added with --transport. Use claude mcp add-json with "type":"ws" instead.

claude mcp add: add a local (stdio) server

A local server is a program Claude Code starts on your machine. Put the command that starts it after --:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Two things trip people up here:

The -- is required. Everything after it goes to the server untouched. Without it, Claude Code tries to read flags like -y or --port as its own options.
Don't put the server name right after --env. --env takes several KEY=value pairs, so the CLI reads the name as another pair and rejects it. Put another option, such as --transport stdio, in between, or put --env after the name: claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server.

Use absolute paths for local scripts. Relative paths in command or args resolve against the folder you started Claude Code from, so a server can work in one folder and fail in another. Tools on your PATH, like npx or uvx, work as-is.

For exact commands for popular servers, see the Claude Code steps in our GitHub MCP server setup and Figma MCP server setup guides.

Add a server from setup steps written for another app

Many servers only give a Claude Desktop or Cursor snippet. Look for one of three things:

A URL (https://…/mcp): use claude mcp add --transport http.
A launch command (npx -y …): use claude mcp add <name> -- <command>.
An mcpServers JSON block: pass the object inside mcpServers to add-json:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Two fixes first. If the entry has a url but no type, add "type": "http" (Claude Code treats an entry with no type as a stdio server, so it fails). And server names can only use letters, numbers, hyphens and underscores.

Import from Claude Desktop

claude mcp add-from-claude-desktop

You pick which servers to import from a list. This only works on macOS and WSL, since it reads Claude Desktop's config from its standard location there. Names with spaces or other characters are skipped (the import tells you which), and a name that already exists gets a suffix like server_1. Add --scope user to import into your user config. On native Windows, copy each entry across with add-json instead.

Claude Code MCP server configuration: scopes and .mcp.json

The scope decides where the config lives and who else gets it. Set it with --scope (or -s).

Scope	Loads in	Shared with your team	Stored in
`local` (default)	This project only	No	`~/.claude.json`, under this project's path
`project`	This project only	Yes, through git	`.mcp.json` at the project root
`user`	All your projects	No	`~/.claude.json`

claude mcp add --transport http shared-server --scope project https://example.com/mcp

That writes a .mcp.json like this, which you commit:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

If the same name is defined in more than one scope, Claude Code uses one definition, whole, in this order: local, then project, then user, then plugin servers, then claude.ai connectors. Fields aren't merged. claude mcp list and /mcp warn you when the same name points at different endpoints.

Keep secrets out of .mcp.json

.mcp.json is committed, so never paste a key into it. Reference an environment variable instead. Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

If a variable isn't set and has no default, the server still loads with the literal ${VAR} text, and claude mcp list warns about it. One safety feature to know: in a remote server's url and headers, Claude Code reads its own and your cloud provider's credentials (such as ANTHROPIC_API_KEY or NPM_TOKEN) as empty, so a shared .mcp.json can't send them to a server. Copy the value into a variable with your own name if a server really needs it. More patterns in how to keep API keys out of your MCP config.

What each scope exposes

Local is the safe default for anything with personal credentials. It never leaves your machine's ~/.claude.json.
Project means everyone who clones the repo gets the server. That's also why Claude Code asks you to approve .mcp.json servers the first time, and why a cloned repo can't pre-approve its own servers until you trust the folder. Read a repo's .mcp.json before you approve it. (Non-interactive runs such as claude -p load project servers without asking; block one by name with disabledMcpjsonServers in your settings.)
User puts the server in every project you open, including ones it has no business seeing. Keep it for read-only helpers like docs lookups (Context7, for example).

The claude mcp list command: check, get and remove servers

claude mcp list            # every server and its status
claude mcp get notion      # one server in detail
claude mcp remove notion   # delete it

claude mcp list connects to each server and shows its health next to it:

Status	What it means
`✔ Connected`	Working
`! Needs authentication`	Sign in from `/mcp` or with `claude mcp login <name>`
`✘ Failed to connect`	Claude Code couldn't reach it; the error detail follows on the same line
`⏸ Pending approval`	A `.mcp.json` server you haven't approved; run `claude` to approve it
`⊘ Disabled for this project`	Turned off in `/mcp`; turn it back on there
`✘ Blocked by enterprise managed policy`	Your organization's policy refuses it

A failure status means that server failed, not the list command. claude mcp get <name> prints the same detail on an Issue: line, with credentials redacted. list and get show ${VAR} references by name, never the resolved secret.

When you remove a remote server, Claude Code deletes the OAuth tokens it stored, but it doesn't revoke them with the provider. To revoke, run claude mcp logout <name> first, then claude mcp remove <name>.

Use /mcp inside a session

Type /mcp at the Claude Code prompt. It lists every server with its status, whether you've approved it for this project, and how many tools it has. Pick a server to:

Sign in (OAuth), Re-authenticate, or Clear authentication
Reconnect a failed server
Disable it for this project without deleting its config

To retry every failed server at once, run /mcp reconnect all (Claude Code v2.1.284 or later). Claude Code also shows a notice at startup when a server needs sign-in.

Permissions: allow and deny MCP tools

Each MCP tool gets a name like mcp__<server>__<tool>. Use those names in permission rules in settings.json (or with /permissions):

{
  "permissions": {
    "allow": ["mcp__github__get_*"],
    "ask": ["mcp__github__*"],
    "deny": ["mcp__github__merge_pull_request"]
  }
}

The rules that matter:

mcp__github__* (or just mcp__github) matches every tool from the github server. mcp__github__get_* matches its get_ tools.
Allow globs need a real server name. An allow rule like "mcp__*" or "*" is skipped and approves nothing. Deny and ask rules can use "mcp__*" to cover every MCP tool.
Server names with . or spaces turn those characters into _ (my.server becomes mcp__my_server__*).
Rules with parentheses on MCP tools are skipped in settings files. To match a tool's arguments, pass a deny rule with --disallowedTools instead.

A good default: allow the read tools you use every day, leave anything that writes, sends or deletes on "ask". Our prompt injection guide explains why a tool that reads untrusted content plus one that can send data out is the combination to watch. Tool annotations tell you which tools a server says are read-only, but treat them as hints.

Tool search: how many servers is too many?

By default, Claude Code doesn't load every tool definition up front. Tool search loads only tool names and server instructions at the start, and fetches a tool's full definition when Claude needs it. So adding servers costs far less context than it used to. There's no fixed tool cap; the limit is your context window.

You can change this with the ENABLE_TOOL_SEARCH environment variable:

Value	What happens
unset or `true`	MCP tools deferred, loaded on demand (the default)
`auto` / `auto:N`	Load tools up front until they pass 10% (or N%) of the context window, then switch to tool search
`false`	Load every MCP tool up front

To keep one server's tools always loaded, set "alwaysLoad": true in its config entry. Use that sparingly, since each loaded tool takes context. Run /context to see what MCP tools are using now. If your context still fills up fast, why MCP servers eat your context window covers how to measure and trim it. Tool search is on by default on Claude Opus 4, Sonnet 4, Haiku 4.5 and later; on older models every tool loads up front.

Timeouts

Startup: MCP_TIMEOUT in milliseconds, for example MCP_TIMEOUT=10000 claude for 10 seconds.
Tool calls, all servers: MCP_TOOL_TIMEOUT.
Tool calls, one server: a timeout field in milliseconds in that server's entry, for example "timeout": 600000 for ten minutes. It overrides MCP_TOOL_TIMEOUT for that server.
Idle calls: a call that sends no response or progress for five minutes (HTTP) or 30 minutes (stdio) is stopped. Change it with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

The full picture, including why raising a timeout on a tool that writes can backfire, is in MCP tool call timeout.

Claude Code MCP troubleshooting

Symptom	Likely cause	Fix
`✘ Failed to connect` in `claude mcp list`	Wrong URL, server down, or the command can't start	Read the detail after the status, or `claude mcp get <name>`. For stdio, run the command after `--` by hand and see if it starts
Server works in one folder, fails in another	Relative path in `command` or `args`	Use absolute paths
`.mcp.json` server never shows up	File is inside `.claude/`, or servers are under `servers` (VS Code's format) instead of `mcpServers`	Put `.mcp.json` at the repo root with an `mcpServers` key
Server added in `settings.json` never appears	`settings.json` doesn't read `mcpServers`	Use `.mcp.json` or `claude mcp add --scope user`
`⏸ Pending approval`	You dismissed the approval prompt	Run `claude` in the folder and approve it from `/mcp`
A `url` entry fails as stdio	The entry has no `type`	Add `"type": "http"` (or `"sse"` / `"ws"`)
`! Needs authentication`, or a 401	Not signed in, token expired, or a `${VAR}` in the header read as empty	`/mcp` → sign in, or `claude mcp login <name>`. Check the variable isn't a covered credential name
Connected, but 0 tools	Server started but isn't returning a tool list	`/mcp` → Reconnect. Still zero: `claude --debug=mcp` and read the server's stderr in `~/.claude/debug/`
`No such tool available`	Server still connecting or failed	`/mcp` or `claude mcp list` to check status, then Reconnect
`MCP server "<name>" is disabled`	You turned it off in `/mcp`	Turn it back on in `/mcp`
Tool call times out	Slow tool, or a startup over `MCP_TIMEOUT`	Per-server `timeout`, or see MCP tool call timeout
Agent keeps retrying a failing tool	The tool returns errors the model can't act on	MCP tool errors
`claude mcp add` says the server already exists	Same name in the same scope	`claude mcp remove <name>` first, or pick another name
Something's broken and you're not sure MCP is the cause	A server, setting or other customization	Start `claude --safe-mode`, which turns off MCP servers and other customizations. If the problem goes away, it's one of them

If a server still won't behave, test it outside Claude Code with the MCP Inspector. If it fails there too, the problem is the server, not your Claude Code config.

Before you add a server: a 2-minute check

Claude Code's own docs say to verify you trust each server before connecting it. In practice:

Find who publishes it. Prefer the vendor's own server (GitHub, Stripe, Playwright) over a lookalike. Our directory shows a trust grade for each listing.
Pin the version in local servers (npx -y package@1.2.3, not just the package name), so an update can't change the tools without you noticing.
Look at its tools with the MCP Inspector before your agent sees them.
Give it the smallest key you can: read-only tokens, one project, short expiry.

The full version, with what to do after you install, is in are MCP servers safe?

Need a server for an internal tool that doesn't exist yet? We build custom MCP servers with tight permissions from day one. Tell us what it should connect to.

Frequently asked questions

What does the claude mcp list command show?

Every MCP server Claude Code can see for the current folder, across local, project and user scopes, with a health status next to each: connected, needs authentication, failed to connect, pending approval, disabled, or blocked by policy. A failed status includes the error detail. Run it from your project folder, since local and project servers depend on where you are.

Where is the Claude Code MCP config file?

Local and user servers are stored in ~/.claude.json in your home folder. Project servers are in .mcp.json at the root of your project. Claude Code doesn't read MCP servers from settings.json, and .mcp.json doesn't go inside the .claude/ folder.

Why doesn't my MCP server show up in Claude Code?

The usual reasons: you added it in a different folder (local scope is per project), it's a .mcp.json server you haven't approved, the file is in the wrong place or uses servers instead of mcpServers, or a JSON entry with a url has no type. Run claude mcp list in the project folder, then /mcp.

How do I add an MCP server to Claude Code?

Run claude mcp add in your shell, not inside a session. For a remote server, pass the transport, a name and the URL: claude mcp add --transport http notion https://mcp.notion.com/mcp. For a local server, put the start command after --: claude mcp add example -- npx -y @example/mcp-server. Then run claude mcp list to check it connects, and /mcp to sign in if it asks.

How do I add an MCP server to Claude Code for all projects?

Add --scope user: claude mcp add --transport http <name> <url> --scope user. The server then loads in every project. Keep that for servers you'd be happy to expose to any repo you open.

Can I use my Claude Desktop MCP servers in Claude Code?

Yes. Run claude mcp add-from-claude-desktop on macOS or WSL and pick the servers to import. On native Windows the import isn't available, so copy each entry from claude_desktop_config.json with claude mcp add-json.

How do I stop Claude Code from asking permission for every MCP tool call?

Add allow rules for the tools you trust, such as "mcp__github__get_*" in permissions.allow. Allow rules must name a server; "mcp__*" won't work as an allow rule. Some tools are marked by their server to always ask, and no rule skips those.

Does adding more MCP servers slow Claude Code down or use up context?

Less than it used to. Tool search, on by default, loads only tool names until a tool is needed. Servers connect in the background, so startup doesn't wait for them unless you set alwaysLoad. Check /context to see the actual cost.