How to Connect MCP Servers to Claude Desktop & Claude Code

Claude Desktop and Claude Code are the primary MCP clients built by Anthropic. Claude Desktop is a GUI application that supports MCP servers through a JSON configuration file, while Claude Code is a terminal-based coding assistant with command-line MCP management. Both give Claude the ability to use tools, read resources, and execute actions through connected MCP servers.

This guide covers everything you need to connect MCP servers to both clients: configuration syntax, environment variables, remote servers, troubleshooting, and advanced usage patterns.

Claude Desktop: Configuration Guide

Step 1: Find the Configuration File

The claude_desktop_config.json file tells Claude Desktop which MCP servers to connect to. Its location depends on your operating system:

If the file does not exist, create it. Start with an empty JSON object:

{}

You can quickly open the file location from Claude Desktop by going to Settings > Developer > Edit Config.

Step 2: Add a Local MCP Server

Local MCP servers run as child processes on your machine using stdio transport. Claude Desktop starts them automatically when it launches.

Python Server (using uv)

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/you/projects/mcp-weather-server",
        "run",
        "server.py"
      ]
    }
  }
}

TypeScript Server (using npx with tsx)

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": [
        "tsx",
        "/Users/you/projects/mcp-notes-server/src/index.ts"
      ]
    }
  }
}

Compiled TypeScript Server (using node)

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": [
        "/Users/you/projects/mcp-notes-server/dist/index.js"
      ]
    }
  }
}

Published npm Package (using npx)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents"
      ]
    }
  }
}

The -y flag tells npx to automatically confirm package installation without prompting.

Go Binary

{
  "mcpServers": {
    "calculator": {
      "command": "/usr/local/bin/mcp-calculator"
    }
  }
}

Step 3: Add Environment Variables

Many MCP servers need API keys or configuration values. Use the env field:

{
  "mcpServers": {
    "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"
      }
    }
  }
}

Environment variables set in the env field are only available to that specific server process. They are not shared between servers.

Step 4: Connect a Remote MCP Server

For servers running on a remote host (using SSE or Streamable HTTP transport):

{
  "mcpServers": {
    "remote-analytics": {
      "url": "https://mcp-analytics.example.com/sse"
    }
  }
}

With authentication headers:

{
  "mcpServers": {
    "remote-analytics": {
      "url": "https://mcp-analytics.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-access-token"
      }
    }
  }
}

Step 5: Restart and Verify

After saving your configuration:

1. Fully quit Claude Desktop (Cmd+Q on macOS, not just close the window)
2. Reopen Claude Desktop
3. Look for the hammer icon in the message input area
4. Click the hammer to see the list of available tools from all connected servers

If the hammer icon does not appear, or your tools are missing, see the troubleshooting section below.

Multiple Servers Configuration Example

Here is a complete example with multiple servers of different types:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents",
        "/Users/you/Projects"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    },
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/you/mcp-servers/weather",
        "run",
        "server.py"
      ]
    },
    "company-api": {
      "url": "https://mcp.company.com/sse",
      "headers": {
        "Authorization": "Bearer company-token"
      }
    }
  }
}

Claude Code: MCP Configuration

Claude Code is Anthropic's terminal-based AI coding assistant. It supports MCP through both a CLI command and a configuration file.

Adding Servers with the CLI

The claude mcp add command is the simplest way to add MCP servers:

# Add a local stdio server
claude mcp add weather -- uv --directory /path/to/server run server.py

# Add an npm package server
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# Add a remote SSE server
claude mcp add analytics --url https://mcp.example.com/sse

Managing Servers

# List configured servers
claude mcp list

# Remove a server
claude mcp remove weather

# Get details about a server
claude mcp get weather

Project-Scoped Configuration

Claude Code supports project-level MCP configuration through .claude/mcp.json in your project root:

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://localhost:5432/myproject"
      }
    },
    "project-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./docs"
      ]
    }
  }
}

This file can be committed to version control (excluding secrets) so all team members have the same MCP server setup. For secrets, use environment variables that each developer sets locally:

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

Claude Code vs Claude Desktop: Key Differences

Using MCP Tools in Conversations

Once your servers are connected, Claude can use their tools naturally in conversation. You do not need special syntax -- just ask Claude to do things that your tools enable.

Examples

With a weather server connected:

"What are the current weather alerts in Texas?"

Claude will recognize this requires the get_alerts tool and call it automatically.

With a GitHub server connected:

