Claude Code MCP Setup Guide: 3 Ways to Configure & Fix Errors

Claude Code connects to external tools such as browsers, databases, and GitHub through MCP (Model Context Protocol), which supports two transport types: HTTP for already-deployed remote servers and stdio for locally run servers, according to a setup guide. HTTP servers are added with the command `claude mcp add --transport http <MCP_service_URL>`, with authentication tokens passed via `--header "Authorization: Bearer YOUR_TOKEN"`, while local servers use `claude mcp add --transport stdio -- <startup_command> [arguments]`, as in `claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest`. The guide instructs users to verify connections with the `/mcp` command and troubleshoot failures in the order of MCP address, authentication information, network connection, and remote server status.

Although Claude Code can complete tasks such as code writing and file operations, it still needs external tools to expand its capabilities in scenarios like browser automation, database queries, and GitHub operations. MCP Model Context Protocol is precisely the protocol that connects Claude Code with external tools. This article will introduce the role of MCP, Server selection, 3 configuration methods, and common error troubleshooting. MCP Model Context Protocol is an open protocol connecting AI applications, external tools, and data sources. Claude Code itself can perform tasks like code writing and file handling, while through MCP, it can further access external capabilities such as browsers, databases, and code repositories. From the perspective of working principles, Claude Code is responsible for understanding user needs and determining whether to call external tools, while the MCP Server is responsible for providing specific capabilities. Upon receiving a call request, the Server executes the corresponding operation and returns the result to Claude Code. In this way, different tools can be connected according to a unified protocol without building separate connection mechanisms for each tool. Currently, there are two main common transmission protocols for MCP: After understanding the transmission protocol of MCP, choosing an MCP Server can be distinguished according to the actual capabilities provided: Therefore, when choosing MCP, there is no need to blindly pursue quantity. First clarify the capabilities that need to be expanded, and then choose according to the function and running environment of the Server. HTTP MCP Servers are usually already deployed in remote environments, and Claude Code only needs to connect to the corresponding service address without installing and starting the Server locally. For beginners, this method has fewer configuration steps and is suitable for quickly connecting to an already set up MCP service. The basic command executed in Claude Code is as follows: claude mcp add --transport http <MCP service URL If the service requires identity authentication, you can use — header to add a Token: claude mcp add --transport http my-server https://example.com/mcp --header "Authorization: Bearer YOUR TOKEN" After adding, type /mcp in Claude Code to check if the Server appears in the list and confirm the connection status. If the connection is not successful, it is recommended to check in the order of MCP address, authentication information, network connection, and remote Server status. First confirm that the service address itself can be accessed normally, and then troubleshoot the configuration issues of Claude Code, which can avoid repeatedly modifying commands. If the MCP Server needs to run locally, you can use the stdio method. Claude Code will start the corresponding program and communicate with the Server through standard input and output, so local tools like npx, uvx, Node.js, and Python can all adopt this method. First add the Server according to the following format: claude mcp add --transport stdio -- <startup command arguments The — here is used to distinguish between Claude Code’s own parameters and the startup parameters of the MCP Server. When configuring, ensure that the startup command is already installed and can be executed normally in the current terminal environment. Taking Playwright MCP as an example, you can directly execute: claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest After the configuration is complete, you can check whether the Server is connected normally through /mcp. If browser automation tools like Playwright MCP are further used for data collection, what truly needs attention is not just whether the browser can open web pages, but also the anti-scraping mechanisms of target sites. Websites usually judge whether access is abnormal based on request frequency, access behavior, cookies and session states, browser fingerprints, and network outlets. Situations like CAPTCHAs, restricted access, and failed page loading may occur. These restrictions directly affect collection efficiency and data integrity, and more seriously may lead to account suspension. For scenarios that require automated data collection, you can configure dedicated residential proxies like IPFoxy in the browser or running environment. Compared with datacenter proxies, such proxies are closer to the network exit characteristics of real users, suitable for long-term stable collection tasks. They can reduce task interruptions or access anomalies caused by frequent network exit changes, lowering the probability of triggering anti-scraping mechanisms. If you need to manage multiple MCP Servers at the same time, or want to include configurations in project collaboration, you can directly manage them through JSON files. Claude Code mainly has two configuration scopes: project-level .mcp.json and user-level ~/.claude.json. Among them, .mcp.json is suitable for team collaboration, and the configuration can be unified and maintained with the project; ~/.claude.json is more suitable for personal use, allowing you to reuse your own MCP configuration across different projects. The following is an example of project-level .mcp.json configuration: { “mcpServers”: { "mcpServers": { "playwright": { "type": "stdio", "command": "npx", "args": "@playwright/mcp@latest" } }} If you only want personal global use, you can configure it in ~/.claude.json: { “mcpServers”: { "mcpServers": { "playwright": { "type": "stdio", "command": "npx", "args": "@playwright/mcp@latest" } }} The difference between the two configurations lies mainly in the scope of action: project-level configuration is suitable for teams to unify tools and environments, while user-level configuration is suitable for long-term personal use. Regardless of which method is adopted, after completing the configuration, you can check whether the Server is correctly recognized by Claude Code through /mcp. This type of issue mainly occurs during the HTTP MCP connection process. Common causes include incorrect MCP address, remote Server anomaly, invalid authentication information, and local network unable to access the target service normally. You can check in the following order: If the target MCP is a remote HTTP service and the current environment needs to connect via stdio, you can use mcp-remote as a bridge layer to forward local stdio requests to the remote MCP. However, if the remote service itself returns 502, it still needs to be handled on the server side. ENOENT usually indicates that the system cannot find the specified executable file. When Claude Code calls npx on Windows, if Node.js is not properly installed, PATH is not configured, or Shell fails to get the correct environment variables, this error may occur. First execute in the terminal: npx --version If it cannot run, recheck the installation of Node.js and npm, as well as the PATH configuration; if the terminal can run normally but Claude Code still reports an error, check the Shell and environment variables used by Claude Code. If necessary, you can switch to using node to directly start the MCP Server, bypassing the npx call. Appears Similar to npx ENOENT, this error usually means that Claude Code cannot find the uvx executable file. Common reasons are that uv is not installed or the installation directory is not added to the system PATH. First execute: uvx --version If the command does not exist, install uv and add its directory to PATH. After modifying environment variables, reopen the terminal and restart Claude Code, then check whether MCP can start normally. This prompt usually means that Claude Code did not read a valid MCP Server configuration, rather than a Server connection failure. Common reasons include the Server not being successfully added, the configuration file location being incorrect, or JSON format issues. First confirm whether the MCP Server has been added, then check whether .mcp.json or ~/.claude.json is in the correct position, and check fields such as mcpServers, type, command, and args. Restart Claude Code after modification and run /mcp to view the Server status. If it is Windows + Playwright MCP, you should also focus on checking npx, Shell, and stdio communication. If npx runs normally but the Server still fails to start, you can try using Node.js to directly execute the entry file of Playwright MCP. How to check if MCP is configured successfully in Claude Code? Enter Claude Code and run /mcp to view configured MCP Servers and their connection statuses. Can Claude Code configure multiple MCP Servers at the same time? Yes. Claude Code supports configuring multiple MCP Servers, and different Servers can provide different tool capabilities. In actual use, it is recommended to select according to task requirements to avoid increasing management costs by configuring too many irrelevant tools. Why can’t Claude Code call the MCP Server after configuration? In addition to connection status, you also need to check whether the Server actually provides the corresponding tool and whether tool dependencies are completely installed. You can first confirm the connection through /mcp, and then check the Server’s startup command, running environment, and specific tool permissions. The core of configuring MCP in Claude Code lies not in memorizing commands, but in choosing a suitable configuration scheme based on how the Server runs. Prioritize HTTP for remote services, stdio for local tools, and JSON file management for long-term personal use or team collaboration. When encountering operational anomalies, troubleshooting step by step in the order of configuration, dependencies, Shell environment, network connection, and Server status will allow you to locate problems faster and complete fixes. Claude Code MCP Setup Guide: 3 Ways to Configure & Fix Errors https://pub.towardsai.net/claude-code-mcp-setup-guide-3-ways-to-configure-fix-errors-921779e4f432 was originally published in Towards AI https://pub.towardsai.net on Medium, where people are continuing the conversation by highlighting and responding to this story.