Claude Code MCP Servers: Complete Setup Guide (2026)

The Model Context Protocol (MCP) gives Claude Code direct access to external tools and data sources — databases, APIs, file systems, and more — without leaving your terminal. Instead of copying data between tools, you connect MCP servers that let Claude read, query, and act on external systems natively. The MCP Config Generator makes this setup fast by producing ready-to-use configuration files. This guide walks through a complete setup from scratch, including installing your first server, testing the connection, and fixing the most common issues.

What MCP Actually Does

MCP is a standardized protocol that connects AI assistants to external tools. Each MCP server exposes a set of tools (actions the AI can take) and resources (data the AI can read). When you configure an MCP server in Claude Code, the assistant gains new capabilities without any custom code on your side.

The architecture is straightforward:

Claude Code CLI → MCP Client (built-in) → MCP Server (your config) → External Service

For example, connecting the GitHub MCP server lets Claude create pull requests, read issues, and search repositories — all through natural conversation.

Installing Your First MCP Server

The GitHub MCP server is the best starting point. It requires only a personal access token and covers the most common developer workflow.

Step 1: Generate a GitHub Token

# Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
# Create a token with these permissions:
# - Repository access: All repositories (or select specific ones)
# - Permissions: Contents (read/write), Issues (read/write), Pull requests (read/write)

Step 2: Add the MCP Server Configuration

Create or edit ~/.claude/mcp-servers.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

You can generate this configuration instantly with the MCP Config Generator — select GitHub from the dropdown, paste your token, and copy the output.

Step 3: Restart Claude Code

# Exit any running session
# Start fresh
claude
# Verify the server loaded
/mcp

The /mcp command shows all connected servers and their status. You should see github listed as connected.

Step 4: Test the Connection

# Inside Claude Code, try:
"List my 5 most recent GitHub repositories"
# Expected: Claude calls the GitHub MCP server and returns your repo list

Adding Multiple Servers

Your mcp-servers.json file supports multiple servers simultaneously:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
      "env": {}
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Each server runs as a separate process. Claude Code manages their lifecycle automatically — starting them when needed and shutting them down when your session ends.

Project-Level vs Global Configuration

MCP servers can be configured at two levels:

Level File Location Scope
Global ~/.claude/mcp-servers.json Available in all projects
Project .claude/mcp-servers.json Available only in this project

Project-level configuration is useful when a server needs project-specific credentials or when you want to share MCP setup with your team via version control.

# Create project-level config
mkdir -p .claude
cat > .claude/mcp-servers.json << 'EOF'
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_TOKEN}"
      }
    }
  }
}
EOF

Debugging Common Issues

Server Shows “disconnected”

# Check if the npm package exists
npx -y @modelcontextprotocol/server-github --help
# If it fails, clear npm cache
npm cache clean --force

Authentication Errors

# Verify your token works outside Claude Code
curl -H "Authorization: token ghp_your_token" https://api.github.com/user
# Common fix: regenerate the token with correct scopes

Server Crashes on Startup

Check the Claude Code logs for the actual error:

# Logs are typically at:
cat ~/.claude/logs/mcp-*.log
# Common causes:
# 1. Missing Node.js (need v18+)
# 2. npm registry timeout
# 3. Invalid JSON in config file

Validate Your Configuration

# Check JSON syntax before restarting
python3 -m json.tool ~/.claude/mcp-servers.json

Try It Yourself

Generate a working MCP configuration in seconds with the MCP Config Generator. Select your server, enter credentials, and get a copy-paste config file — no manual JSON editing required.

What is MCP in Claude Code? MCP (Model Context Protocol) is a standardized protocol that connects Claude Code to external tools and data sources. It allows Claude to interact with databases, APIs, and services directly from your terminal session.
How many MCP servers can I run at once? There is no hard limit on simultaneous MCP servers. Most developers run 2-5 servers. Each server runs as a separate process, so resource usage scales linearly. Monitor memory if you add more than 10.
Do MCP servers work with Claude Code on all operating systems? Yes. MCP servers work on macOS, Linux, and Windows (via WSL or native). The configuration format is identical across platforms. File paths in server arguments should use your OS conventions.
Can I use MCP servers with the Claude API directly? MCP servers are designed for Claude Code (the CLI tool). The Claude API uses a different tool-use format. However, you can use the MCP SDK to build bridges between MCP servers and API-based applications.

Find the right skill → Browse 155+ skills in our Skill Finder.

Try it: Paste your error into our Error Diagnostic for an instant fix.