"Create an issue in my repo called 'Fix login bug' with a description of the authentication timeout problem."

Claude will use the GitHub server's create_issue tool with the appropriate parameters.

How Claude Decides Which Tool to Use

When multiple servers are connected, Claude uses the tool names, descriptions, and input schemas to select the right tool. This is why good tool descriptions are critical -- see our guide on Creating Custom Tools & Resources.

Claude follows this process:

1. Analyzes the user's request
2. Reviews available tools from all connected servers
3. Selects the most appropriate tool(s)
4. Constructs the arguments based on the input schema
5. Calls the tool and processes the response
6. Presents the result to the user in natural language

Tool Approval

By default, Claude Desktop asks for user approval before calling MCP tools. This is a safety measure that lets you verify the tool call parameters before execution. You can review:

• Which tool is being called
• What arguments are being passed
• Which server provides the tool

This approval step is especially important for tools with side effects (writing files, sending messages, making API calls).

Troubleshooting

Server Not Appearing in Claude Desktop

Step 1: Validate your JSON

# Check for syntax errors
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: Verify the command works

Run exactly what Claude Desktop would run:

# For a Python server
uv --directory /path/to/server run server.py

# For an npm server
npx -y @modelcontextprotocol/server-github

If the command fails or hangs, fix that before configuring Claude Desktop.

Step 3: Check the logs

Claude Desktop logs MCP connection details:

• macOS: ~/Library/Logs/Claude/
• Look for the newest log file
• Search for "MCP" or your server name

Common log errors:

MCP server "weather" failed to start: spawn uv ENOENT
→ Fix: uv is not in Claude Desktop's PATH. Use the full path: /Users/you/.cargo/bin/uv

MCP server "notes" failed to start: ENOENT
→ Fix: The path in args does not exist. Use absolute paths.

MCP server "db" exited with code 1
→ Fix: The server crashed at startup. Run it manually to see the error.

Step 4: Check for common path issues

Tools Show Up But Fail When Called

Check environment variables: The server may need API keys that are not configured:

{
  "myserver": {
    "command": "...",
    "env": {
      "API_KEY": "required-key-here"
    }
  }
}

Check network access: Tools that make HTTP requests need network access. Corporate firewalls or VPNs can block requests.

Check file permissions: Tools that read/write files need appropriate filesystem permissions.

Server Disconnects During Conversation

Common causes:

• Server crashed due to an unhandled exception
• Server ran out of memory
• Server's stdout was corrupted (something printed to stdout)
• Network timeout for remote servers

Solution: Improve error handling in your server:

@mcp.tool()
async def my_tool(input: str) -> str:
    try:
        return await do_work(input)
    except Exception as e:
        # Return error as text, do not crash
        return f"Error: {str(e)}"

Advanced Configuration Patterns

Development vs Production Servers

Maintain separate configurations for development and production:

{
  "mcpServers": {
    "api-dev": {
      "command": "uv",
      "args": ["--directory", "/path/to/server", "run", "server.py"],
      "env": {
        "API_BASE_URL": "http://localhost:8000",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

When ready for production, swap to the remote URL:

{
  "mcpServers": {
    "api-prod": {
      "url": "https://mcp.production.com/sse",
      "headers": {
        "Authorization": "Bearer prod-token"
      }
    }
  }
}

Server Groups for Different Workflows

Organize servers by workflow. While you cannot conditionally load servers, you can comment out unused ones:

{
  "mcpServers": {
    "github": { "...": "always active" },
    "filesystem": { "...": "always active" },
    "postgres-dev": { "...": "active during dev" }
  }
}

What to Read Next

• Understand what MCP servers are: What Is an MCP Server?
• Use MCP in other IDEs: MCP in Cursor, VS Code & Other IDEs
• Build your own server: How to Build Your First MCP Server in Python
• Understand tools, resources, and prompts: MCP Core Building Blocks
• Browse available servers: MCP Server Directory

Summary

Connecting MCP servers to Claude Desktop and Claude Code is a straightforward configuration process. Claude Desktop uses claude_desktop_config.json with server entries specifying either a local command or a remote URL. Claude Code offers both CLI commands (claude mcp add) and project-scoped configuration files (.claude/mcp.json).

The key principles: use absolute paths for local servers, set environment variables in the config for API keys, restart Claude completely after configuration changes, and check the developer logs when something is not working. Once configured, Claude can seamlessly use all the tools and resources your MCP servers provide.