MCP Multi-Server Setup: Orchestrating Multiple Tools in 2026

Problem: One MCP Server Is Not Enough

You got the filesystem MCP server running. Now you want GitHub access, a Postgres connection, and web search — all in the same Claude session.

Most guides show a single server. Connecting several at once introduces name collisions, auth conflicts, and config sprawl that's hard to debug.

You'll learn:

• How to wire four MCP servers into a single claude_desktop_config.json
• How to resolve tool name conflicts across servers
• How to keep secrets out of config files using environment variables

Time: 25 min | Difficulty: Intermediate

Why Multi-Server Setups Break

Each MCP server exposes a list of tools. The client merges them into one flat namespace. When two servers both export a tool called search or read_file, the client picks one silently — often the wrong one.

Symptoms:

• Tool calls return unexpected results with no error
• Error: duplicate tool name in client logs (Claude Desktop 0.10+)
• One server's auth token being sent to a different server's endpoint

The fix is explicit server namespacing and a config structure that makes each server's scope obvious.

Solution

Step 1: Confirm Your MCP Client Version

Claude Desktop 0.10+ supports multi-server configs natively. Older versions only load the first server entry.

# macOS
defaults read com.anthropic.claude CFBundleShortVersionString

# Or check the About screen: Claude → About Claude

Expected: 0.10.0 or higher. If not, update at claude.ai/download before continuing.

Step 2: Locate and Back Up Your Config File

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Back it up before editing
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.backup.json

Step 3: Install the Four MCP Servers

Install each server as a local package. Pinning exact versions prevents silent breakage when a server updates its tool schema.

# Filesystem access
npm install -g @modelcontextprotocol/server-filesystem@0.6.2

# GitHub API (issues, PRs, repo search)
npm install -g @modelcontextprotocol/server-github@0.6.1

# PostgreSQL query runner
npm install -g @modelcontextprotocol/server-postgres@0.6.0

# Brave web search
npm install -g @modelcontextprotocol/server-brave-search@0.6.1

Verify each binary is on PATH:

which mcp-server-filesystem mcp-server-github mcp-server-postgres mcp-server-brave-search

Expected output:

/usr/local/bin/mcp-server-filesystem
/usr/local/bin/mcp-server-github
/usr/local/bin/mcp-server-postgres
/usr/local/bin/mcp-server-brave-search

Step 4: Store Secrets in Your Shell Environment

Never put API tokens directly in claude_desktop_config.json — it is plaintext and often synced to cloud backup.

# Add to ~/.zshrc or ~/.bashrc
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export BRAVE_API_KEY="BSA_xxxxxxxxxxxxxxxxxxxx"
export POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/mydb"

# Reload
source ~/.zshrc

Claude Desktop inherits environment variables from your shell login session on macOS. On Windows, set these via System Properties → Environment Variables.

Step 5: Write the Multi-Server Config

Open claude_desktop_config.json in your editor and replace its contents:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": [
        "--allowed-directories",
        "/Users/yourname/projects",
        "/Users/yourname/Documents"
      ]
    },
    "github": {
      "command": "mcp-server-github",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "postgres": {
      "command": "mcp-server-postgres",
      "env": {
        "POSTGRES_CONNECTION_STRING": "${POSTGRES_CONNECTION_STRING}"
      }
    },
    "brave-search": {
      "command": "mcp-server-brave-search",
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

Key decisions in this config:

• filesystem gets explicit --allowed-directories so it cannot read outside your project folders. Never pass / or ~ here.
• All three API-backed servers read secrets from environment variables via ${VAR_NAME} interpolation — not hardcoded strings.
• Server keys ("filesystem", "github", etc.) become the namespace prefix in logs and are shown in Claude's tool-use UI.

Step 6: Resolve Tool Name Conflicts

Check for overlapping tool names before restarting Claude Desktop:

# List tools from each server
mcp-server-filesystem --list-tools 2>/dev/null
mcp-server-github --list-tools 2>/dev/null
mcp-server-postgres --list-tools 2>/dev/null
mcp-server-brave-search --list-tools 2>/dev/null

Look for duplicates. Common collisions:

Claude Desktop 0.10+ namespaces tools automatically as serverKey__toolName (double underscore) in its internal routing. You do not need to rename tools manually — but you do need to reference them correctly when prompting:

# Explicit tool routing in a prompt
Use the github__search tool to find issues mentioning "rate limit",
then use brave-search__search to find recent blog posts on the same topic.

Step 7: Restart Claude Desktop and Verify

# macOS: quit fully (Cmd+Q, not just close window), then reopen
open -a "Claude"

In a new Claude conversation, ask:

List all MCP tools currently available to you, grouped by server.

You should see four groups — filesystem, github, postgres, brave-search — each with their tool list. If a server is missing, check Step 8.

Debugging Server Startup Failures

Enable verbose MCP logs:

# macOS — tail logs while Claude starts
tail -f ~/Library/Logs/Claude/mcp*.log

Common errors and fixes:

• spawn mcp-server-github ENOENT → Binary not on PATH. Run npm install -g again and confirm with which mcp-server-github.
• Error: GITHUB_PERSONAL_ACCESS_TOKEN not set → Shell env vars aren't inherited. On macOS, launch Claude from Terminal: open -a Claude so it picks up your shell environment.
• Error: permission denied /Users/yourname/projects → The --allowed-directories path doesn't exist or has restrictive permissions. Run ls -la on the path.
• PostgreSQL connection refused → Postgres isn't running locally. Start it with brew services start postgresql@16 or adjust the connection string to point at your remote host.

Verification

Ask Claude to perform a cross-server task:

1. Search GitHub for open issues in the 'anthropics/anthropic-sdk-python' repo 
   labelled 'bug' 
2. Save a summary of the top 3 issues to ~/projects/notes/mcp-bugs.md
3. Query my local postgres for any matching error codes in the errors table

You should see Claude orchestrate three tool calls in sequence — github__search_issues, filesystem__write_file, postgres__query — and return a consolidated result.

Caption: Claude Desktop showing three MCP servers active simultaneously, each tool call namespaced by server

Production Considerations

Limit filesystem scope aggressively. The more directories you allow, the more risk if a prompt injection in a file tricks Claude into exfiltrating data. Scope to the minimum you need per project.

Use read-only Postgres credentials. Create a dedicated mcp_readonly role with SELECT only. Never point MCP at your primary application database user.

Token permissions matter. For GitHub, create a fine-grained personal access token scoped to specific repos and Contents: Read-only. A leaked full-access token through a prompt injection is a real threat.

Restart Claude Desktop after config changes. The config is read once at startup. In-place edits have no effect until you fully quit and reopen.

What You Learned

• mcpServers keys in claude_desktop_config.json define server identity and become namespace prefixes in tool routing
• Secrets belong in shell environment variables, not in the config file
• Claude Desktop 0.10+ namespaces tools as serverKey__toolName to prevent silent collisions
• Filesystem and database servers need explicit permission scoping before production use

Limitation: Claude Desktop runs all MCP servers as local processes. For remote teams, each developer needs their own config. Server-side MCP (running servers as HTTP endpoints) is in beta as of early 2026 — watch the MCP spec repo for updates.

Tested on Claude Desktop 0.10.3, @modelcontextprotocol/server- 0.6.x, macOS Sequoia 15.3 and Ubuntu 24.04*