# Claude Code MCP Setup: Config File Location & Add Server Command (2026)

> Claude Code MCP config lives in ~/.claude.json (user scope) or .mcp.json (project scope). Full file paths on Mac, Windows and Linux, the claude mcp add command syntax for HTTP/SSE/stdio transports, all 3 scopes explained, and the best MCP servers for Claude Code in 2026.

**Source:** https://mcpplaygroundonline.com/blog/claude-code-mcp-setup-best-servers-guide  
**Author:** Nikhil Tiwari  
**Published:** 2026-02-05  
**Updated:** 2026-02-05  
**Category:** Tutorial  
**Reading time:** 12 min read

---

✓ Quick Answer

**Claude Code MCP config file location:** User-scope servers live in `~/.claude.json` (all your projects). Project-scope servers live in `.mcp.json` at your project root (committed to git, shared with your team). Local-scope servers are stored privately in your user state per project.

claude mcp add command syntax:

```
# Remote HTTP server
claude mcp add --transport http <name> <url>

# Remote SSE server
claude mcp add --transport sse <name> <url>

# Local stdio server (npm package)
claude mcp add <name> -- npx -y <package>

# Specify scope (default is local)
claude mcp add --scope user <name> ...
claude mcp add --scope project <name> ...
```

Verify your remote server works before running `claude mcp add` — paste the URL into the free [MCP server tester](/mcp-server-tester) and check tools/list, schemas and auth in seconds.

TL;DR

-   `claude mcp add --transport http <name> <url>` for remote servers
-   `claude mcp add <name> -- npx -y <package>` for local stdio servers
-   3 scopes: **local** (default, you only), **project** (.mcp.json, shared with team), **user** (all your projects)
-   Top servers: GitHub, Sentry, Notion, PostgreSQL, Filesystem, Context7

[Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) is Anthropic's AI-powered CLI for software development. It connects to external tools through MCP servers — giving it access to your databases, GitHub repos, error trackers, and more. This guide covers everything: how to add servers, the 3 scopes, all transport types, and the best servers to install.

## Install Claude Code

```
curl -fsSL https://claude.ai/install.sh | sh
```

## Adding MCP Servers: 3 Transport Types

### 1\. Remote HTTP Server (Recommended for cloud services)

```
# Syntax
claude mcp add --transport http <name> <url>

# Examples
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

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

After adding, run `/mcp` inside Claude Code to authenticate with OAuth if the server requires it.

### 2\. Remote SSE Server (Legacy, prefer HTTP)

```
# SSE transport is deprecated — use HTTP where available
claude mcp add --transport sse asana https://mcp.asana.com/sse
```

### 3\. Local stdio Server (For local processes)

```
# Syntax: options first, then server name, then -- command
claude mcp add --transport stdio <name> -- <command> [args...]

# Examples
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
claude mcp add --transport stdio --env GITHUB_TOKEN=ghp_xxx github -- npx -y @modelcontextprotocol/server-github
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb"
```

**Important:** All flags (`--transport`, `--env`, `--scope`) must come _before_ the server name. The `--` separates the name from the command/args passed to the server.

## MCP Installation Scopes

Scope

Flag

Stored in

Who sees it

**Local** (default)

`--scope local`

`~/.claude.json` (under project path)

Only you, current project only

**Project**

`--scope project`

`.mcp.json` at project root

Everyone on the team (commit to git)

**User**

`--scope user`

`~/.claude.json`

Only you, all projects

### When to use which scope

-   **Local** — Personal servers, experiments, sensitive credentials for one project
-   **Project** — Team-shared tools. The `.mcp.json` file gets committed to git, so everyone gets the same MCP setup
-   **User** — Personal utilities you use across all projects (filesystem, memory, etc.)

```
# Add for this project only (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Share with team (creates .mcp.json)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# Available in all your projects
claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
```

### Project .mcp.json example

When you use `--scope project`, Claude Code creates/updates a `.mcp.json` file at your project root:

```
{
 "mcpServers": {
 "github": {
 "type": "http",
 "url": "https://api.githubcopilot.com/mcp/"
 },
 "sentry": {
 "type": "http",
 "url": "https://mcp.sentry.dev/mcp"
 },
 "db": {
 "command": "npx",
 "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://..."],
 "env": {}
 }
 }
}
```

It supports environment variable expansion: `${API_KEY}`, `${VAR:-default}`. Keep secrets in env vars, not in the file.

## Managing Servers

```
# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# Inside Claude Code: check server status
/mcp

# Import servers from Claude Desktop
claude mcp add-from-claude-desktop
```

## Best MCP Servers for Claude Code (2026)

### Essential Starter Kit

**GitHub MCP**

PRs, issues, code search, repo management

```
claude mcp add --transport http github https://api.githubcopilot.com/mcp/
```

**Sentry MCP**

Error monitoring, stack traces, debugging

```
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

**Notion MCP**

Docs, databases, project management

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

**Filesystem MCP**

Read/write files beyond the project directory

