Claude MCP Setup Guide (2026): Config, Servers & Fixes

Claude MCP connects Claude to files, databases, APIs, and business tools through the Model Context Protocol. In 2026, there are three practical setup paths: install a Claude Desktop extension, configure a local server in claude_desktop_config.json or add a remote connector that works across Claude clients.

This guide shows the current setup for Claude Desktop and Claude Code, includes copy-paste configuration examples, and gives you a troubleshooting sequence that starts with the real error instead of guesswork.

What is a Claude MCP server?

A Claude MCP server is a service that connects Claude to external data or tools through the Model Context Protocol (MCP). It can expose tools Claude may call, resources Claude may read, and reusable prompts, while the server’s permissions and credentials control what Claude can access or change.

Claude is the host application, and its MCP client connects to one or more local or remote servers. Each server talks to an underlying system (such as GitHub, a filesystem, a CRM or an internal API) and returns structured results.

Choose the right Claude MCP setup

Setup	Best for	Where it runs	How to add it
Desktop extension	The easiest local install	Your computer	Install an .mcpb package in Claude Desktop
Local stdio server	Files, scripts, private local tools	Your computer	Edit claude_desktop_config.json
Remote MCP connector	Cloud tools and cross-device access	Vendor or company infrastructure	Add a connector URL in Claude settings
Claude Code MCP	Developer workflows in a repository	Local process or remote endpoint	Use claude mcp add

Start with a Desktop extension or a trusted remote connector if one exists. Use manual JSON when you need a custom command, a private server or precise control over paths and environment variables.

What you need before setup

• The latest Claude Desktop for macOS or Windows.
• For Node-based local servers, the current Node.js LTS release and npm. Confirm both with node --version and npm --version.
• The exact installation instructions from the server publisher. Package names, commands, endpoints, and required variables differ by server.
• A narrowly scoped account or token. Begin with read-only access when possible.

Desktop extensions can bundle their own runtime, so Node.js is not required for every extension. Manual npx-based server configurations do require Node and npm to be available to Claude Desktop.

Set up a local MCP server in Claude Desktop

Option 1: install a Desktop extension

Claude Desktop extensions package a local MCP server as an .mcpb file and provide a guided installation flow. In Claude Desktop, open Settings → Extensions. Install from the directory or choose Advanced settings → Install Extension for a custom package. Follow the permission and configuration prompts.

This is the preferred route for non-technical users because it avoids hand-editing JSON and can store fields marked as sensitive in the operating system’s secure credential store.

Option 2: edit claude_desktop_config.json

For a manual local server, open Claude Desktop → Settings → Developer → Edit Config. The configuration file is normally located here:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

The official filesystem server is a useful first test because you can restrict it to specific folders. Replace the example paths with folders you are comfortable allowing the server to read and modify.

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

On Windows, use escaped backslashes in JSON:

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

Save the file and fully quit and restart Claude Desktop. Closing only the window is not enough on macOS. Open a new chat, click the + button, select Connectors, and open Manage connectors to inspect the server and its tools. Developer settings also show connection status and logs.

Add environment variables safely

Some local servers need an API key or token. Follow the publisher’s variable names exactly. A typical entry looks like this:

{
  "mcpServers": {
    "example": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "publisher-package-name"],
      "env": {
        "EXAMPLE_API_KEY": "replace-with-a-scoped-key"
      }
    }
  }
}

The Desktop JSON file stores these values as plain text. Restrict access to the file, never commit it to Git, and prefer an extension’s sensitive configuration fields or your organization’s secret-management approach for production credentials.

Add a remote MCP connector to Claude

A remote MCP server is hosted on the internet. In Claude, individual Pro and Max users can add supported custom connectors from Settings → Connectors; Team and Enterprise organizations may require an Owner or Primary Owner to add and approve the connector first. After configuration, enable it for a conversation from the + → Connectors menu.

Remote connectors work differently from local JSON servers. Claude connects to a remote server from Anthropic’s cloud infrastructure, including when you use Claude Desktop. The endpoint therefore must be reachable from Anthropic’s network. A service that exists only on localhost, behind a VPN or behind a restrictive firewall will not work as a remote connector unless the network is configured appropriately.

Use HTTPS and OAuth where supported. Review the scopes before authorizing, confirm whether the connector exposes write tools, and disconnect it from both Claude and the service’s security settings if access is no longer needed.

