Set Up MCP on Claude Desktop: Config, Extensions, Errors (2026)

Set up an MCP server on Claude Desktop in three steps: add the server through an extension, a config file, or a connector, restart the application with a full quit, and verify the server’s tools appear. The Model Context Protocol (MCP) is the open standard Anthropic created in November 2024 for connecting AI assistants to external tools and data. Claude Desktop was the first application to support it.

Three installation methods exist. Desktop Extensions install servers in one click with no terminal and no JSON editing. Manual JSON configuration gives full control over commands, arguments, and environment variables. Custom Connectors connect to remote hosted servers through a UI. Each method serves a different server type and a different user profile.

The errors below come from real installs, not documentation. Every method has a specific failure mode, and this guide maps each error to its fix inline rather than in a separate troubleshooting section. The full Claude Desktop MCP capabilities profile is at what Claude Desktop supports and where its limits are.

What Do You Need Before Setting Up MCP on Claude Desktop?

Claude Desktop installed on macOS or Windows is the only universal prerequisite. Node.js is required for npx-based servers configured through JSON. A Pro plan ($20/month) is required for Custom Connectors.

Desktop Extensions bundle their own runtime. No additional software is needed. Manual JSON configuration requires Node.js (for npx-based servers) or Python (for uvx-based servers) installed and accessible from the system PATH. Verify with npx --version or uvx --version in the terminal before editing the config file. A missing runtime is the error that happens before anything else can.

How Do You Install MCP Servers Through Desktop Extensions?

Open Claude Desktop, navigate to Settings, then Extensions, then Browse Extensions. Click Install on any server. Restart Claude Desktop. The server activates automatically.

Desktop Extensions are .mcpb files (MCP Bundles) that package an entire MCP server with all dependencies into a single installable archive. No terminal. No JSON editing. No Node.js installation. Claude Desktop includes a built-in Node.js runtime that Desktop Extensions use automatically.

The install sequence:

Open Claude Desktop.
Click the “+” button at the bottom of the chat input.
Select “Extensions” to open the marketplace.
Browse the Anthropic-reviewed directory and click Install on the server you need.
Complete any configuration prompts (API keys, directory paths).
Quit Claude Desktop completely (Cmd+Q on macOS, system tray Quit on Windows).
Reopen Claude Desktop.

Private extensions distributed outside the official directory install through a separate path. Navigate to Settings, then Extensions, then Install Extension. Select the .mcpb file from your filesystem. Follow the configuration prompts.

Desktop Extensions store sensitive values (API keys, tokens) in the operating system’s secure storage: Keychain on macOS, Credential Manager on Windows. Extensions from the official directory update automatically. Enterprise and Team administrators control which extensions are available through allowlist and blocklist settings.

The earlier .dxt format (June 2025) was renamed to .mcpb in September 2025. Legacy .dxt files still install correctly. New extensions use .mcpb.

The error you hit: The extension installs but no tools appear. The cause is almost always the restart. Closing the window does not restart MCP servers. Claude Desktop reads the configuration once at process start. Quit the application completely and relaunch it.

How Do You Add MCP Servers Through the JSON Config File?

Open the config file, add a server entry under the “mcpServers” key, save the file, then fully quit and reopen Claude Desktop. This method gives full control over the server command, arguments, and environment variables. Use it for custom servers, private servers, or any server not published as a Desktop Extension.

Where Is the Config File?

The config file location depends on the operating system.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

A shortcut exists inside the app. Open Claude Desktop, navigate to Settings, then Developer, then Edit Config. This opens the file in the default text editor and creates it if it does not exist. The file starts as an empty JSON object: {}.

What Does a Server Entry Look Like?

Here is the config entry for the Filesystem server, the simplest MCP server to install and verify:

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

Four fields define the entry:

“filesystem” is the server name. You choose it. It becomes the label in the tool list. Use a descriptive name: “github,” “postgres,” “slack.”

“command” is the executable Claude Desktop runs to start the server. Use the full absolute path, not the short name. /usr/local/bin/npx on macOS. C:\Program Files\nodejs\npx.cmd on Windows. Claude Desktop launches server processes with a minimal PATH. Short names like npx or docker resolve in your terminal but fail in Claude Desktop’s launch environment. This is the single most common setup error.

