CLAUDE CODE · MCP

Claude Code MCP servers
added in one command, shared in .mcp.json.

Run claude mcp add --transport http <name> <url> for a hosted server, or claude mcp add <name> -- <command> for one that runs on your machine. It's saved for you in this project by default; --scope user adds it to every project, and --scope project writes .mcp.json for your team.

Start freeGet started Explore the team demo

Free for 3 seats · No credit cardStarter covers 3 seats · Pro is $49 a month for 5 · The demo needs no signup

Open the live team demo

Sample data, no signup · Create a free accountCreate your account

Zest lemon in its mech suit

01See your team’s AI stack

Winding / Teams Last 30 days

Zest

3 Members 1 Agent
Team overview
67%
AI Adoption▲ 34 pts
240
PRs Merged▲ 101
96.1h
Median AI Time▲ 9.5h
57.2h
Build Hours▲ 20.3h
This week
Member AI PRs/wk AI Task Plan Impl Last Standup AI Stack
22.8/wk28 min ago
15.8/wk12 min ago
4/wkAug 14
—2 hours ago
Current AI models & harnesses As of Sep 8
Claude CodeFable 5.1 (max) (with fallback)70.4 · Coding Agent Index
CodexGPT-6 Astra (max)67.0 · Coding Agent Index
Muse CodeMuse Spark 1.3 (xhigh)64.2 · Coding Agent Index
Grok BuildGrok 4.5 (high)64.1 · Coding Agent Index
Kimi Code CLIKimi K362.6 · Coding Agent Index
OpencodeGemini 3.8 Flash (high)61.2 · Coding Agent Index
Cursor CLIComposer 2.5 Fast38.3 · Coding Agent Index

Demo setups use current model families. The pairings above are the combinations benchmarked by Artificial Analysis; rankings measure performance, not popularity.

Intelligence Index

Illustrative daily trends · Other totals: last 30 days. Build Hours: this week, model-estimated activity including overlap; not engineer hours.

USED BY ENGINEERING TEAMS AT

Flyps Charm Wildfires Geoforge MisaLabs

How to add an MCP server to Claude Code

Run claude mcp add in your shell, not inside a session. A hosted server takes --transport http, a name you pick and its URL; a local one takes the name, then -- and the command that starts it. Everything after -- reaches the server untouched, so its own flags, like -y, aren't read as Claude Code's.

The Added ... line only means the entry was saved: the command isn't run and the token isn't checked. Run claude mcp get <name> to see whether the server connects.

  • --transport takes http, sse or stdio, the default. SSE is deprecated, and from v2.1.265 --transport http switches to it by itself when a server doesn't accept HTTP.
  • A wss:// WebSocket server goes in through claude mcp add-json with "type":"ws", or straight into .mcp.json.
  • Don't put the server name right after --env: it takes several KEY=value pairs and reads the name as one more. Put --transport stdio or another flag in between.
Terminal
# A hosted server over HTTP
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A hosted server that wants a token in a header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# A local stdio server: everything after -- starts it
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# An entry copied from another client's mcpServers block
claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Commands for the GitHub, Playwright, Sentry and Postgres MCP servers

The commands below come from Anthropic's own MCP docs. For more, the Anthropic Directory lists reviewed remote servers, and each one goes in with the same claude mcp add --transport http line. Add only servers you trust: one that fetches outside content can carry a prompt injection into your session.

GitHub's server takes a fine-grained personal access token, scoped to the repositories Claude should touch. Playwright needs Node.js 18 or later and drives the Chrome you already have; its first claude mcp list can read ✘ Failed to connect while npx downloads the package, so give it a moment. Sentry signs you in through the browser from /mcp. Anthropic's database example connects as a read-only user, so the SQL Claude writes can't change data.

Terminal
# GitHub, with a fine-grained personal access token
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# Playwright, a browser Claude can drive (Node.js 18+)
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Sentry, OAuth: finish the sign-in in /mcp
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Postgres through DBHub, as a read-only user
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# Anthropic's docs server: no sign-in, a good first test
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Where is the Claude Code MCP config file?

Claude Code's MCP config lives in one of two files, picked by --scope. Local, the default, keeps the server to you and to the project you ran the command in: the repository root, or that exact folder outside git. To add an MCP server globally, so it loads in every project you open, add it with --scope user.

Local and user servers both sit in ~/.claude.json (%USERPROFILE%\.claude.json on Windows), a file Claude Code also writes for itself, so let claude mcp add edit it. Claude Code doesn't read ~/.claude/mcp.json, ~/.claude/.mcp.json or %APPDATA%\Claude\mcp.json; a server written there is the usual reason /mcp reports no servers configured.

