How to Configure Multiple MCP Servers in Claude Desktop

You can configure as many MCP servers as you want in Claude Desktop by adding multiple entries under the mcpServers key in your claude_desktop_config.json file. Each server gets a unique name, runs as an independent process, and makes its tools available to Claude simultaneously. This guide walks through the configuration structure, shows real multi-server examples, and covers the performance and conflict issues you may encounter.

For the foundational setup guide, see How to Connect MCP Servers to Claude Desktop and Claude Code.

The Configuration File Structure

Claude Desktop reads its MCP server configuration from a single JSON file. Every server is defined as a named entry under the mcpServers object:

{
  "mcpServers": {
    "server-name-1": {
      "command": "npx",
      "args": ["-y", "package-name-1"],
      "env": {}
    },
    "server-name-2": {
      "command": "npx",
      "args": ["-y", "package-name-2"],
      "env": {}
    },
    "server-name-3": {
      "command": "uvx",
      "args": ["package-name-3"],
      "env": {}
    }
  }
}

Configuration File Locations

If the file does not exist, create it with the structure shown above.

---

Step-by-Step: Adding Multiple Servers

Step 1: Open the Configuration File

On macOS, open the file in your preferred editor. You can access it through Claude Desktop's menu under Settings, or open it directly:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Add Your Server Entries

Each server entry needs three things:

Step 3: Example -- Three-Server Configuration

Here is a practical configuration with three commonly used servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/alex/projects",
        "/Users/alex/documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxxxxxxxxxx"
      }
    }
  }
}

This gives Claude three capabilities simultaneously: local file management, GitHub access, and web search.

Step 4: Example -- Five-Server Power Configuration

For developers who want a comprehensive setup:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/alex/projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_xxxxxxxxxxxx"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Step 5: Restart Claude Desktop

After saving the configuration file, you must fully restart Claude Desktop:

• macOS: Press Cmd+Q to quit (not just close the window), then reopen
• Windows: Right-click the system tray icon and choose Quit, then reopen
• Linux: Close the application completely and relaunch

Claude only reads the configuration file at startup. Closing the window without quitting does not restart the application on macOS.

Step 6: Verify All Servers Connected

After restarting, look for the hammer icon in Claude's input area. Click it to see the list of available tools. Each connected server should have its tools listed. If a server is missing, check the troubleshooting section below.

---

Naming Your Servers

The server name (the key in the mcpServers object) is important because it appears in logs and can affect how Claude references tools. Follow these guidelines:

You can have multiple instances of the same server type. For example, two PostgreSQL servers pointing at different databases:

{
  "mcpServers": {
    "postgres-analytics": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/analytics"
      }
    },
    "postgres-production": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@prod-host:5432/app"
      }
    }
  }
}

---

Handling Tool Name Conflicts

When running multiple servers, it is possible for two servers to expose tools with the same name. For example, two different servers might both expose a search tool.

How Claude Desktop Handles Conflicts

Claude Desktop prefixes tool names with the server name internally, so conflicts are rare in practice. However, Claude (the model) sees all tool descriptions and may choose the wrong one if descriptions are similar.

Resolution Strategies

---

Performance and Resource Management

Each MCP server runs as a separate process on your machine. Here is what to expect:

Memory Usage

Startup Time

Each server adds 1-3 seconds to Claude Desktop's startup time. With 10+ servers, startup may take 15-30 seconds before all tools are available.

Tips for Better Performance

• Use npx with the -y flag to auto-confirm installs and avoid interactive prompts
• Keep Node.js updated to version 18 or later for optimal performance
• Close servers you do not need by removing or commenting out entries in the config
• Monitor with Activity Monitor (macOS) or Task Manager (Windows) to see per-server resource usage

---

Mixing Local and Remote Servers

You can combine local (stdio) and remote (SSE/Streamable HTTP) servers in the same configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/alex/projects"]
    },
    "remote-api": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your_token_here"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Remote servers use the url field instead of command and args. They connect over HTTP and do not start a local process, which saves system resources.

For a deeper dive on local vs remote architecture, see Local vs Remote MCP Servers.

---

Debugging Connection Issues

When one or more servers fail to connect, use these steps to diagnose the problem:

Check the Developer Logs

On macOS, Claude Desktop writes logs to:

ls ~/Library/Logs/Claude/

Open the most recent log file and search for error messages related to your server names.

Common Multi-Server Errors

Validate Your JSON

A common mistake is a missing comma between server entries or a trailing comma after the last entry. Use a JSON validator to check syntax:

python3 -c "import json; json.load(open('claude_desktop_config.json'))"

If the command exits without output, your JSON is valid. If it prints an error, it will tell you the line number of the problem.

Test Servers Individually

If a specific server is not connecting, test it in isolation. Create a temporary config with only that server, restart Claude Desktop, and see if it connects. This isolates whether the issue is the server itself or a conflict with other servers.

---

Organizing Configurations for Different Workflows

You may want different server combinations for different tasks. While Claude Desktop does not support profiles natively, you can manage this with simple file swapping:

Manual Profile Switching

Create separate config files for different workflows:

# Save your current config
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/claude-configs/development.json

# Switch to a data analysis config
cp ~/claude-configs/data-analysis.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Then restart Claude Desktop to load the new configuration.

Recommended Profiles

---

Frequently Asked Questions

Is there a maximum number of servers I can configure?

There is no hard limit imposed by Claude Desktop. The practical limit depends on your system's available memory and CPU. Most users run 3-8 servers comfortably. Running 15+ servers is possible on systems with 16 GB or more of RAM.

Do all servers start when Claude Desktop launches?

Yes. Claude Desktop starts all configured servers at launch. There is no way to selectively enable or disable servers without editing the config file and restarting.

Can two servers share environment variables?

No. Each server has its own isolated env object. If two servers need the same API key, you must include it in both entries.

What happens if a server crashes during a conversation?

Claude loses access to that server's tools for the rest of the session. Other servers continue working normally. Restart Claude Desktop to reconnect the crashed server.

What to Read Next

• How to Connect MCP Servers to Claude Desktop -- Complete setup guide (parent pillar)
• Best MCP Servers for Claude Desktop -- Our top 15 server recommendations
• Cursor MCP Troubleshooting -- Debugging guide (many tips apply to Claude Desktop too)
• Local vs Remote MCP Servers -- Understanding transport options
• Browse All MCP Servers -- Find servers for your specific needs