```
claude mcp add filesystem --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
```

### Full Server Recommendations

Category

Server

What it does

**Code**

GitHub MCP

PRs, issues, code search, commit history

**Monitoring**

Sentry MCP

Errors, stack traces, release tracking

**Docs**

Notion MCP

Read/write pages, databases, search

**Database**

@bytebase/dbhub

Query Postgres, MySQL, SQLite with natural language

**Files**

Filesystem MCP

File read/write/search outside project

**Context**

Context7

Real-time library documentation for LLMs

**Memory**

Memory MCP

Persistent knowledge graph across sessions

**Thinking**

Sequential Thinking

Reflective problem-solving for complex tasks

**Browser**

Playwright MCP

Browser automation, testing, scraping

**Infra**

Docker MCP Toolkit

200+ containerized MCP servers, one-click setup

**Context cost:** Each MCP server adds 500–2,000 tokens to your context window. Start with 3–5 servers and add more as needed. If you have many servers, Claude Code's **MCP Tool Search** automatically kicks in (when tool definitions exceed 10% of context) to load tools on-demand.

## Practical Workflow Examples

### Debug a production error

```
# Add Sentry + GitHub
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# In Claude Code:
> "What are the top errors in the last 24 hours?"
> "Show me the stack trace for error abc123 and find the relevant PR"
> "Fix the bug and create a PR"
```

### Query your database

```
# Add a Postgres server
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
 --dsn "postgresql://readonly:pass@localhost:5432/analytics"

# In Claude Code:
> "What's our total revenue this month?"
> "Show me users who signed up in the last 7 days"
> "Find the top 10 products by order count"
```

### Team project setup

```
# Share servers with the team via .mcp.json
claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/
claude mcp add --transport http sentry --scope project https://mcp.sentry.dev/mcp

# Commit .mcp.json so everyone gets the same setup
git add .mcp.json && git commit -m "Add shared MCP server config"
```

## Claude Code as an MCP Server

Claude Code can also _act as_ an MCP server for other clients. This lets Claude Desktop or other MCP clients use Claude Code's tools (View, Edit, LS, etc.):

```
# Start Claude Code as an MCP server
claude mcp serve
```

Add to Claude Desktop's config:

```
{
 "mcpServers": {
 "claude-code": {
 "type": "stdio",
 "command": "claude",
 "args": ["mcp", "serve"],
 "env": {}
 }
 }
}
```

## Troubleshooting

Issue

Fix

Server not connecting

Run `/mcp` in Claude Code to check status and re-authenticate

"Connection closed" on Windows

Use `cmd /c` wrapper: `claude mcp add myserver -- cmd /c npx -y @package`

MCP output too large

Set `MAX_MCP_OUTPUT_TOKENS=50000` before running Claude Code

Server timeout

Set `MCP_TIMEOUT=10000` for slower servers (10s timeout)

OAuth fails

Clear auth: `/mcp` → select server → "Clear authentication". Re-auth.

Test Remote MCP Servers Before Adding to Claude Code

Use MCP Playground to verify HTTP/SSE servers work correctly

[Open MCP Playground →](/mcp-test-server)

## Related Content

-   [What Is the Model Context Protocol (MCP)?](/blog/what-is-model-context-protocol)
-   [How to Set Up MCP in Claude Desktop](/blog/how-to-setup-mcp-claude-desktop)
-   [Build Your First MCP Server with Python and FastMCP](/blog/build-mcp-server-python-fastmcp-tutorial)
-   [ChatGPT MCP Support: OpenAI Agents SDK Setup Guide](/blog/chatgpt-mcp-openai-agents-sdk-setup-guide)
-   [Awesome MCP Servers List](/blog/awesome-mcp-servers)

## Frequently Asked Questions

**What's the difference between Claude Desktop and Claude Code for MCP?**

Claude Desktop is a GUI app that supports stdio MCP servers via a JSON config file. Claude Code is a CLI tool that supports all 3 transports (HTTP, SSE, stdio), has scoping (local/project/user), OAuth support, and can also act as an MCP server itself. Claude Code is more flexible for developers.

**Can I share MCP server configs with my team?**

Yes. Use `--scope project` when adding servers. This creates a `.mcp.json` file at your project root that you can commit to git. Everyone who clones the repo gets the same MCP servers. Keep secrets in environment variables, not in the file.

**How many MCP servers should I add?**

Start with 3–5. Each server adds 500–2,000 tokens to context. Claude Code has MCP Tool Search that auto-activates when tool definitions exceed 10% of context, loading tools on-demand instead of all at once. But fewer servers = faster responses.

**Can I import my Claude Desktop MCP servers into Claude Code?**

Yes. Run `claude mcp add-from-claude-desktop` and select which servers to import. Works on macOS and WSL.

---

_Canonical page: https://mcpplaygroundonline.com/blog/claude-code-mcp-setup-best-servers-guide — MCP Playground (mcpplaygroundonline.com), the free browser-based tool for testing MCP servers and building AI agents._