A scope can't be changed in place: remove the server with claude mcp remove <name> --scope local and add it again. When the same server is defined in several places, Claude Code uses the whole entry from the highest row below and merges nothing from the others. Local, project and user entries match by name; plugin servers and claude.ai connectors match by URL or command.

Where each scope is stored, highest precedence first, from Anthropic's MCP docs, read November 11, 2026.
ScopeHow it's addedStored inWho gets it
Local (default)claude mcp add~/.claude.json, under this project's pathYou, in this project
Project--scope project.mcp.json at the project rootEveryone who clones the repo, once they approve it
User--scope user~/.claude.json, top-level mcpServersYou, in every project
PluginInstalling the pluginThe plugin's .mcp.json or plugin.jsonAnyone who enables the plugin
claude.ai connectorclaude.ai/customize/connectorsYour claude.ai accountYou, when Claude Code is signed in with a claude.ai plan

How to share MCP servers with your team in .mcp.json

Commit .mcp.json at the repository root and everyone who clones the repo gets the same servers. claude mcp add --scope project creates or updates the file, or you can write it by hand in the shape below. Claude Code reads it when a session starts, so restart after an edit.

Keep tokens out of the file with environment variables. ${VAR} expands in command, args, env, url and headers, and ${VAR:-default} falls back when the variable is unset. A missing variable without a default doesn't stop the server: it loads with the literal ${VAR} text and claude mcp list prints a warning. An empty string counts as set, so its default never applies.

One trap with headers: in a remote server's url and headers, Claude Code reads credential variables such as ANTHROPIC_API_KEY, AWS_BEARER_TOKEN_BEDROCK and NPM_TOKEN as empty, so a checked-in file can't ship them to a server it names. The server receives a bare Bearer and rejects it, usually with a 401. Copy the value into a variable with a name of your own.

  • Give every remote entry a type. An entry with a url and no type is read as stdio, then skipped with an error; streamable-http is accepted as another name for http.
  • A malformed entry is skipped and the rest still load. claude mcp list names the field it couldn't parse.
.mcp.json
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Why does Claude Code ask me to approve .mcp.json servers?

The approval prompt is there so a repository you clone can't start processes on your machine without your say. Claude Code asks the first time it sees each project-scope server; approving all of them writes enableAllProjectMcpServers to your .claude/settings.local.json, and claude mcp reset-project-choices forgets the answers.

A repository can't approve its own servers. An enableAllProjectMcpServers or enabledMcpjsonServers committed to .claude/settings.json is ignored until you accept the folder's trust dialog.

Scripts are the exception. A claude -p run or an Agent SDK session has nobody to ask, so it loads project servers without a prompt. To keep one out, list it in disabledMcpjsonServers, which blocks it in every mode, or start with --strict-mcp-config, which uses only the servers you pass with --mcp-config.

How to list, check and remove MCP servers

claude mcp list prints every server with its health. claude mcp get <name> shows one, with the scope it came from and, when it fails, an Issue: line carrying the HTTP status or error text the server sent back. Inside a session, /mcp shows the same with each server's tool count, and lets you reconnect, sign in, or switch a server off for this project without deleting its entry.

Removing a remote server deletes the OAuth tokens Claude Code stored for it but doesn't revoke them with the provider. If the server supports revocation, run claude mcp logout <name> before claude mcp remove <name>.

Terminal
claude mcp list                    # every server and its status
claude mcp get github              # one server: scope, URL or command, any Issue: line
claude mcp remove github           # add --scope if the name is in more than one scope
claude mcp reset-project-choices   # forget your .mcp.json approvals
Inside Claude Code
/mcp                  # status, tools, reconnect, authenticate, disable
/mcp reconnect all    # retry every server that failed or needs sign-in (v2.1.284+)
/mcp disable github   # stop connecting it, keep its entry
What each status in claude mcp list means, from Anthropic's MCP quickstart, read November 11, 2026.
StatusWhat to do
✔ ConnectedNothing: it's ready
! Needs authenticationSign in from /mcp, or pass a token with --header
✘ Failed to connectRead the detail after it: the HTTP status or error the server returned
✘ Connection errorNo detail is shown, so test the URL or the command yourself
⏸ Pending approvalStart claude in the project and approve the server
⊘ Disabled for this projectSwitch it back on in /mcp
✘ Blocked by enterprise managed policyAsk your admin which policy

How to sign in to an MCP server with OAuth

