Claude Code MCP Server Setup Guide (2026): claude mcp add, Transports & Config Scopes Explained

To add an MCP server to Claude Code, run claude mcp add <name> -- <command> for a local stdio server, or claude mcp add --transport http <name> <url> for a remote one, then verify with claude mcp list until it shows Connected. The server's tools become available to Claude automatically in every session at that config scope, no extra prompting needed.

What MCP actually does for Claude Code

Claude Code already ships with file read/write, Bash, and grep-style search. MCP (Model Context Protocol) exists for everything outside that: your database, your ticketing system, a browser you want driven headlessly, an internal API, or a proprietary CLI wrapped as tools. When you connect an MCP server, Claude Code queries it at session start for a tool list, then can call those tools mid-conversation the same way it calls its built-in ones.

The practical rule of thumb: don't build or install a server that duplicates something Claude Code already does well (filesystem search, running shell commands). Reach for MCP when you need to hit a system Claude has no native access to.

The claude mcp add command

Run these commands in your regular shell, not inside an active claude session. Once inside a session, use the /mcp slash command to inspect or manage connections instead.

# Local stdio server (runs as a subprocess)
claude mcp add my-server -- node ./mcp-server/index.js

# Local server with environment variables
claude mcp add my-db -e DATABASE_URL=postgres://localhost/mydb -- npx -y @some/postgres-mcp

# Remote HTTP server
claude mcp add --transport http github https://mcp.github.com

# Remote SSE server (older transport, still common)
claude mcp add --transport sse notion https://mcp.notion.com/sse

After adding, confirm it actually connected:

claude mcp list
# Check my-server   Connected
# Check github      Connected
# X my-db       Failed to connect

A failed connection almost always means one of three things: the subprocess command is wrong (typo in path, missing binary), a required environment variable wasn't set, or a remote server needs an OAuth sign-in step that hasn't completed yet. Run claude mcp get <name> to see the exact command and args Claude Code is trying to launch.

Transports: stdio vs HTTP vs SSE

Stdio servers are the most common for anything touching local resources, since they inherit your shell's environment and filesystem access. Remote HTTP/SSE servers are simpler to add but depend on the vendor's uptime and often gate access behind OAuth.

Config scopes: local, project, and user

Claude Code stores MCP server definitions in one of three scopes, and picking the wrong one is the most common source of "it worked yesterday, why is it gone today" confusion:

• local (default) - saved to a project-specific config file, not committed to git, only visible to you in that directory.
• project - saved to .mcp.json at the project root, meant to be committed so teammates get the same servers automatically.
• user - saved to your global config, available across every project on your machine.

Add the scope flag explicitly when it matters: claude mcp add --scope project github -- .... If you're setting up a server that only you need (personal API keys, local dev tools), keep it at local or user scope so secrets don't end up in a committed .mcp.json.

Common connection failures and fixes

• "Failed to connect" on a stdio server - test the exact command outside Claude Code first (node ./mcp-server/index.js). If it errors there, MCP isn't the problem.
• Server connects but Claude never calls its tools - check that the tool descriptions are specific. Claude decides whether to call a tool based on its description matching the task; vague names like "run_query" get ignored in favor of built-in tools.
• OAuth loop on a remote server - run /mcp inside an active session and look for a pending auth step; some servers need you to approve access in a browser tab before the first tool call succeeds.
• Works locally, breaks in CI or a teammate's machine - you're likely using local scope with environment variables only set on your machine. Move the server definition to project scope and document the required env vars in your README instead of hardcoding them.

Cost angle: MCP tool calls still bill as API tokens

Every MCP tool call and its result get folded into the conversation context, which means a chatty database server returning large JSON blobs can quietly inflate your token bill same as any other tool. If you're running Claude Code against the official Anthropic API, this adds up fast on long agentic sessions that call MCP tools dozens of times per task.

This is one of the reasons a lot of developers point ANTHROPIC_BASE_URL at a cheaper relay instead of paying Anthropic's list price directly. Safa API is one option: it's an OpenAI-compatible relay that sits in front of Claude, GPT, and Gemini through one endpoint, at a lower per-token price than official billing, with prompt caching supported (which matters a lot once MCP tool results start piling into your context window). It also doesn't require a US credit card - Alipay works - which is the other common blocker for developers outside the US trying to get Claude API access at all. Setup in Claude Code is just swapping the base URL and API key, nothing else changes about how MCP servers behave.

Frequently Asked Questions

Do I need to restart Claude Code after adding an MCP server?

Yes for new sessions - server definitions are read at session start. If you're mid-session and add a server from another terminal, start a new claude session (or use /mcp to check status) rather than expecting it to hot-load.

Can I use MCP servers with a third-party API relay instead of the official Anthropic API?

Yes. MCP configuration is independent of which API endpoint Claude Code talks to. As long as ANTHROPIC_BASE_URL points to an OpenAI/Anthropic-compatible relay like Safa API, your MCP servers work exactly the same way regardless of which model backend is serving the requests.

What's the difference between claude mcp add and editing .mcp.json by hand?

claude mcp add is the safer path since it validates the command and writes correctly-formatted JSON. Hand-editing .mcp.json works too but a malformed entry will silently fail to load rather than throwing a clear error, so stick with the CLI unless you're scripting bulk additions.