How to add an MCP server to Claude Code
To add an MCP server to Claude Code, run claude mcp add. For a remote server use --transport http and its URL; for a local one use --transport stdio and put the server command after --. Then run claude mcp list or /mcp to check that it connects. Reported from the docs, read 2026-10-26; not run by us.
Checked by Agentic Weekly's editorial process: vendor docs re-read.
Last verified: 2026-10-26 (America/Chicago) · Versions covered: Claude Code MCP docs as read on 2026-10-26; no Claude Code version recorded for these commands · Evidence: Reported (see “What we tested”)
Pick a transport: remote HTTP or local stdio
An MCP server is a program that gives an AI agent tools; see What is an MCP server?. Claude Code can talk to one over HTTP (a remote service) or stdio (a program it starts on your machine). Everything on this page is from Claude Code's MCP documentation, read 2026-10-26, and it is Reported: we have not run these commands.
| Transport | Command shape | When to use | Source and date |
|---|---|---|---|
| HTTP | claude mcp add --transport http <name> <url> | The docs call HTTP the recommended option for remote servers and the most widely supported transport for cloud services | Claude Code MCP docs, read 2026-10-26 |
| stdio | claude mcp add [options] <name> -- <command> [args...] | A local process that Claude Code starts and talks to over standard input and output | Claude Code MCP docs, read 2026-10-26 |
| SSE | claude mcp add --transport sse <name> <url> | Deprecated per the docs; use HTTP where available. The docs say the HTTP command falls back to SSE for services that only expose it | Claude Code MCP docs, read 2026-10-26 |
| WebSocket | claude mcp add-json <name> '<json>' with "type": "ws" | For remote servers that push events; configured in .mcp.json or with add-json, authentication by header only | Claude Code MCP docs, read 2026-10-26 |
Docs change often and describe behaviour by Claude Code version, so re-check the source before relying on a flag.
Get the weekly brief: which AI tools to update, try or skip. Free.
Free. Unsubscribe anytime. No spam. We email a confirmation link first. Privacy
Add a remote server
claude mcp add --transport http <name> <url>
claude mcp add --transport http notion https://mcp.notion.com/mcpclaude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"The docs say that when a server needs OAuth, you sign in from the /mcp panel inside a session, or run claude mcp login <name> in your shell; a claude -p or Agent SDK run cannot start the sign-in. For a worked token example, see GitHub MCP server: how to set it up.
Evidence: Reported. Source: Claude Code MCP docs, read 2026-10-26.
Add a local server
claude mcp add [options] <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverThe docs explain that the -- (double dash) separates Claude Code's own options, such as --transport, --env and --scope, from the command that starts the server; everything after it is passed to the server untouched. Without it, Claude Code would read the server's flags as its own. --env accepts several KEY=value pairs; if the server name comes straight after --env, the command reads the name as another pair and fails, so put another option, such as --transport stdio, between them.
A worked example for the reference Git server, built by combining the docs' command shape with that server's README. We have not run it as a command, though we did test the server itself outside Claude Code (see Git MCP server: setup and what we tested):
claude mcp add --transport stdio git -- uvx mcp-server-git --repository /path/to/repoEvidence: Reported. Source: Claude Code MCP docs, read 2026-10-26.
Check it connected
claude mcp list
claude mcp get notion
/mcp # inside a Claude Code sessionclaude mcp addprints anAdded ...line when the configuration was written; that is not proof the server connects.claude mcp listshows a health status next to each server, such as Connected, Needs authentication or Failed to connect.claude mcp get <name>shows details; for a failed server it shows the HTTP status or error code on anIssue:line.- Statuses that report a configuration decision instead of a connection: Pending approval (a project server from
.mcp.jsonyou have not approved), Rejected, and Disabled for this project.
Evidence: Reported. Source: Claude Code MCP docs, read 2026-10-26.
Scopes: local, project, user
| Scope | Loads in | Shared with team | Stored in | Flag |
|---|---|---|---|---|
| local (default) | Current project only | No | ~/.claude.json | --scope local |
| project | Current project only | Yes, via version control | .mcp.json in the project root | --scope project |
| user | All your projects | No | ~/.claude.json | --scope user |
Project-scoped servers need your approval before Claude Code connects to them. The docs note that this "local scope" is different from general local settings, which live in .claude/settings.local.json. Source: Claude Code MCP docs, read 2026-10-26.
Remove or disable a server
claude mcp remove notionThe docs say that removing a remote server also deletes the OAuth tokens and client registration Claude Code stored for it. To switch a server off for one project without removing it, use the /mcp panel. Source: Claude Code MCP docs, read 2026-10-26.
Troubleshooting
| Symptom | Likely cause | Fix | Source |
|---|---|---|---|
| A placeholder token is accepted at add time, then the server fails | claude mcp add saves the configuration without validating credentials | Run /mcp and check for a checkmark or an X; fix the token and add the server again. | Claude Code MCP docs, read 2026-10-26 |
A JSON entry with a url is skipped with a message about a missing type | An entry with no type is read as a stdio server | Add "type": "http" (or sse or ws) to the entry. | Claude Code MCP docs, read 2026-10-26 |
| The server's own flags are rejected or misread | Without --, Claude Code parses the flags as its own | Put the whole server command after --. | Claude Code MCP docs, read 2026-10-26 |
--env error when adding | The name directly after --env is read as another KEY=value pair | Place another option, such as --transport stdio, between --env and the name. | Claude Code MCP docs, read 2026-10-26 |
| A server needs authentication | The server answered 401 or 403 and Claude Code flagged it | Open /mcp and complete the sign-in; in claude -p runs, sign in from an interactive session first. | Claude Code MCP docs, read 2026-10-26 |
| A local npm-based server is older than expected | npm on an older Node installs older package versions without an error | Check node --version. Our study measured this for four packages, including the MCP filesystem server and the MCP Inspector. | Our study: older Node installs older servers, 2026-10-25 |
What we tested
Evidence: Reported (not run by us). We did not run claude mcp add, list, get or remove for this guide.
- What we ran: nothing for these commands. Our only Claude Code test is a separate smoke test on 2026-10-25 of a headless edit with a local model; see the Claude Code test log. That task did not involve MCP servers.
- Reported, from the Claude Code MCP docs, read 2026-10-26: every command, flag, scope and status on this page.
- Not tested: OAuth sign-in, project approval prompts, plugins, managed configuration, WebSocket servers, Windows behaviour, and whether any listed server connects or works.
| Section | Evidence | Source |
|---|---|---|
| Transports, remote, local | Reported | Claude Code MCP docs, read 2026-10-26 |
| Check, scopes, remove | Reported | Claude Code MCP docs, read 2026-10-26 |
| Git server worked example | Reported (combination of two documents) | Claude Code MCP docs, read 2026-10-26 and Git server README |
Related tools
- Claude Code: Update now if you use the sandbox or run Claude Code on a cloud provider; skip if you wanted flashy new features, this is a hardening release. Tested (smoke test, 2026-10-25, local Qwen2.5-3B-Instruct, not vendor models).
FAQ
How do I add an MCP server to Claude Code?
Run claude mcp add. For a remote server use claude mcp add --transport http <name> <url>; for a local one use claude mcp add --transport stdio <name> -- <command>. Then check with claude mcp list. This is from the Claude Code docs, read 2026-10-26; we have not run it.
What is the difference between local, project and user scope?
Per the docs, local scope (the default) loads only in the current project and is private to you. Project scope stores the server in .mcp.json so your team shares it through version control. User scope loads in all your projects.
How do I see which MCP servers Claude Code has?
Run claude mcp list for each server and a health status, claude mcp get <name> for details on one server, or /mcp inside a session. These commands are from the Claude Code docs, read 2026-10-26.
How do I remove an MCP server from Claude Code?
Run claude mcp remove <name>, for example claude mcp remove notion. The docs say removing a remote server also deletes the OAuth tokens and registration Claude Code stored for it. We have not run this command.
Why does my MCP server show as failed?
The docs say Failed to connect means Claude Code could not reach the server, and claude mcp get <name> shows the HTTP status or error. Common causes are a wrong token, a missing type on a JSON entry or a server command that does not start.
Have you tested these commands?
No. We have not run claude mcp add, list, get or remove for this guide, so every command is copied from the Claude Code docs, read 2026-10-26. Our Claude Code test log covers a different task.
Sources
- Claude Code MCP documentation (fetched 2026-10-26)
- mcp-server-git README (for the worked example) (fetched 2026-10-26)
Related
Page history
- : First published. Claude Code MCP docs read on this date; nothing was run.
Markdown version for agents: /guides/add-mcp-server-to-claude-code.md
Free · weekly · about six minutes
Get The Weekly Verdict, free
What shipped this week, what is worth switching to, and what to ignore. We run what we can and label what we only read.
- One email a week. Each release gets one call: update now, worth a look, or skip.
- Every claim shows its evidence. Reported means we read the sources; Tested means we ran it, with the exact scope and the failures left in.
- A free AI Tools Cheat Sheet (web page and printable PDF) lands in your inbox when you confirm.
Free. Unsubscribe anytime. No spam. We email a confirmation link first and add you only after you click it. We use your email only to send this newsletter and never sell it. Privacy