Set up MCP in Claude Code

Claude Code has its own MCP configuration. For a remote HTTP server:

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

For a local stdio server, put Claude’s options before the server name and use -- to separate them from the command that starts the server:

claude mcp add --transport stdio example -- npx -y publisher-package-name

Then verify the connection:

claude mcp list
claude mcp get example

Use --scope project only when the server configuration should be shared with a team through the repository. Never commit secrets to a project-level .mcp.json. Project servers require workspace trust and explicit approval before Claude Code connects to them.

Best MCP servers to start with in 2026

There is no universal “best” server. The safest shortlist starts with the official connector directory, the service vendor’s own documentation, and the smallest permission set that completes your task.

Server or connector	Good for	What to verify
Filesystem	Reading and organizing selected local folders	Exact allowlisted folders; write access
GitHub	Issues, pull requests, repositories, code workflows	Vendor-maintained server; repository and token scopes
Notion	Searching and updating workspace knowledge	Pages shared with the integration; write permissions
Google Drive	Finding and summarizing documents	Account, shared-drive, and document access
Slack	Searching channels and supporting team workflows	Channel visibility and any message-writing tools
Playwright	Browser testing and controlled web automation	Trusted publisher, allowed sites, and action scope
Generect MCP	Live B2B lead research and prospecting workflows	Workspace access, credit usage, and available actions

Browse reviewed remote connectors in the Anthropic Connectors Directory and discover server metadata in the official MCP Registry. A registry listing is not a security guarantee. Confirm the publisher, repository, latest release, authentication method, and requested scopes before installation.

If your workflow is sales prospecting, Generect MCP connects Claude to live lead discovery rather than a static CSV. Review the available tools and permissions before enabling actions.

How to test your Claude MCP setup

1. Validate the configuration. For manual Desktop setup, parse the file with a JSON validator. A trailing comma or mismatched bracket can stop every server from loading.
2. Run the launch command directly. Copy the exact command and args into a terminal. If the process crashes there, fix that error before debugging Claude.
3. Restart the host. Fully quit and reopen Claude Desktop after changing local server definitions.
4. Inspect the connector. Use + → Connectors → Manage connectors in Claude Desktop or claude mcp list and claude mcp get NAME in Claude Code.
5. Test a specific tool. Ask Claude to use a named tool for a harmless, read-only task. A generic prompt may not require a tool call.
6. Check logs. On macOS, inspect ~/Library/Logs/Claude. On Windows, inspect %APPDATA%\Claude\logs. mcp.log records general connection failures; server-specific files contain the process’s stderr.

For server development, use the official MCP Inspector to inspect capabilities and tool calls independently of Claude.

Claude MCP troubleshooting

Server does not appear

Confirm that you edited the correct file, validate the JSON, and fully restart Claude Desktop. Make every local script and allowed-folder path absolute. If npx, uv or another executable works in your terminal but not in Claude, find its absolute path with which on macOS/Linux or where on Windows and use that path as command.

Command not found or ENOENT

The executable, package or script cannot be found. Run the launch command manually, verify the package name against the publisher’s current documentation, and confirm that the runtime is installed. On Windows, a package’s instructions may require cmd /c; use it only when the server publisher or the observed error calls for it.

Server starts but tools are missing

Open the connector details and confirm the server actually advertises tools. Check the server-specific log for a startup exception. Then ask Claude to perform a task that clearly needs one named tool. In Claude Code, use /mcp inside a session or claude mcp get NAME from the terminal.

Authentication fails

Check the exact environment-variable name, token expiry, OAuth callback, and account permissions. Do not “fix” authentication by granting broad admin access. Revoke the credential, create a narrowly scoped replacement, and reconnect.

Remote connector works in a browser but not Claude

Remember that Anthropic’s cloud, not your laptop, connects to remote MCP endpoints. Verify public HTTPS reachability, the endpoint path, authentication, and firewall rules. Do not expose a private service to the internet without appropriate authentication and network controls.

STDIO server connects and then breaks

A stdio server must reserve stdout for MCP’s JSON-RPC messages. In Python, log through the standard logging module to stderr. In Node.js, use console.error() or a logger configured for stderr, not console.log().

Run multiple MCP servers without losing control

