How to Add an MCP Server to Claude Code (Tested with Real Servers)
To add an MCP server to Claude Code, run claude mcp add <name> -- <command> for a server that runs on your machine, or claude mcp add --transport http <name> <url> for a hosted one. Then run claude mcp list to check that it connected. By default the server is saved for the current project only, inside ~/.claude.json. Add --scope project to write it to a shareable .mcp.json instead.
I tested this with five servers that need no account or API key (filesystem, memory, sequential-thinking and everything through npx, fetch through uvx) plus Anthropic’s hosted docs server. Below are the commands, the real output, where each config ends up, and the errors I triggered on purpose.
Tested on: Claude Code 2.1.326, macOS (Apple Silicon), 17 November 2026. Every command below was run for this guide and the outputs are copied from that run. Drafted with AI assistance (Claude) and checked against the official docs linked in the text.
The two commands you need
# Local server (stdio): everything after -- is the command that starts it
claude mcp add <name> -- npx -y <package> [args...]
# Remote server (Streamable HTTP)
claude mcp add --transport http <name> <url>
Run these in your normal terminal, not inside a claude session. Three flags cover most cases (from the official Claude Code MCP docs):
--scope(-s):local(the default),projectoruser.--env(-e):KEY=valueenvironment variables for a local server.--header(-H): HTTP headers for a remote server, such as"Authorization: Bearer YOUR_TOKEN".
The -- matters. It separates Claude Code’s options from the server’s command, so a flag like -y goes to npx and not to claude. Forgetting it is the most common mistake (see troubleshooting).
Before you start
- Node.js 24 or later for the npm reference servers, as their READMEs state (for example the memory server README).
- uv for Python servers such as fetch, which run through
uvx. - Your terminal in the project folder. Local-scoped servers belong to the folder you run the command in, or to its git root.
$ claude --version
2.1.326 (Claude Code)
$ node --version
v26.8.2
$ npx --version
11.19.1
$ uvx --version
uvx 0.12.5 (210d1f678 2026-08-14 aarch64-apple-darwin)
$ sw_vers -productVersion
26.7.1
$ uname -m
arm64
Step 1: Add a local stdio server (filesystem)
The filesystem server gives Claude file tools limited to the folders you pass as arguments. I gave it only the project folder:
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects/demo
There’s no --transport flag, because stdio is the default when you give a command. The output names the config file it wrote:
Added stdio MCP server filesystem with command: npx -y @modelcontextprotocol/server-filesystem ~/tmp/exploreday-mcp/proj to local config
File modified: ~/.claude.json [project: ~/tmp/exploreday-mcp/proj]
“Added” only means the config was saved. The MCP quickstart warns that the first claude mcp list can show ✘ Failed to connect while npx is still downloading the package, so check twice before you debug.
Step 2: Pass environment variables with –env (memory)
The memory server keeps a small knowledge graph in a JSONL file. Its README says to set MEMORY_FILE_PATH to a path you own, because the default file sits inside the npx cache and vanishes when that cache is cleared:
claude mcp add memory --env MEMORY_FILE_PATH=~/projects/demo/memory.jsonl \
-- npx -y @modelcontextprotocol/server-memory
claude mcp get memory
Added stdio MCP server memory with command: npx -y @modelcontextprotocol/server-memory to local config
$ claude mcp get memory
memory:
Scope: Local config (private to you in this project)
Status: ✔ Connected
Type: stdio
Command: npx
Args: -y @modelcontextprotocol/server-memory
Environment:
MEMORY_FILE_PATH=~/tmp/exploreday-mcp/memory.jsonl
To remove this server, run: claude mcp remove memory -s local
Put the server name before --env, or put another option between them. The docs warn that a name placed right after --env is read as one more KEY=value pair and rejected:
$ claude mcp add --env FOO=bar broken -- npx -y @modelcontextprotocol/server-memory
Invalid environment variable format: broken, environment variables should be added as: -e KEY1=value1 -e KEY2=value2
exit=1
Step 3: Add a server from JSON with add-json (fetch)
Many READMEs only give an mcpServers JSON block written for Claude Desktop. Pass the inner object, without the mcpServers wrapper, to claude mcp add-json. Here’s the Python fetch server, which turns web pages into Markdown:
claude mcp add-json fetch '{"type":"stdio","command":"uvx","args":["mcp-server-fetch"]}'
Added stdio MCP server fetch to local config
uvx downloaded mcp-server-fetch on the first health check, and it showed ✔ Connected in the list below.
If the JSON you copied has a url but no type, add "type": "http" yourself. Claude Code reads an entry without a type as stdio, so a bare url fails.
Step 4: Share a server with your team (project scope)
--scope project writes the server to .mcp.json in the project root, which you commit:
claude mcp add --scope project sequential-thinking \
-- npx -y @modelcontextprotocol/server-sequential-thinking
Added stdio MCP server sequential-thinking with command: npx -y @modelcontextprotocol/server-sequential-thinking to project config
File modified: ~/tmp/exploreday-mcp/proj/.mcp.json
$ cat .mcp.json
{
"mcpServers": {
"sequential-thinking": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sequential-thinking"
],
"env": {}
}
}
}
Project servers need approval. In an interactive session Claude Code asks before it starts a server from .mcp.json, so a cloned repo can’t launch processes on your machine without consent. Until then, claude mcp list shows ⏸ Pending approval (run `claude` to approve). If you dismissed the prompt, claude mcp reset-project-choices brings it back (project scope docs).
Security note for scripts: print mode (claude -p) can’t show that approval prompt. When I ran claude -p in a fresh folder containing only a .mcp.json, the server connected straight away with no prompt (its status in the system/init event was connected), which matches the headless docs. In my main test folder, which already had local-scope servers registered, the same kind of project server stayed pending. So don’t count on the approval step to protect you in scripts: read a cloned repo’s .mcp.json before you run claude -p in it.
Step 5: Add a remote server (HTTP, and what about SSE?)
Anthropic’s Claude Code docs server needs no sign-in, so it’s an easy remote test:
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config
$ claude mcp get claude-code-docs
claude-code-docs:
Scope: Local config (private to you in this project)
Status: ✔ Connected
Type: http
URL: https://code.claude.com/docs/mcp
For a local HTTP server, I ran the everything reference server in Streamable HTTP mode on port 3917:
PORT=3917 npx -y @modelcontextprotocol/server-everything streamableHttp
claude mcp add --transport http everything-http http://127.0.0.1:3917/mcp
$ PORT=3917 npx -y @modelcontextprotocol/server-everything streamableHttp
Starting Streamable HTTP server...
MCP Streamable HTTP Server listening on 127.0.0.1:3917
$ claude mcp add --transport http everything-http http://127.0.0.1:3917/mcp
Added HTTP MCP server everything-http with URL: http://127.0.0.1:3917/mcp to local config
$ claude mcp get everything-http
everything-http:
Scope: Local config (private to you in this project)
Status: ✔ Connected
Type: http
URL: http://127.0.0.1:3917/mcp
- SSE is deprecated. Since v2.1.265,
--transport httpswitches to SSE by itself when a server doesn’t accept HTTP. Use--transport sseonly on older versions or to force it. - Auth: add
--header "Authorization: Bearer YOUR_TOKEN". OAuth servers such as Notion or Sentry show! Needs authenticationuntil you sign in from/mcpor withclaude mcp login <name>. - WebSocket servers (
"type": "ws") only go in throughadd-jsonor.mcp.json.
Not tested here: SSE is deprecated, so I didn’t add an SSE server for this guide. The syntax is the same as HTTP with --transport sse; see the official MCP docs.
Check, inspect and remove servers
claude mcp list # every server and its health
claude mcp get <name> # one server: scope, command or URL, status
claude mcp remove <name> # add --scope local|project|user if the name is in several
/mcp # inside a session: status, tools, sign-in, reconnect, disable
With all the test servers added, claude mcp list printed this (my own servers and connectors trimmed):
Checking MCP server health…
sequential-thinking: npx -y @modelcontextprotocol/server-sequential-thinking - ⏸ Pending approval (run `claude` to approve)
filesystem: npx -y @modelcontextprotocol/server-filesystem ~/tmp/exploreday-mcp/proj - ✔ Connected
memory: npx -y @modelcontextprotocol/server-memory - ✔ Connected
claude-code-docs: https://code.claude.com/docs/mcp (HTTP) - ✔ Connected
fetch: uvx mcp-server-fetch - ✔ Connected
Note the project-scope server: it stays ⏸ Pending approval until you open claude in that folder and approve it.
Other statuses you may see are ! Needs authentication, ✘ Connection error and ⊘ Disabled for this project (full list). Inside a session, /mcp shows tool counts and lets you reconnect, sign in, or switch a server off without deleting it.
A green tick only proves the server started. To check the tools work, I had Claude write to the memory graph and list the folder through the filesystem server in print mode:
claude -p "Use the memory MCP server to create one entity named exploreday-test ... \
Then use the filesystem MCP server to list the files in this directory." \
--allowedTools "mcp__memory__*" "mcp__filesystem__*" --max-turns 6
CALL mcp__memory__create_entities {"entities":[{"name":"exploreday-test","entityType":"note","observations":["added with claude mcp add"]}]}
RESULT is_error=false: {"entities":[{"name":"exploreday-test","entityType":"note","observations":["added with claude mcp add"]}]}
CALL mcp__filesystem__list_directory {"path":"~/tmp/exploreday-mcp/proj"}
RESULT is_error=false: {"content":"[FILE] .mcp.json"}
FINAL success turns=4 cost_usd=0.3230102
The directory holds one file, `.mcp.json`.
- `mcp__memory__create_entities`: created the entity `exploreday-test` (type `note`) with the observation "added with claude mcp add".
- `mcp__filesystem__list_directory`: listed this directory and found only `.mcp.json`.
$ cat memory.jsonl
{"type":"entity","name":"exploreday-test","entityType":"note","observations":["added with claude mcp add"]}
The whole run cost $0.32 and took 4 turns. Claude first loaded the two MCP tools on demand (a ToolSearch call), then used them.
MCP tools are named mcp__<server>__<tool>, and mcp__memory__* allows every tool from one server (permissions docs). In scripts, the system/init event of --output-format stream-json lists each server’s status:
INIT mcp_servers=[
{"name":"sequential-thinking","status":"pending","source":"project"},
{"name":"filesystem","status":"connected","source":"local"},
{"name":"memory","status":"connected","source":"local"},
{"name":"claude-code-docs","status":"connected","source":"local"},
{"name":"fetch","status":"connected","source":"local"},
{"name":"everything-http","status":"connected","source":"local"}]
That’s the system/init event from the same run, filtered to my test servers. In this folder the project server showed as pending and wasn’t loaded. In a fresh folder it connected without asking (see the security note above), so check the status field in your own runs rather than assuming.
Removing takes one command per server. To change a server’s scope, remove it and add it again, because scope is fixed when you add it:
Removed MCP server "filesystem" from local config
Removed MCP server "memory" from local config
Removed MCP server "fetch" from local config
Removed MCP server "claude-code-docs" from local config
Removed MCP server "everything-http" from local config
Removed MCP server sequential-thinking from project config
$ cat .mcp.json
{
"mcpServers": {}
}
Claude Code MCP config file location
Claude Code keeps the three scopes in two files:
| Scope | File | Where inside it | Who gets the server |
|---|---|---|---|
local (default) |
~/.claude.json |
projects["/path/to/project"].mcpServers |
You, in this project only |
project |
.mcp.json in the project root |
mcpServers |
Everyone who clones the repo, after approval |
user |
~/.claude.json |
top-level mcpServers |
You, in every project |
Here’s what my test left in each file. I printed the local entry with jq so the rest of ~/.claude.json stays private:
== .mcp.json (project scope)
{ "mcpServers": { "sequential-thinking": { "type": "stdio", "command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"], "env": {} } } }
== ~/.claude.json, this project's entry (local scope)
{
"filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", ".../proj"], "env": {} },
"memory": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"],
"env": { "MEMORY_FILE_PATH": ".../memory.jsonl" } },
"claude-code-docs": { "type": "http", "url": "https://code.claude.com/docs/mcp" },
"fetch": { "type": "stdio", "command": "uvx", "args": ["mcp-server-fetch"] },
"everything-http": { "type": "http", "url": "http://127.0.0.1:3917/mcp" }
}
== key used in ~/.claude.json
~/tmp/exploreday-mcp/proj
One gotcha I found: on macOS the temp folder is a symlink, and Claude Code stored local-scope servers under the resolved path (/private/var/...), not the path I typed. If a local server “disappears”, check which path your project is listed under.
Details worth knowing, from the quickstart and the scopes docs:
- On Windows,
~/.claude.jsonis%USERPROFILE%\.claude.json. WithCLAUDE_CONFIG_DIRset, Claude Code reads.claude.jsonfrom that folder. - Claude Code does not read
~/.claude/.mcp.json,~/.claude/mcp.json,~/.claude/config/mcp.jsonor%APPDATA%\Claude\mcp.json. - MCP “local scope” isn’t
.claude/settings.local.json. Local servers live in~/.claude.json. - When one name exists in several places, local beats project, then user, then plugins, then claude.ai connectors. Fields aren’t merged.
.mcp.jsonexpands${VAR}and${VAR:-default}incommand,args,env,urlandheaders, so you can commit it without secrets.- Companies can deploy
managed-mcp.jsonto/Library/Application Support/ClaudeCode/on macOS (managed MCP docs).
Claude Code reads .mcp.json at session start, so restart the session after editing it.
Windows: when you need cmd /c
I couldn’t test this part, because I have no Windows machine for this guide. The MCP reference server READMEs still say to launch npx through cmd /c on Windows (see the everything README). In Claude Code that’s:
claude mcp add memory -- cmd /c npx -y @modelcontextprotocol/server-memory
Claude Code’s own docs no longer ask for it: the quickstart says claude mcp add works the same in PowerShell and Command Prompt, and v2.1.119 removed a “false-positive” warning about the wrapper. So add the server without it first, and add cmd /c only if an npx server fails to connect on native Windows. WSL doesn’t need it.
Troubleshooting: documented errors and fixes
/mcp says “No MCP servers configured”
You added the server from another folder, or edited a file Claude Code doesn’t read. Run claude mcp add again from the project, or use --scope user.
You forgot the — separator
$ claude mcp add broken npx -y @modelcontextprotocol/server-memory
error: unknown option '-y'
exit=1
Without --, Claude Code tries to read -y as one of its own options and refuses. Nothing gets added.
Remove the entry and add it again with -- before npx. claude mcp get <name> shows the exact command Claude Code will run.
“has a “url” but no “type”” and unset variables
The docs quote this message: MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. An unset ${VAR} with no default still loads, but claude mcp list warns and the server gets the literal ${VAR} text. I put both mistakes in a test .mcp.json:
MCP config diagnostics ⚠
[Has warnings] Project config (shared via .mcp.json)
├ [Warning] [bad-url-no-type] mcpServers.bad-url-no-type: Skipped — MCP server "bad-url-no-type" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry
└ [Warning] [missing-var] mcpServers.missing-var: Missing environment variables: EXPLOREDAY_UNSET_VAR
Server already exists
$ claude mcp add memory -- npx -y @modelcontextprotocol/server-memory
MCP server memory already exists in local config
exit=1
Remove the old entry or pick another name. If the name is in several scopes, remove reports exists in multiple scopes, so add --scope.
No server found with that name
$ claude mcp get does-not-exist
No MCP server named "does-not-exist". Configured servers: claude-code-docs, ... (your other servers)
exit=1
$ claude mcp remove does-not-exist
No MCP server named "does-not-exist". Configured servers: claude-code-docs, fetch, filesystem, memory, sequential-thinking
exit=1
The error lists every server Claude Code can see, which is the quickest way to spot a typo in the name.
You’re probably not in the folder where you added the local server. cd back and try again.
✘ Failed to connect or ✘ Connection error
- Since v2.1.219,
listandgetadd the HTTP status or error text to a failed status. Read it first. - For a stdio server, run its command yourself. If it starts and waits for input, the server is fine and your entry is wrong. If it errors, the message names what’s missing, such as a newer Node.js.
- For an HTTP server, run
curl -I <url>: 404 or 405 means it’s up (many endpoints only accept POST), 401 or 403 means you need auth, and silence means a wrong URL or network. Leading or trailing whitespace in: headers.Authorizationusually means a token pasted with a trailing newline.
Timed out at startup, or connected with no tools
The default startup timeout is 30 seconds, and a first npx or uvx download can take longer: start with MCP_TIMEOUT=60000 claude. A server that connects but lists no tools is usually missing an environment variable such as an API key.
Gotchas worth knowing
- Local scope follows the git root. Inside a repo, a local server belongs to the repository root, not the subfolder you ran the command in.
- Servers cost context. Each server’s tool names and instructions load into every session. Tool search, on by default, defers the full definitions, but unused servers are still worth removing.
- Web-reading servers can carry prompt injection. The docs warn about this for servers like fetch. Only add servers you trust.
- Notes count too. The filesystem server is one way to give Claude Code an Obsidian vault; my guide to connecting Claude Code to Obsidian covers the vault side.
FAQ
Where is the Claude Code MCP config file?
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 project root. claude mcp get <name> shows which scope holds a server.
Can I edit .mcp.json by hand instead of using claude mcp add?
Yes. Use type plus url for remote servers and command plus args for local ones, restart the session, and approve the server when asked.
Does Claude Code use my Claude Desktop MCP servers?
Not automatically. claude mcp add-from-claude-desktop imports them on macOS and WSL. Names containing anything other than letters, numbers, hyphens and underscores are skipped.
How do I add an MCP server in VS Code?
Type /mcp in the extension’s chat panel (adding there needs v2.1.261 or later), or run claude mcp add in the integrated terminal. Per the VS Code docs, both save to the same configuration.
Sources
- Claude Code docs: Connect Claude Code to tools via MCP
- Claude Code docs: Connect to MCP servers (quickstart and troubleshooting)
- Claude Code docs: Run Claude Code programmatically
- Claude Code docs: Permissions
- Claude Code docs: Managed MCP configuration
- Claude Code docs: VS Code
- Claude Code changelog
- MCP reference servers on GitHub
- Model Context Protocol introduction