Hosted servers such as Sentry, Linear and Notion sign in with OAuth. Add the URL, open /mcp in a session, pick the server and choose Authenticate; the provider's sign-in opens in your browser, and Claude Code stores the token and refreshes it from then on.

claude mcp login <name> runs the same flow from your shell. Over SSH it prints the URL for you to open on your laptop, then takes the redirect URL back at a prompt, so connect with ssh -t. A claude -p run can't sign in at all: do it once interactively before you script against the server.

A server you gave an Authorization header never falls back to OAuth. When it rejects that token, Claude Code reports a failed connection; fix the token, or remove the header to use the browser sign-in instead.

Why is my Claude Code MCP server failing to connect?

Run claude mcp get <name> first: since v2.1.219, a Failed to connect status carries the server's own error text. If that doesn't explain it, test the server outside Claude Code. A stdio server's command should start and sit waiting for input; a hosted server should answer curl -I, where a 404 or 405 still means it's up (many MCP endpoints take only POST) and a 401 or 403 means it wants a sign-in.

Terminal
# Run a stdio server's command yourself
npx -y @playwright/mcp@latest

# Probe a hosted server: 404/405 = up, 401/403 = sign in, nothing = URL or network
curl -I https://mcp.sentry.dev/mcp

# Give slow servers longer than the 30-second startup default
MCP_TIMEOUT=60000 claude
Common causes, from Anthropic's MCP quickstart and MCP reference, read November 11, 2026.
SymptomUsual cause and fix
/mcp: No MCP servers configuredThe server was added at local scope in another project, or written to a file Claude Code doesn't read. Add it here, or with --scope user
Times out at startupThe server took longer than 30 seconds, often npx downloading on its first run. Start Claude Code with a higher MCP_TIMEOUT
Connected, but no toolsUsually a missing environment variable such as an API key. Pass it with --env or in the entry's env
claude mcp get shows a different commandThe -- before the server's command was left out. Remove the server and add it again with --
401 right after pasting a tokenA trailing newline or space. claude mcp list warns Leading or trailing whitespace in: headers.Authorization
MCP endpoint not found at <origin>A 404: the URL's path is wrong. Compare claude mcp get with the server's documented endpoint
Edits to .mcp.json don't show upThe file is read at startup. Restart the session, then check claude mcp list for a parse warning

MCP timeouts and output limits in Claude Code

Two settings cover most cases: MCP_TIMEOUT for how long a server may take to start, and MCP_TOOL_TIMEOUT for how long one tool call may run. Both are environment variables in milliseconds, and a timeout field on one server's entry overrides the tool-call limit for that server. A call in the main conversation that runs past two minutes moves to a background task, so Claude keeps working.

Big results don't flood the conversation. Claude Code warns above 10,000 tokens, and a successful text result over the 25,000-token cap, or over 50,000 characters whatever its token count, is saved to a file in the session's tool-results folder under ~/.claude/projects/; Claude gets the path and reads the file when it needs to.

Defaults from Anthropic's MCP reference and environment variables reference, read November 11, 2026.
SettingDefaultWhat it limits
MCP_TIMEOUT30 secondsA server's startup
MCP_TOOL_TIMEOUTAbout 28 hoursOne tool call, by the wall clock
timeout in a server's entryUnsetOne tool call on that server; values under 1,000 are ignored
Per-request timer (HTTP, SSE, connectors)60 seconds to the first byteRaised when the tool timeout or MCP_TIMEOUT is set higher
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT5 minutes remote, 30 minutes stdioA call with no response or progress; 0 turns the check off
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS2 minutesWhen a main-conversation call moves to the background; 0 keeps it in front
MAX_MCP_OUTPUT_TOKENS25,000 tokensA tool result before it goes to a file; the 10,000-token warning is fixed
Response size16 MiBOne HTTP or SSE response; a bigger one fails

Do MCP servers fill up Claude Code's context?

MCP servers take little context by default, because tool search is on. A session starts with each server's tool names and instructions, and a tool's full schema loads only when Claude looks it up, so Claude Code sets no cap on tools per server: your context window is the limit. /context all shows what each loaded MCP tool costs in tokens.

ENABLE_TOOL_SEARCH=false loads every tool up front, and auto does so until the definitions pass 10% of the context window (auto:5 sets 5%). For a small server Claude needs on every turn, set "alwaysLoad": true on its entry instead; startup then waits up to five seconds for that server's tools.

How to allow or block MCP tools in Claude Code