You can add multiple entries under mcpServers, but more is not always better. Every connected server adds tools and descriptions Claude must consider. Keep only the servers needed for the current workflow, disable unused connectors, and give each server a descriptive unique name.

Separate high-risk write tools from routine read-only tools where possible. For example, a read-only analytics connector should not share a broad production credential with a deployment server. This makes approvals easier to understand and credentials easier to rotate.

MCP security checklist

• Install servers only from a publisher you can verify.
• Read the source or security documentation for community servers.
• Start with read-only scopes and a test account.
• Restrict filesystem servers to the smallest necessary directories.
• Keep secrets out of repositories, screenshots, prompts, and shared config files.
• Review tool calls before approving changes to external systems.
• Treat content returned by connected systems as untrusted; it can contain prompt-injection attempts.
• Remove unused servers and revoke their OAuth grants or tokens.

An MCP server runs with the permissions you give it. Local stdio servers normally run as your operating-system user; remote connectors act through the account and scopes you authorize. MCP standardizes the connection; it does not replace access control or human review.

How to build your own MCP server

Use an official MCP SDK instead of copying an old tutorial snippet. The maintained quickstarts cover Python and TypeScript and show how to expose tools, resources, and prompts. For a local server, use stdio; for a remotely hosted service, use Streamable HTTP.

1. Define the narrow workflow and the minimum data it needs.
2. Choose the official Python or TypeScript server quickstart.
3. Add typed inputs, clear tool descriptions, validation, timeouts, and safe error handling.
4. Keep stdout clean for a stdio server and send logs to stderr.
5. Test with MCP Inspector before connecting Claude.
6. Use scoped credentials and explicit authorization for write operations.
7. For a remote service, implement HTTPS and the authentication model described in the current MCP and Claude connector documentation.

A custom server should fail safely. Validate every tool input, avoid arbitrary shell execution, enforce server-side permissions, and log enough context to audit actions without recording secrets.

Claude Desktop MCP config reference

A local server entry is a launch instruction. Claude Desktop starts the command as a child process, passes the values in args, and communicates with the server over standard input and output. Understanding each field makes most setup errors easy to diagnose.

Field	Meaning	Typical mistake
mcpServers	Top-level object containing local server definitions	Putting a server beside this key instead of inside it
Server name	Your unique label for the connection	Using duplicate or unclear names
command	Executable Claude Desktop launches	Using a command that is not in the app’s PATH
args	Ordered arguments passed to the executable	Wrong package name, relative path or Windows escaping
env	Environment variables given to that server process	Wrong variable name or a token with insufficient scope

For example, Claude interprets "command": "npx" and "args": ["-y", "package-name"] as the equivalent of running npx -y package-name in a terminal. If that terminal command does not start successfully, the same configuration will not start successfully inside Claude.

Configure more than one local server

Each server is a separate property inside mcpServers. The commas between entries matter, and the final entry must not have a trailing comma.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Projects"
      ]
    },
    "internal-tool": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"],
      "env": {
        "INTERNAL_API_TOKEN": "replace-with-a-scoped-token"
      }
    }
  }
}

Do not copy the second entry unless you actually have that script. It demonstrates the shape of a second server, not a published package. Replace the command, path, and environment variable with values from your server’s own documentation.

Absolute paths and PATH problems

Desktop applications may inherit a smaller PATH than your interactive terminal. This is common when Node was installed with nvm, fnm or Homebrew. If Claude reports that it cannot find npx, run which npx on macOS or where npx on Windows. Put the returned executable path in command.

Use absolute paths for scripts and allowed directories as well. Do not assume that ~, ./ or environment-variable interpolation will behave like your shell. On Windows, either escape each backslash as \\ in JSON or use forward slashes where the program supports them.

Validate the JSON before restarting

On macOS, Python can validate the file without uploading it to a third-party website:

python3 -m json.tool "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

On Windows PowerShell:

Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" -Raw | ConvertFrom-Json

A successful parse proves only that the JSON is valid. It does not prove that the executable exists, the package name is correct or the credentials work. Test those separately.

Remote connector setup, step by step

Use a remote connector when the service is already hosted, should work across devices or needs centralized authentication and administration. The exact labels can vary by plan, but the connection flow has four parts.

