How to Set Up MCP Servers with Claude Code

The Model Context Protocol (MCP) extends Claude Code's capabilities by connecting it to external tools, databases, and services. This guide covers everything you need to configure MCP servers and unlock powerful integrations for your development workflow.

What is MCP?

MCP (Model Context Protocol) is an open standard created by Anthropic that provides a standardized way for AI applications to interact with external systems. Think of MCP like USB-C for AI - just as USB-C provides a universal connector for devices, MCP provides a universal protocol for AI-tool integrations.

With MCP servers configured, you can ask Claude Code to:

• Query databases directly and analyze results
• Manage GitHub issues, pull requests, and repositories
• Read and write files outside your current project
• Access Slack messages and channels
• Integrate with APIs like Stripe, Notion, and Sentry
• Run browser automation with Puppeteer

Prerequisites

Before configuring MCP servers, ensure you have:

• Claude Code installed (see our installation guide)
• Node.js 18+ for npm-based MCP servers (run node --version to check)
• Network access for remote MCP servers
• Credentials for any services you want to connect

Understanding MCP Configuration Scopes

Claude Code supports three configuration scopes for MCP servers:

Choose the appropriate scope based on whether the configuration contains secrets and whether it should be shared with your team.

Adding MCP Servers via CLI

The claude mcp add command is the primary way to configure MCP servers.

Basic Syntax

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

All options must come before the server name, and -- separates the server name from the command.

Adding an HTTP Server (Remote APIs)

For cloud-hosted MCP servers, use the HTTP transport:

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

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

# With a specific scope
claude mcp add --transport http github --scope user https://api.githubcopilot.com/mcp/

Adding a Stdio Server (Local Process)

For locally-run MCP servers, use the stdio transport:

# Filesystem access server
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# With environment variables
claude mcp add --transport stdio --env GITHUB_TOKEN=your_token github \
  -- npx -y @modelcontextprotocol/server-github

# PostgreSQL database server
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres \
  postgresql://user:password@localhost:5432/mydb

Managing MCP Servers

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get filesystem

# Remove a server
claude mcp remove filesystem

# Check status within Claude Code
/mcp

Popular MCP Servers

Here are configurations for commonly used MCP servers:

Filesystem Server

Gives Claude Code access to read and write files outside your current project:

claude mcp add --transport stdio filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem /Users/yourname/Documents

GitHub Server

Enables repository management, issue tracking, and pull request workflows:

# Using remote HTTP server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Or using local server with PAT
claude mcp add --transport stdio --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx github \
  -- npx -y @modelcontextprotocol/server-github

PostgreSQL Server

Query and analyze your PostgreSQL databases:

claude mcp add --transport stdio postgres \
  -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://readonly:password@localhost:5432/analytics"

For security, use a read-only database user when possible.

SQLite Server

Work with SQLite databases:

claude mcp add --transport stdio sqlite \
  -- npx -y @modelcontextprotocol/server-sqlite /path/to/database.db

Slack Server

Access Slack channels and messages:

claude mcp add --transport stdio --env SLACK_BOT_TOKEN=xoxb-xxx --env SLACK_TEAM_ID=T0123 slack \
  -- npx -y @anthropics/mcp-server-slack

Puppeteer Server (Browser Automation)

Control a browser for testing and scraping:

# Install globally first (recommended)
npm install -g @anthropic/mcp-server-puppeteer

# Then add to Claude Code
claude mcp add --transport stdio puppeteer -- mcp-server-puppeteer

Sentry Server (Error Monitoring)

Monitor and analyze application errors:

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

After adding, run /mcp in Claude Code to complete authentication.

Configuration File Format

For complex configurations or team sharing, edit the configuration files directly.

Project Configuration (.mcp.json)

Create .mcp.json in your project root for team-shared servers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DB_CONNECTION_STRING}"],
      "env": {
        "DB_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.company.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Environment Variable Expansion

Configuration files support environment variable expansion:

• ${VAR} - Expand the environment variable
• ${VAR:-default} - Use a default value if not set

This keeps secrets out of your configuration files while allowing the structure to be version-controlled.

Platform-Specific Notes

macOS

Configuration works out of the box on macOS. Key file locations:

• User config: ~/.claude.json
• Managed config (admin): /Library/Application Support/ClaudeCode/managed-mcp.json

If using nvm for Node.js management, MCP servers may fail to find npx. Use full paths:

claude mcp add --transport stdio myserver \
  -- /Users/yourname/.nvm/versions/node/v20.0.0/bin/node \
  /Users/yourname/.nvm/versions/node/v20.0.0/bin/npx -y @some/mcp-server

Windows

Claude Code runs natively on Windows (no WSL required). Key considerations:

• User config: %USERPROFILE%\.claude.json
• Managed config (admin): C:\Program Files\ClaudeCode\managed-mcp.json

For stdio servers, wrap commands with cmd /c:

claude mcp add --transport stdio myserver -- cmd /c npx -y @some/mcp-server

Windows with WSL

If running Claude Code in WSL and MCP servers fail to connect:

1. Edit your .wslconfig file (in Windows at %USERPROFILE%\.wslconfig):

[wsl2]
networkingMode = mirrored

2. Restart WSL:

wsl --shutdown

This allows MCP servers bound to 127.0.0.1 to work correctly with WSL's virtual network interface.

Linux

Configuration follows standard Linux conventions:

• User config: ~/.claude.json
• Managed config (admin): /etc/claude-code/managed-mcp.json

Ensure npx is in your PATH or use absolute paths to Node.js binaries.

Troubleshooting

"spawn npx ENOENT" Error

Claude Code cannot find the npx executable. Solutions:

1. Use absolute paths to the Node.js binary:

claude mcp add --transport stdio myserver \
  -- /usr/local/bin/node /usr/local/bin/npx -y @some/mcp-server

2. Install packages globally instead of using npx:

npm install -g @modelcontextprotocol/server-filesystem
claude mcp add --transport stdio filesystem -- mcp-server-filesystem /path/to/dir

Server Transport Closed Unexpectedly

The MCP server is crashing during startup. Debug steps:

1. Run the server manually to see errors:

npx -y @modelcontextprotocol/server-postgres "your-connection-string"

2. Check Node.js version (requires 18+):

node --version

3. Verify connection strings and credentials are correct

Port Conflicts

Another process may be using the required port:

# Check what's using a port (macOS/Linux)
lsof -i :8080

# Kill the conflicting process
kill -9 <PID>

Large Output Warnings

MCP tools producing large outputs will show warnings at 10,000 tokens. Adjust limits:

# Increase maximum output (default: 25,000)
MAX_MCP_OUTPUT_TOKENS=50000 claude

Check Server Status

Within Claude Code, run:

/mcp

This shows all connected servers and their status. Servers with authentication requirements will prompt you to complete setup.

Environment Variables

Key environment variables for MCP configuration:

Example usage:

MCP_TIMEOUT=30000 MAX_MCP_OUTPUT_TOKENS=50000 claude

Security Best Practices

1. Use read-only database credentials when possible
2. Store secrets in environment variables, not config files
3. Limit filesystem access to specific directories
4. Review project .mcp.json files before approving team-shared servers
5. Use the local scope for sensitive personal credentials
6. Rotate API tokens regularly for connected services

Discovering More MCP Servers

The MCP ecosystem is growing rapidly. Find additional servers at:

• Official MCP Servers Repository
• Awesome MCP Servers - Community curated list
• MCP.so - MCP server directory
• Smithery.ai - MCP marketplace

Next Steps

• Read the official Claude Code MCP documentation
• Explore MCP server development if you want to build your own
• Learn about Claude Code configuration for other customization options