Installing MCP Servers in Claude Code

From theory to practice

The previous sections covered what MCP servers do. Now: getting them running.

Claude Code offers two approaches. The CLI handles quick, one-off additions. Configuration files handle persistent, shareable setups. Both write to the same underlying configuration, so pick whichever fits the moment.

The claude mcp add command

The basic pattern differs by transport type.

For remote HTTP servers:

claude mcp add --transport http <name> <url>

For local stdio servers:

claude mcp add <name> -- <command> [args...]

The -- (double dash) separates Claude Code's options from the command that launches the server. Everything after -- gets passed to the subprocess.

Adding HTTP servers

HTTP is the recommended transport for remote servers. Most managed MCP services expose HTTP endpoints.

# Basic HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With authentication header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer ${GITHUB_TOKEN}"

# SSE transport (deprecated, use HTTP when available)
claude mcp add --transport sse asana https://mcp.asana.com/sse

The --header option adds HTTP headers for authentication. Environment variables expand at configuration time, so ${GITHUB_TOKEN} reads from your current shell environment.

Adding stdio servers

Stdio servers run as local subprocesses. Claude Code spawns the process and communicates via stdin/stdout.

# Filesystem server with specific directory access
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# GitHub server with environment variable
claude mcp add --env GITHUB_TOKEN=$GITHUB_TOKEN github \
  -- npx -y @modelcontextprotocol/server-github

# Memory server for persistent context
claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

The add-json command

Complex configurations are easier to express as JSON. The add-json command accepts a JSON object directly:

claude mcp add-json database '{"command":"npx","args":["-y","@bytebase/dbhub","--dsn","postgresql://localhost:5432/dev"],"env":{"DEBUG":"true"}}'

claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

This sidesteps shell quoting issues and makes multi-part configurations readable.

Management commands

After adding servers:

Inside Claude Code, the /mcp command shows server status and handles OAuth authentication for servers that require it.

Configuration file locations

Every claude mcp add writes to a configuration file. Which file depends on the scope.

User configuration: ~/.claude.json

User-scoped configurations live in your home directory. These servers are available across all projects.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/dev/.claude/memory.jsonl"
      }
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Project configuration: .mcp.json

Project-scoped configurations live in the project root. These files are meant for version control—share them with your team.

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

When Claude Code encounters a .mcp.json file, it prompts for approval before loading project-scoped servers. This prevents untrusted repositories from automatically connecting to MCP servers.

Managed configuration

Enterprises can deploy a managed-mcp.json file that takes precedence over user configurations.

Locations by platform:

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

Managed configurations can include allowlists and denylists to control which servers users can add.

Configuration file format

The schema is identical regardless of which file contains it. Transport type is inferred from the fields present.

Stdio server configuration

A server with a command field is a stdio server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

HTTP server configuration

A server with a url field is an HTTP server:

{
  "mcpServers": {
    "remote-api": {
      "type": "http",
      "url": "https://mcp.example.com/api",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

The type field is optional if url is present—Claude Code defaults to HTTP.

Environment variable expansion

Configuration files support environment variable expansion. This keeps secrets out of version control while allowing shared configurations.

Syntax options:

Supported locations:

• command — Server executable path
• args — Command-line arguments
• env — Environment variables passed to server
• url — HTTP server endpoint
• headers — HTTP header values

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost:5432/dev}"
      }
    }
  }
}

Team members set DATABASE_URL in their local environment. The configuration file contains no secrets.

Scope options

The --scope flag controls where configurations are stored and who can see them.

Local scope (default)

claude mcp add --scope local my-server -- npx -y @some/package

• Storage: ~/.claude.json under project-specific section
• Visibility: Only you, only in current project
• Use case: Experimental servers, sensitive credentials, personal tools

Project scope

claude mcp add --scope project shared-api --transport http https://api.example.com/mcp

• Storage: .mcp.json in project root
• Visibility: Anyone with repository access
• Use case: Team-shared services, project-specific integrations

User scope

claude mcp add --scope user my-utility --transport http https://util.example.com/mcp

• Storage: ~/.claude.json global section
• Visibility: You, across all projects
• Use case: Personal utilities you want everywhere

Scope precedence

When servers with the same name exist at multiple scopes, local overrides project, and project overrides user:

1. Local (highest priority)
2. Project
3. User (lowest priority)

This lets you override team configurations for testing without touching shared files.

Windows-specific considerations

Windows handles stdio servers differently. The short version: npx needs a wrapper.

The cmd /c wrapper

On native Windows (not WSL), wrap npx commands with cmd /c:

claude mcp add filesystem -- cmd /c npx -y @modelcontextprotocol/server-filesystem D:/projects

In configuration files:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]
    }
  }
}

Without the wrapper, Claude Code reports "Connection closed" errors. Debugging this without knowing about the wrapper requirement is frustrating.

Alternative: full path to npx

Instead of the wrapper, specify the full path to npx:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]
    }
  }
}

Path format

Use forward slashes in paths, even on Windows:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/projects"]

Forward slashes work reliably. Backslashes require escaping (\\) and are error-prone.

Verifying installation

After adding servers, verify they work.

From the command line:

claude mcp list
claude mcp get filesystem

Inside Claude Code: The /mcp command shows loaded servers and their available tools. This is also where OAuth authentication happens for servers that require it.

Diagnostics: The /doctor command includes MCP configuration checks and highlights errors.

Transport selection summary

HTTP is the standard for remote servers. Stdio remains necessary for servers needing local system access. SSE is deprecated but still supported for compatibility.

The next section covers ongoing configuration management: authentication, permissions, and coordinating multiple servers.