1. Get the official MCP endpoint. Use the provider’s own documentation or Anthropic’s connector directory. Do not infer an endpoint by adding /mcp to a normal API URL.
2. Add the connector. Individual Pro and Max users can use Claude’s connector settings. Team and Enterprise members may need an organization owner to register the connector first.
3. Authenticate. Complete the OAuth flow or other supported authorization method and review every requested scope.
4. Enable it for the conversation. Open the + menu in chat, choose Connectors, and toggle the connector on.

If the connector’s endpoint changes, Claude may require you to remove and re-add it rather than editing the existing entry. Disconnecting in Claude does not always revoke the third-party authorization, so also review connected applications in the provider account.

Local server or remote connector?

• Choose local for access to files on your machine, private scripts or development tools that must not be internet-facing.
• Choose remote for SaaS products, team-wide services, mobile access or a centrally managed production integration.
• Choose a Desktop extension when the same local capability is available as a trusted packaged install and you do not need custom launch arguments.

Do not use a public tunnel as a casual workaround for a private remote server. A tunnel changes the security boundary. If a company service must be reachable from Claude’s cloud, use approved network controls, HTTPS, authentication, rate limits, and auditable server-side authorization.

Claude Code MCP scopes and team sharing

Claude Code supports different configuration scopes. Pick the smallest scope that matches the intended audience:

• Local scope: applies to you in the current project. This is the default and a good choice for experiments or credentials tied to one repository.
• Project scope: writes a shareable .mcp.json for the repository. Use it for a team-standard server definition, never for secrets.
• User scope: makes a server available to you across projects. Use it for personal tools you need regularly.

A project-scoped server is not silently trusted just because its configuration is committed. Claude Code asks users to trust the workspace and approve project MCP servers. That prevents a newly cloned repository from launching an arbitrary process before review.

Import an existing Desktop server

Claude Desktop and Claude Code are separate applications and do not automatically share all server settings. On supported systems, Claude Code can import entries from the Desktop configuration:

claude mcp add-from-claude-desktop

Review every imported command and environment variable afterward. A local Desktop configuration that is appropriate for one machine may not be appropriate as a project-level team configuration.

Add a remote HTTP server with a header

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

This syntax is useful for services that document static bearer authentication, but a token on a command line may enter shell history. Prefer OAuth or a supported dynamic-secret mechanism for long-lived production access. Follow the server publisher’s current authentication instructions instead of assuming every endpoint accepts a bearer token.

Understand connection status

claude mcp list can report connected, needs authentication, failed to connect, pending approval, rejected or disabled. “Added” means the configuration was written; it does not by itself prove a healthy connection. Use claude mcp get NAME for details and /mcp inside Claude Code for interactive status and authentication.

How to evaluate an MCP server before installing it

A long directory listing is not a recommendation. Evaluate the server as you would any application that receives credentials and can act on your data.

1. Publisher: Is it maintained by the service vendor, the MCP project or an identifiable third party?
2. Source and releases: Is the code available for review? Are releases current and reproducible?
3. Capabilities: Which tools, resources, and prompts does it expose? Are any tools destructive?
4. Permissions: Can you restrict the token to selected repositories, folders, pages or read-only scopes?
5. Authentication: Does it use OAuth or another appropriate method? Where are secrets stored?
6. Network path: Is data processed locally, by the vendor, by your infrastructure or through another third party?
7. Maintenance: Does the publisher document upgrades, breaking changes, logs, and support?

Prefer a vendor-maintained server over an unofficial wrapper when both exist. For a community server, pin a reviewed version where practical and re-check permissions before upgrades. Avoid packages that imitate a popular server’s name but point to an unrelated publisher.

MCP error-to-fix matrix

Symptom	Most likely layer	First check
No connectors or tools appear	Config parsing or restart	Validate JSON and fully restart Claude Desktop
command not found	Executable PATH	Use the absolute executable path
ENOENT	Package, script or path	Run the exact command manually
Server exits immediately	Runtime or server code	Read server stderr and dependency errors
Connected, but zero tools	Server initialization	Inspect advertised capabilities with MCP Inspector
Tools exist but are not called	Prompt relevance or permissions	Request one named read-only tool explicitly
401 or OAuth error	Authentication	Check token expiry, scopes, and callback configuration
403 forbidden	Authorization	Confirm resource-level access, not just a valid login
Remote connection timeout	Network reachability	Confirm public HTTPS access from Anthropic’s network
Malformed protocol messages	STDIO output	Move application logs from stdout to stderr

