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

Claude Code connects to MCP (Model Context Protocol) servers to reach tools outside your terminal: an issue tracker, a database, a browser, a publishing tool. One command adds a server, a scope decides who else gets it, and /mcp inside a session shows what is connected.

The short version: for a remote server run claude mcp add --transport http <name> <url>, then open /mcp in Claude Code to sign in. For a local one run claude mcp add <name> -- <command>. Add --scope project to write it to .mcp.json so your team gets it too. Everything below is from Anthropic's Claude Code MCP documentation, checked October 22, 2026.

How do I add an MCP server to Claude Code?

Remote servers over HTTP are the recommended kind. Give the server a name and its URL:

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 with --header (or -H). A local server runs as a process on your machine; everything after -- is the command that starts it:

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

The -- matters: without it, the server's own flags would be read as Claude Code's. SSE servers still work with --transport sse, but Anthropic marks SSE as deprecated, so use HTTP where the server offers it.

What do the MCP scopes mean in Claude Code?

• local (the default): only you, only in this project. Stored in ~/.claude.json under the project's path.
• project: everyone working in the repository. Stored in .mcp.json at the project root, so it goes into version control.
• user: only you, in every project. Stored in ~/.claude.json.

Pick one with --scope (or -s). When the same name is defined in more than one place, local wins over project, project over user, and the whole entry from the winner is used; fields are not merged.

How do I share MCP servers with my team?

Add them with --scope project, or write .mcp.json by hand and commit it. Keep secrets out of the file with variables, which Claude Code expands 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}" }
    }
  }
}

${VAR} takes the variable's value and ${VAR:-default} falls back to the default. Two safety rules to know: Claude Code asks each person to approve project servers before it uses them (reset those answers with claude mcp reset-project-choices), and well-known credential variables such as ANTHROPIC_API_KEY or NPM_TOKEN expand to nothing in a remote server's URL or headers, so a repository cannot send them elsewhere. Copy a value into a variable of your own name if a server really needs it.

How do I sign in to a remote MCP server?

Add the server, then type /mcp in Claude Code and finish the sign-in in your browser. Claude Code stores the tokens and refreshes them; "Clear authentication" in /mcp revokes them. From the shell, claude mcp login <name> runs the same flow and claude mcp logout <name> clears it. If the provider does not support dynamic client registration, register an app with it, use http://localhost:PORT/callback as the redirect address, and add the server with --client-id, --client-secret and --callback-port.

How do I list, check and remove MCP servers?

claude mcp list            # every server and its health
claude mcp get notion      # one server's details
claude mcp remove notion   # remove it, with its stored sign-in
claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp"}'
claude mcp add-from-claude-desktop   # copy servers from Claude Desktop (macOS and WSL)

Inside a session, /mcp shows each server as connected, needing sign-in, failed, waiting for approval or disabled, and /mcp reconnect all retries the failed ones. In add-json, an entry with a url must also say "type": "http", or Claude Code treats it as a local server.

Why is my MCP server not working in Claude Code?

• It is slow to start. Raise the startup timeout for the session, for example MCP_TIMEOUT=10000 claude for ten seconds.
• Its results are cut short. MCP output is capped at 25,000 tokens by default; raise it with MAX_MCP_OUTPUT_TOKENS=50000.
• A project server never loads. It is waiting for your approval; start claude interactively and accept it.
• A variable shows up literally. An unset ${VAR} with no default stays as text and claude mcp list warns about it.
• The server's flags were swallowed. Put the server's command after --.

Can Claude Code be an MCP server itself?

Yes. claude mcp serve runs Claude Code as a local MCP server, so another client can call its tools. In Claude Desktop, add it with "command": "claude" and "args": ["mcp", "serve"], using the full path to claude if it is not on your PATH. Plugins can also bring their own MCP servers: installing the plugin adds them and uninstalling removes them.

A worked example: posting from Claude Code

Skryvo is a remote MCP server for social media:

claude mcp add --transport http skryvo https://api.skryvo.ai/mcp

Open /mcp, sign in, and ask "Write a LinkedIn post about the bug we just fixed and schedule it for tomorrow at 9am." Claude Code drafts it in your brand's voice, shows it, and schedules it only after you approve. The Claude Code setup page also covers the plugin route. The same server works in Claude as a connector, in Codex and in Cursor.

Keep personal servers at user scope, shared ones in a committed .mcp.json with every secret behind a variable, and check /mcp whenever a tool goes quiet.