What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
If Claude Code cannot connect to an MCP server, first run /mcp and record the exact status and error. Then check the active server definition with claude mcp list and claude mcp get <name>. This separates the main causes: a configuration or scope mismatch, a local server that will not launch, remote authentication, or a proxy or TLS problem. A generic “connection failed” message alone does not identify which one is responsible.
1. Check Claude Code’s own status and diagnostics
Inspect MCP status
In the Claude Code session that is failing, run /mcp. Note which server is affected and the status or error shown for it. If more than one server is configured, distinguish the failing entry from servers that are connected; their status may point to different causes.
Redact access tokens, sensitive endpoint details, and other credentials before sharing output. A diagnostic log can be useful, but it should not become a way of publishing secrets.
Run the broader health check
Run /doctor to check Claude Code installation, settings, extensions, and context usage. If MCP servers are not loading, use the configuration-debugging route in Claude Code’s troubleshooting documentation. These checks are useful early because they can identify an issue in Claude Code’s settings or installation before you spend time changing the server itself.
Recommended Free Tools
2. Confirm which server definition Claude Code is using
A server can appear correctly configured in one place while Claude Code is using a different definition with the same name. List configured servers, then inspect the specific one:
- Run
claude mcp listto see the configured servers. - Run
claude mcp get <name>, replacing<name>with the affected server’s name. - Check its scope, transport, command or endpoint, arguments, and environment-variable references against the server you intended to configure.
Claude Code supports local, project, and user configuration scopes. If a server with the same name exists in more than one scope, the highest-precedence matching definition is used as a whole; Claude Code does not merge fields from the entries. Thus, a valid command in one entry will not necessarily supply a missing argument or environment variable in the entry that takes precedence. Check for duplicates before editing credentials or networking.
Adding a server with claude mcp add only saves configuration. It does not prove that the server can start, that its credentials work, or that a remote endpoint is reachable. Return to /mcp and verify the resulting status after making a change.
3. Diagnose local stdio servers
A local stdio server is launched as a process by Claude Code. The process must be available and able to start in the environment from which Claude Code runs. A configuration may look plausible yet fail because its executable cannot be found, an argument is wrong, or the launch command behaves differently on that platform.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCheck the launch definition
- Use
claude mcp get <name>to verify the command and each argument, rather than relying on a similarly named configuration in another scope. - Confirm the executable is available to the Claude Code process. If the command depends on a shell environment or a package runner, check it in the same environment used to start Claude Code.
- Inspect environment references in the definition. A missing variable may remain as a literal
${VAR}value. Certain sensitive values used in remote URLs or headers may instead be read as empty. Either outcome can prevent a connection; consult the debug log for the documented warning, and do not print credentials to diagnose it.
Windows and npx
On native Windows, an stdio server started through npx may need the documented cmd /c npx ... wrapper. If that describes your setup, use the Windows form in the official Claude Code MCP guide. Do not apply this workaround to unrelated launch failures: first confirm that the failing entry is an stdio server using npx.
4. Diagnose remote HTTP or SSE servers
Remote servers use HTTP or SSE configurations rather than a local process command. Check the endpoint and authentication as separate parts of the connection. Verify that the endpoint is the intended one and reachable from the same machine and environment as Claude Code; a URL that works from another browser or host does not establish that Claude Code can reach it.
Choose the authentication flow the server expects
For an OAuth-enabled server, authenticate through /mcp or run claude mcp login <name>. A 401 or 403 can indicate that authentication is required, although the status alone does not establish why the request was rejected.
If the configuration supplies an Authorization header manually, check that the token is current and belongs to the intended server. If OAuth is the intended flow, remove a manually configured header that conflicts with it and authenticate using OAuth instead. Do not assume that combining both methods is necessary or correct; match the configuration to the server’s supported authentication method.
Free tools Windows power users keep installed
One-click scans. No signup required.
Recheck environment-variable expansion
Remote URLs and headers can depend on environment variables. If a variable is absent, it may produce a literal placeholder or, for certain sensitive values, an empty value. Inspect the effective configuration and debug warning without dumping the resolved secret. If the variable is supplied by your shell, remember that Claude Code reads shell environment variables when it starts: update the environment, then launch a fresh Claude Code session before testing again.
5. Check proxies, firewalls, and TLS trust
When configuration and authentication look right, examine the network path from the Claude Code process to the remote server. In a corporate or managed environment, a proxy, firewall policy, or custom TLS certificate can interfere even when the endpoint itself is correct.
- Review whether
HTTP_PROXY,HTTPS_PROXY, andNO_PROXYare set appropriately for the environment. - Check whether a firewall or other network policy permits the connection to the intended endpoint.
- If the network uses a custom certificate authority, review Claude Code’s current guidance for custom CA trust rather than applying a generic certificate workaround.
- After changing shell-exported proxy or certificate-related environment settings, start a new Claude Code session. The process reads shell environment variables at startup.
Claude Code’s enterprise network guidance covers proxies and certificate trust. Use debug logging to confirm that the settings are being loaded. The correct configuration depends on the network, installation, and runtime, so there is no universal proxy or certificate value that fixes every environment.
6. Use the error to choose the next check
| What you observe | What to check next |
|---|---|
| Server is missing or an unexpected definition appears | Compare claude mcp list and claude mcp get <name>; check local, project, and user scopes for duplicate names. |
| Local stdio server does not start | Verify command availability, arguments, environment references, and platform-specific launch details. For native Windows with npx, check the documented cmd /c wrapper. |
| Remote server returns 401 or 403 | Confirm whether the server expects OAuth or a configured authorization header, then use the matching login or token path. |
| Remote endpoint fails only in a managed network | Review proxy variables, network policy, and custom CA trust; restart Claude Code after changing shell environment settings. |
| Status is only “connection failed” | Do not infer a cause from that label alone. Inspect the active definition and debug output, then test the relevant process, authentication, or network path. |
7. Escalate with useful, safe diagnostics
If the preceding checks do not isolate the failure, keep a short record of the affected server name, its scope and transport, the exact status or error, and the checks already performed. Use /doctor and the official configuration-debugging and troubleshooting paths for problems that appear to involve Claude Code itself. Consult the MCP guide and CLI reference for server setup and management behavior; version-specific details can change as the documentation is updated.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Before posting an issue publicly, remove tokens, authorization headers, sensitive endpoint data, and private environment values. Share only the relevant, redacted diagnostic output rather than a full environment dump.
Or skip the browser setup
ScreenshotNeo is a separate website screenshot API and MCP server, not a repair for Claude Code’s connection to another MCP server. If your development task also needs website captures, you can request one with a single GET call. The API accepts a URL and can return an image or PDF; see the ScreenshotNeo API documentation for the available options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses indicate the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does claude mcp add confirm that a server works?
No. It saves a configuration; check the server status in Claude Code afterward.
Should I share my full debug log when asking for help?
Only share the relevant output after redacting tokens, authorization headers, sensitive endpoints, and private environment values.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
