claude mcp add: How to Add MCP Servers to Claude Code (Syntax and Examples)

claude mcp add registers an MCP server with Claude Code from your terminal. For a remote server, run claude mcp add --transport http <name> <url>. For a local server, put Claude's options first, then --, then the command that starts the server: claude mcp add --transport stdio <name> -- npx -y some-server.

After adding, run claude mcp list to check it connected, and use /mcp inside Claude Code to sign in to servers that need OAuth. The rest of this guide covers every common form of the command and the mistakes that trip people up.

Checked against: Claude Code's MCP documentation on 2 November 2026. Commands are quoted from those docs; eSEOspace did not run them for this guide.

Basic syntax

# Remote server over HTTP (recommended)
claude mcp add --transport http <name> <url>

# Local server that runs as a process
claude mcp add [options] <name> -- <command> [args...]

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

Add a remote (HTTP) server

The docs call HTTP "the recommended option for connecting to remote MCP servers." Their Notion example:

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

If the server takes a fixed token instead of OAuth, pass it as a header:

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

Anthropic's docs say "the SSE (Server-Sent Events) transport is deprecated." Use --transport sse only when a vendor offers nothing else. The docs add that Claude Code v2.1.265 or later tries HTTP first and switches to SSE when a server does not accept HTTP. Our SSE vs Streamable HTTP comparison explains why.

Add a local (stdio) server

The docs' Airtable example shows the full pattern:

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

Three rules from the docs:

1. The -- "separates Claude's own options, such as --transport, --env, and --scope, from the command and arguments that run the server."
2. "Everything after -- is passed to the server untouched." So claude mcp add --transport stdio myserver -- python server.py --port 8080 runs python server.py --port 8080.
3. --env accepts several KEY=value pairs. If the server name comes right after --env, the CLI reads it as another pair and rejects it. Put another option, such as --transport stdio, in between.

Add a server from JSON

If a vendor gives you a JSON block, use add-json:

claude mcp add-json <name> '<json>'

This is also the way to add a WebSocket server, since the docs say --transport "doesn't accept ws." Their example:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

If you already set up servers in Claude Desktop, claude mcp add-from-claude-desktop imports them. The docs say this "only works on macOS and Windows Subsystem for Linux (WSL)."

Choose a scope

Every add command accepts --scope:

Example: claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic. Our Claude Code MCP scopes guide covers precedence and team approvals in detail.

Sign in with OAuth

Many hosted servers use OAuth. After adding one, run /mcp inside Claude Code and follow the browser sign-in. From the shell, claude mcp login <name> does the same; add --no-browser to get a URL to open yourself.

For servers that need a pre-registered OAuth app, the docs show:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

--client-secret prompts with masked input; in CI, set MCP_CLIENT_SECRET instead. --callback-port fixes the redirect to http://localhost:PORT/callback.

Manage servers after adding

claude mcp list            # all servers, with health status
claude mcp get notion      # details for one server
claude mcp remove notion   # remove a server
claude mcp logout notion   # clear stored credentials

claude mcp list shows states such as ✔ Connected, ! Needs authentication, ✘ Failed to connect and ⏸ Pending approval. Anthropic notes that removing a remote server deletes its stored tokens but does not revoke them. To revoke, run claude mcp logout <name> before claude mcp remove <name>.

Timeouts and big outputs

• MCP_TIMEOUT=10000 claude sets a 10-second startup timeout.
• A "timeout": 600000 field (milliseconds) on one server's .mcp.json entry sets its tool timeout.
• Claude Code warns when tool output passes 10,000 tokens and limits it to 25,000 by default. MAX_MCP_OUTPUT_TOKENS=50000 raises the cap.

Test a server before adding it

If a server misbehaves, test it on its own with the MCP Inspector. The MCP docs say it runs with npx @modelcontextprotocol/inspector and needs Node 22.19.0 or newer. It also has a --cli mode for scripts. If the server works there but not in Claude Code, the problem is usually the add command: a flag after --, a wrong scope, or a missing sign-in.

Admins who want to control which servers people can add should read Anthropic's managed MCP docs, which describe options from an approved catalog to turning MCP off. Claude Code itself installs with one command on macOS, Linux and WSL, per its setup docs.

Common mistakes

• Flags after --. They go to the server, not Claude. Move --env and --scope before the name.
• Same name, same scope. The docs say adding a duplicate fails with an "already exists" error. Remove the old one first.
• Reserved names. claude mcp add rejects built-in names such as workspace.
• Forgetting to sign in. A server stuck at "Needs authentication" just needs /mcp.

Next step

Add one server you will use daily, such as GitHub or your docs. Our guides to connecting Claude Code to GitHub and the best MCP servers for Claude Code are good starting points. For team rollouts with approved servers, see our Claude Code consulting service.

Frequently asked questions