Read the first real error

One startup problem often creates many secondary messages. Start with the earliest server-specific error after a clean restart. For example, an expired token may cause tool discovery to fail, which then causes Claude to report that no tools are available. Fixing the later symptom will not fix the authentication failure.

Test outside Claude

For local servers, run the exact command in a terminal with the same arguments and required environment variables. For remote servers, test DNS, TLS, the documented endpoint, and authentication separately. MCP Inspector can then verify initialization and tool discovery before Claude is added to the debugging chain.

Inspect Claude Desktop logs

On macOS, follow recent MCP logs with:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

On Windows, inspect the files in %APPDATA%\Claude\logs. The general mcp.log file shows connection-level events. A file named for a specific server contains that process’s stderr, which is usually where missing modules, invalid options, and authentication failures appear.

Fix a Windows APPDATA launch error

If a server log shows a literal ${APPDATA} path, the process may not have received the expanded variable. Follow the current server documentation and, if required, pass an explicit APPDATA value in that server’s env block. Confirm that npm is installed and that %APPDATA%\npm exists before changing unrelated settings.

From a working demo to a production MCP deployment

A server that works on a laptop is not automatically ready for a team. Before production use, define ownership, access, observability, and failure behavior.

• Authentication: use per-user identity where actions must be attributable; avoid one shared admin credential.
• Authorization: enforce permissions on the server for every tool call. Do not rely only on Claude’s description of a tool.
• Input validation: validate types, ranges, identifiers, and allowed destinations server-side.
• Confirmation: require explicit user confirmation for destructive, costly or externally visible actions.
• Timeouts and retries: bound external requests and make write operations idempotent before retrying them.
• Audit logs: record actor, tool, target, time, and result without recording secrets or unnecessary personal data.
• Rate limits: protect both the MCP endpoint and downstream APIs from loops and accidental bursts.
• Revocation: document how to disable the connector and revoke credentials quickly.
• Versioning: test server and SDK upgrades in a non-production environment.

For a remote server, monitor availability and authentication failures. For a local server, document the runtime version, installation source, allowed directories, and update process. In both cases, maintain a small set of test prompts that exercise tool discovery, a safe read, a denied action, and a controlled write.

Common Claude MCP setup mistakes to avoid

• Installing an outdated package from a copied tutorial: always confirm the command on the publisher’s current page.
• Using a normal REST API URL as an MCP endpoint: an MCP client needs a compatible MCP transport, not just any HTTPS API.
• Exposing a private local server publicly: use a local stdio configuration unless a reviewed remote architecture is required.
• Putting secrets in project config: a committed .mcp.json is for shareable definitions, not credentials.
• Granting full access for convenience: a valid connection with excessive scopes is still a bad setup.
• Ignoring the difference between authentication and authorization: a successful login does not prove access to the requested repository, page, channel or record.
• Adding too many servers at once: install and test one server, then add the next. This isolates failures and keeps the tool list understandable.
• Logging to stdout in a stdio server: protocol and log messages will collide.

The fastest successful setup is usually the smallest one: one trusted server, one read-only use case, one verified tool call, and one documented way to revoke access.

What changed in Claude MCP for 2026?

• Desktop extensions: Claude Desktop can install packaged local servers through .mcpb files, reducing manual JSON and dependency setup.
• Remote connectors across clients: Custom remote connectors can be used through Claude’s account-based connector flow rather than only from a local Desktop process.
• Streamable HTTP: HTTP is the recommended transport for new remote Claude Code integrations; legacy SSE remains for compatibility but is deprecated.
• Stronger organization controls: Team and Enterprise owners can control which extensions and connectors members may use.
• Claude Code tooling: claude mcp add, scoped configurations, status commands, and project approvals make local and remote setup easier to inspect.

Avoid relying on unsourced server-count claims or invented MCP version labels. The ecosystem changes too quickly for a static number to remain useful; use the official registry and vendor directories for current availability.

Claude MCP FAQ

Conclusion

The reliable 2026 setup is simple: choose a Desktop extension for convenience, manual JSON for a custom local server, a remote connector for cross-device cloud access or Claude Code’s MCP commands for repository workflows. Test the server command directly, use absolute paths, inspect connector status and logs, and grant the minimum permissions required.

Ready to use Claude for live prospecting? Explore Generect MCP or book a demo.