“args” is the array of arguments passed to the command. The -y flag tells npx to auto-confirm the package install. The package name follows. The final argument is the directory the Filesystem server can access. Scope it to one project folder. A server pointed at your home directory can read SSH keys, environment files, and credentials stored anywhere in the tree.

“env” is an optional object for environment variables the server needs. Servers that require API tokens, database connection strings, or service credentials declare them here:

{
  "mcpServers": {
    "github": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Tokens in the env object sit in the config file as plain text. Protect the file. Anyone who can read the config can read the credentials.

How Do You Add Multiple Servers?

Add additional entries under the same “mcpServers” key. Each entry is a separate server:

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    },
    "github": {
      "command": "/usr/local/bin/docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Desktop launches all configured servers at startup. Each server runs as a separate child process. Each server’s tool definitions consume 500 to 2,000 tokens of context window space. Three to five servers is practical. Beyond that, tool definitions crowd the context window and degrade model performance.

Save the file after editing. Validate the JSON syntax before saving. A trailing comma after the last entry, a missing bracket, or an unescaped character breaks the entire config. Paste the file into a JSON validator (jsonlint.com or your editor’s built-in validator) before closing the editor.

How Do You Connect Remote Servers Through Custom Connectors?

Navigate to Settings, then Connectors, then Add Custom Connector. Paste the MCP server’s endpoint URL. Complete the OAuth flow. Save and start a new conversation.

Custom Connectors connect Claude Desktop to remote MCP servers using Streamable HTTP. The server runs on external infrastructure: a vendor’s hosted endpoint, a Cloudflare Worker, a company server with a public URL. No JSON config file editing is involved.

The setup:

Open Claude Desktop.
Navigate to Settings, then Connectors.
Click Add Custom Connector.
Paste the server’s MCP endpoint URL (e.g., https://mcp.example.com/mcp).
Complete the OAuth 2.1 authentication flow if the server requires it.
Save the connector.
Start a new conversation. The connector’s tools appear in the tool list.

Custom Connectors require a Claude Pro plan ($20/month) or higher. Free-tier users do not have access to this feature.

One architectural detail matters: Custom Connector traffic routes through Anthropic’s cloud infrastructure, not directly from your machine to the server. The remote server must be reachable from Anthropic’s public IP ranges. A server behind a corporate VPN with no public ingress will not connect. Test the URL’s reachability from outside your network before debugging the connector configuration.

How Do You Verify That MCP Servers Are Running?

Open a new chat window. Look at the bottom of the input area for a hammer icon with a number. The number is the total tool count across all connected servers. Click the icon to see the tool list.

The hammer icon appears only when at least one server is connected and has registered its tools. No hammer icon means no server connected successfully. Check the error fixes in the next section.

A second verification method: ask Claude a question that requires the server. With the Filesystem server connected, type “list the files in my Documents folder.” Claude calls the list_directory tool, receives the directory contents, and responds with the file list. A successful tool call confirms the server is running, the tools are registered, and Claude can access them.

The config root key is “mcpServers.” Other clients use different root keys: Cursor uses the same key, VS Code uses “servers.” A mismatch between the key and the client causes silent failure with no error message.

How Do You Fix the Most Common MCP Setup Errors?

Six errors account for the majority of first-install failures on Claude Desktop. Each one has a specific cause and a specific fix.

“command not found” or Server Does Not Start

The command path is not absolute. Claude Desktop launches server processes with a minimal PATH that does not include standard tool directories. The config entry "command": "npx" resolves in your terminal but fails in Claude Desktop’s environment.

Fix: Replace the short command name with the full absolute path. Find it with which npx (macOS/Linux) or where npx (Windows). Replace "npx" with "/usr/local/bin/npx" on macOS or "C:\\Program Files\\nodejs\\npx.cmd" on Windows.

Server Starts but No Tools Appear After Restart

The application was not fully quit. Closing the Claude Desktop window does not terminate the process or reload the config file. The config is read once at process start. A window close followed by a window open reuses the existing process with the old config.

Fix: Quit completely. On macOS: Cmd+Q. On Windows: right-click the system tray icon and select Quit. Then relaunch. The hammer icon with a tool count confirms the server loaded.

JSON Syntax Errors Break the Config File

A trailing comma, a missing bracket, or an unescaped backslash in the config file prevents all servers from loading. Claude Desktop fails silently. No error dialog appears. The hammer icon simply does not show up.

Fix: Paste the config file into a JSON validator before saving. Common mistakes: a comma after the last server entry (JSON does not allow trailing commas), a missing closing brace, or Windows file paths with single backslashes instead of double (\\).

npx Fails on Windows

Windows requires the cmd /c wrapper for npx commands. The npx binary on Windows is npx.cmd, and Claude Desktop’s process launcher does not handle .cmd extensions correctly without the wrapper.

Fix: Change the command to "cmd" and prepend "/c" and "npx" to the args array:

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

Runtime Is Missing (Node.js or Python)

The server package requires a runtime that is not installed. npx-based servers require Node.js. uvx-based servers require Python with uv installed. The error message is “command not found” or a silent failure depending on the operating system.

Fix: Verify the runtime before editing the config. Run npx --version in the terminal. A version number means Node.js is installed and npx is available. No output or “command not found” means Node.js is not installed or not in the PATH. Install Node.js from nodejs.org. On Windows, verify that Node.js is installed natively, not inside WSL. A runtime installed inside WSL is not visible to Claude Desktop running on Windows.

Server Connects but Tool Calls Fail

The API token is missing, expired, or incorrectly scoped. The server registers its tools at startup (the hammer icon shows a count), but tool calls return errors because the server cannot authenticate with the external service.

Fix: Check the “env” object in the server’s config entry. Verify the token value is current. Verify the token has the required scopes. A GitHub server that creates issues needs a token scoped to repo. A GitHub server that only reads public repos needs public_repo. A Postgres server that only runs SELECT queries needs a read-only database role. Restart Claude Desktop after updating any environment variable.

Which Server Is the Best First MCP Install on Claude Desktop?

The Filesystem server is the best first install. It needs no API key, no external service, no authentication. It runs locally, starts instantly, and provides immediate verification. One question confirms it works: “list the files in my Documents folder.”

Here is the config entry:

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

Replace /Users/you/Documents/projects with the specific project directory you want the server to access. Scope it narrow. Do not point it at your home directory.

The Filesystem server is the best first install because it needs no authentication, no API key, and no external service. Verifying it takes one question: “list the files in my Documents folder.” After the Filesystem server is working, add a second server with authentication (GitHub or Slack) to learn the env variable flow. The full server directory with auth requirements per category is at which MCP servers are available. The full Filesystem server profile is at Filesystem MCP server guide.

Claude Desktop MCP Setup Questions

Do You Need Node.js to Use MCP on Claude Desktop?

Not for Desktop Extensions. Claude Desktop includes a built-in Node.js runtime that extensions use automatically. Manual JSON configuration with npx-based servers requires Node.js installed on your machine. Python-based servers (uvx) require Python. Docker-based servers require Docker Desktop.

Can You Use MCP on the Free Plan?

Partially. The free plan includes pre-built app connectors for services like Notion and Slack. Local MCP servers through JSON config and Desktop Extensions, and Custom Connectors for remote servers, require Claude Pro ($20/month) or higher.

Does Closing the Window Restart MCP Servers?

No. Closing the Claude Desktop window does not terminate the application process or reload the config file. MCP servers continue running (or not running) in their current state. Quit completely with Cmd+Q on macOS or system tray Quit on Windows, then relaunch. The restart requirement catches every first-time user. Claude Desktop reads the configuration once at process start. Editing the file while the app is open changes nothing until the next full launch.

Where Are MCP Server Logs on Claude Desktop?

Open Claude Desktop, navigate to Settings, then Developer. The Developer panel shows server connection status and error logs. Desktop Extension logs appear in Settings, then Extensions, then the individual extension’s detail panel. For deeper debugging, the MCP Inspector tool connects to any MCP server and displays raw tool definitions, request/response pairs, and protocol errors.

How Do You Set Up MCP Servers on Claude Desktop?