Last checked against Anthropic's Help Center, the Claude Code docs, modelcontextprotocol.io and GitHub issue reports on October 17, 2026.

MCP is how Claude connects to your other tools, such as your files, your project tracker or your database. Setup is usually quick. When it fails, though, the error messages can be cryptic. This guide covers setup for Claude Desktop and Claude Code in plain English, then walks through the fixes for the errors people report most.

What is MCP, in one paragraph

The Model Context Protocol (MCP) is "an open standard, created by Anthropic, for AI applications to connect to tools and data" (Custom connectors). An MCP server is a small program that gives Claude a set of tools, like "search files" or "create issue." A remote server lives on the internet at a URL. A local server runs on your own computer. In the Claude apps, connected MCP servers are called connectors.

Before you start: pick the easiest route

A connector from the directory (easiest). Click Customize in the left sidebar, open the Connectors tab, then the Discover tab to browse what's available (Browse the directory).
A desktop extension (easy). One-click local servers for Claude Desktop.
A config file or command (technical). For servers that have neither of the above.

Only connect servers you trust. Anthropic warns that malicious servers can hide instructions that try to make Claude do things you didn't ask for (Custom connectors).

Setup in Claude Desktop

Option A: Install a desktop extension

Open Settings > Extensions in Claude Desktop.
Click Browse extensions, choose an Anthropic-reviewed tool, and click Install.
Fill in any required settings, such as an API key.
The extension is now available in your conversations.

To install a .mcpb file someone sent you, go to Settings > Extensions > Advanced settings, find the Extension Developer section, and click Install Extension… (Local MCP servers on Claude Desktop). Claude Desktop has Node.js built in, so extensions don't need a separate install.

Option B: Add a remote server as a custom connector

On Pro or Max, go to Customize > Connectors, click + Add, then Add custom connector. Enter a name and the server's URL, review the sign-in settings, and click Add. On Team and Enterprise, an Owner adds it first in Organization settings > Connectors, then members click Connect. Free plans can add one custom connector (Custom connectors).

Option C: Edit the config file

Open Claude Desktop's settings from your computer's menu bar (not the settings inside the chat window) and go to the Developer tab.
Click Edit Config. This opens claude_desktop_config.json, found at ~/Library/Application Support/Claude/ on Mac and %APPDATA%\Claude\ on Windows.
Add your server under mcpServers, using the server's instructions. The official filesystem example looks like this:

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

Save, then completely quit Claude Desktop and reopen it.
To check it worked, click the + button in the chat box and select Connectors (MCP docs; Help Center).

Servers like this one need Node.js installed on your computer. Note that local servers from this file aren't available in Cowork or on claude.ai (Custom connectors).

Setup in Claude Code

Run these in your terminal, not inside a claude session (MCP quickstart).

Remote server:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Local server: everything after -- is the command that starts the server.

claude mcp add playwright -- npx -y @playwright/mcp@latest

Check it: run claude mcp list and look for ✔ Connected. Inside a session, /mcp shows status and handles browser sign-ins.

Reuse what you already set up: if you sign in with a claude.ai account, your claude.ai connectors appear in Claude Code automatically, and claude mcp add-from-claude-desktop imports servers from Claude Desktop (Mac and WSL only) (Claude Code MCP reference).

By default a server is saved for you in the current project only. Add --scope user to use it in all your projects.

Fix-it guide: the most common errors

Server doesn't show up in Claude Desktop

Fully quit and restart Claude Desktop.
Check the JSON for typos, such as a missing comma or bracket.
Use full (absolute) file paths, not relative ones.
Read the logs: ~/Library/Logs/Claude on Mac or %APPDATA%\Claude\logs on Windows. mcp.log covers connections, and mcp-server-NAME.log shows each server's errors.
Run the server's command in your terminal to see the real error (MCP docs).

"spawn npx ENOENT" or "env: node: No such file or directory"

This is one of the most reported problems, especially for people who use nvm to manage Node versions. Claude Desktop doesn't load your terminal's setup, so it can't find npx, or it picks up an old Node version. Workarounds confirmed by users in this GitHub issue:

Use the full path to node or npx in command.
Add a PATH entry under env that points to your Node bin folder.
Remove old Node versions (several users found Claude used the oldest one installed).

Windows: npx servers show "Failed to connect"

On native Windows, npx is a .cmd file that some setups can't launch directly. Users fixed it by wrapping the command in cmd /c, for example claude mcp add playwright -- cmd /c npx -y @playwright/mcp@latest (issue #4793; issue #68221). The same reports show the JSON form: "command": "cmd", "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]. This workaround comes from user reports, not the official docs.

"Failed to connect" or "Connection error" in Claude Code

Run claude mcp get <name> to see the error detail. For a remote server, test the URL with curl -I <url>: a 404 or 405 means the server is up, a 401 or 403 means you need to sign in, and no response means a URL or network problem. For a local server, run its command directly. If the command in claude mcp get doesn't match, you probably forgot the -- (MCP quickstart).

Connection timed out

The first npx run can be slow while it downloads. Raise the 30-second limit with MCP_TIMEOUT=60000 claude (MCP quickstart).

Connected, but no tools appear

Usually a missing API key or other setting. Add it with --env KEY=value or in the server's env field (MCP quickstart). In Claude Desktop, recheck the extension's settings and restart (Help Center).

Edits to .mcp.json are ignored

Claude Code reads .mcp.json when a session starts, so restart. The file must sit at your project root, not inside .claude/, with servers under mcpServers (Debug your configuration).

Custom connector can't reach your server

Claude connects to remote servers from Anthropic's cloud, not from your computer. A server behind a VPN or company firewall won't connect unless you allowlist Anthropic's IP addresses (Custom connectors).

"is Anthropic-hosted and doesn't support local OAuth"

For services like Microsoft 365, Gmail and Google Calendar, connect at claude.ai/customize/connectors instead. The connector then appears in Claude Code automatically (Claude Code MCP reference).

Free download: get our Claude Skills template pack, five ready-to-upload skills that work alongside your connectors.

Stuck on a connection? CNR Consulting can connect Claude to the tools your business already uses and make sure it works reliably. Book a quick chat.