Every MCP tool is called mcp__<server>__<tool>, and permission rules use that name. mcp__github__*, or the bare mcp__github, covers every tool on the github server; a full name covers one tool. An allow rule takes a wildcard only after a literal server name, so mcp__* under allow is skipped and approves nothing, while under deny it removes every MCP tool from Claude's context.

Settings files skip any mcp__ rule written with parentheses; to deny one tool only for a given argument, pass the rule with --disallowedTools instead. Dots and spaces in a server's name become underscores (my.server is mcp__my_server__*), and a plugin's server takes the long form mcp__plugin_<plugin>_<server>__*. Hook matchers and a skill's allowed-tools use the same names.

.claude/settings.json
{
  "permissions": {
    "allow": ["mcp__github__get_*", "mcp__puppeteer__puppeteer_navigate"],
    "deny": ["mcp__sentry__*"]
  }
}

MCP servers from plugins, Claude Desktop and claude.ai

A plugin can ship servers in an .mcp.json at its root or under mcpServers in plugin.json. They start when the plugin is enabled and leave when it's uninstalled, not through claude mcp remove, and their tool names carry the plugin, so a hook matcher or permission rule written for the bare server key misses them.

claude mcp add-from-claude-desktop copies servers from Claude Desktop's config through a picker, on macOS and WSL only. A name with a space or any character outside letters, digits, hyphens and underscores is skipped, and a name already taken gets a suffix such as server_1. /import does the same from Codex, Cursor or the Gemini CLI, along with their instructions, commands, subagents and skills.

Connectors added at claude.ai appear in /mcp by themselves when Claude Code is signed in with a claude.ai plan. They stay away when an API key, an apiKeyHelper or a cloud provider such as Bedrock supplies the credential; "disableClaudeAiConnectors": true in settings, or ENABLE_CLAUDEAI_MCP_SERVERS=false for one shell, turns them off.

MCP, skill or hook: which one does the job?

Reach for an MCP server when Claude needs a system it can't see, such as an issue tracker, a database or a browser. Anthropic's trigger is a habit: you keep copying data into the chat from a tab Claude can't open.

A skill is knowledge rather than a connection, and the two pair well: the server reaches the database, and a skill holds your schema and the queries your team trusts. A hook fires on every matching event whether Claude chooses to or not, so a rule that must always hold belongs there, even when the hook does its work by calling an MCP tool, like a Slack message whenever Claude edits a critical file.

Which MCP servers does your team actually use?

On your own machine, /usage answers part of it: on a Pro, Max, Ultra, Team or Enterprise plan it shows what share of your last 24 hours or 7 days went to each MCP server, counting only the requests that used one of its results. It reads this machine's history only, and nobody else's.

Configured isn't the same as used. In one engineer's 323 Claude Code sessions (September 2 to October 3, 2026), Claude never called the Stripe plugin's MCP tools, though the plugin was enabled at user scope the whole time.

Zest gives the same answer for a whole team. Its Claude Code plugin records each MCP tool a session calls, by its full mcp__server__tool name and the number of calls, and the AI Stack view rolls them up per engineer beside their skills and subagents, as on Claude Code usage. It reads a tool's name, never its input or output. Zest also runs an MCP server of its own: the app gives you a claude mcp add --transport http zest line with a personal token, and Claude Code can then ask your team's session data a question.

What Zest doesn't show: a server that's set up but never called, and how much context each server's tools take. /mcp and /context all cover those on your machine.

TRY IT ON YOUR TEAM

See what your team ships with AI.

Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing

A FEW THINGS TO KNOW

Questions

Where is the MCP config file in Claude Code?+

Local and user servers are in ~/.claude.json: local ones under the project's path, user ones under the top-level mcpServers key. Project servers are in .mcp.json at the repository root. Claude Code doesn't read ~/.claude/mcp.json.

How do I add an MCP server to Claude Code globally?+

Add it at user scope, with claude mcp add --scope user followed by the transport, the name and the URL or command. It then loads in every project you open and stays private to you.

Can Claude Code use my Claude Desktop MCP servers?+

Yes, on macOS and WSL. claude mcp add-from-claude-desktop lists the servers in Claude Desktop's config and copies the ones you pick; names with spaces or other characters outside letters, digits, hyphens and underscores are skipped.

Does Claude Code support SSE MCP servers?+

Yes, though SSE is deprecated. From v2.1.265, claude mcp add --transport http falls back to SSE when a server won't take HTTP; on older versions, pass --transport sse.

Can Claude Code run as an MCP server?+

Yes. claude mcp serve starts Claude Code as a stdio MCP server that Claude Desktop or another client can connect to. It exposes Claude Code's tools, and the client is responsible for asking before each call.