How to Fix Claude Code When It Cannot Connect to an MCP Server

Start with Claude Code’s diagnostics: run /mcp to see each server’s status and error, then run /doctor for installation, settings, extensions, and context checks. After that, inspect the active definition with claude mcp list and claude mcp get <name>. Most connection failures come from one of four places: Claude Code loaded a different configuration than you expected, the server process or transport is wrong, authentication is missing or mismatched, or a proxy/TLS policy blocks the network.

This guide follows that order so each step narrows the failure. It covers local stdio servers, remote HTTP or SSE servers, OAuth, authorization headers, environment variables, Windows launchers, proxies, and custom certificate authorities.

1. Capture the exact failure before changing anything

In Claude Code, run /mcp. Record the server name, transport, status, and the complete error wording. Redact access tokens, cookies, private URLs, and authorization headers.
Run /doctor. Follow its findings for installation, settings, extensions, and context problems. If it reports that MCP servers are not loading, use the configuration-debugging path in the official troubleshooting guide.
Reproduce the problem after starting a new Claude Code session. Environment variables exported after Claude Code started are not used by that process.

A generic “connection failed” message does not identify the cause. Treat the status detail from /mcp and the debug log as evidence, not as a diagnosis.

2. Confirm which MCP definition Claude Code is using

Claude Code can load MCP servers from local, project, and user scopes. A same-name definition in a higher-precedence scope is selected as a whole; fields are not merged across duplicate entries.

claude mcp list
claude mcp get my-server

Check all of the following in the output:

the selected scope (local, project, or user);
the server name and whether another scope defines the same name;
the transport: local stdio, remote HTTP, or remote SSE;
the executable, URL, and arguments;
environment-variable references in arguments, URLs, and headers.

If you recently ran claude mcp add, remember that saving a configuration does not prove that the process can start or that credentials work. Re-run /mcp and verify the resulting status.

3. Fix local stdio server failures

A stdio server is a process that Claude Code launches and communicates with over standard input and output. Test the launch command outside Claude Code first, using the same account, working directory, runtime, and environment.

Check the executable and runtime

Use an absolute path temporarily if node, python, uv, or another executable may not be on Claude Code’s PATH.
Confirm the package or script exists in the environment that launches Claude Code.
Check that arguments are ordered correctly and that a required working directory exists.
Make sure the server writes protocol traffic to stdout only. Diagnostic logging should go to stderr; arbitrary stdout output can corrupt the MCP exchange.

Windows and `npx`

On native Windows, an stdio server invoked through npx may need the documented cmd /c npx ... wrapper. Without it, Claude Code can fail to spawn the command even though the same command works in an interactive shell. Apply the Windows form from the official MCP setup guide, then restart Claude Code and check /mcp.

Process-level edge cases

Immediate exit: the server may have a missing dependency, invalid argument, or startup exception. Run it directly and inspect stderr.
Hanging startup: the server may be waiting for an interactive prompt. Configure non-interactive credentials and options.
Permission denied: fix executable permissions or run from a directory readable by the Claude Code process.
Wrong project: relative paths resolve from the configured launch context, not necessarily the terminal directory where you tested them.

4. Fix remote HTTP and SSE connections

For a remote server, verify the endpoint from the same machine, container, shell environment, and network route used by Claude Code. A browser test from another network does not prove that Claude Code can reach it.

Confirm the URL scheme, hostname, path, and port. Remove accidental whitespace and make sure the endpoint is the MCP endpoint rather than a landing page.
Check DNS, firewall allowlisting, and outbound proxy rules from the Claude Code host.
Use the server’s documented transport. An HTTP endpoint configured as SSE, or an SSE endpoint configured as HTTP, can fail before authentication is evaluated.
Inspect the debug output for redirects, TLS errors, response status, and missing-variable warnings.

Do not infer the cause from status code alone. A 401 or 403 commonly means authentication is required, while a timeout can be a route, proxy, TLS, or server-liveness problem.

5. Match the authentication method to the server

OAuth

If the server expects OAuth, authenticate through /mcp or the CLI command:

claude mcp login <name>

Complete the browser flow, return to Claude Code, and check the server status again. OAuth credentials and manually supplied bearer headers are different paths.

Authorization headers

If the server explicitly requires a token header, verify the token value, header name, and expected scheme. If a manually configured Authorization header is rejected but the server is intended to use OAuth, remove the manual header and use the OAuth flow instead. Never paste a live token into a public issue, screenshot, or shared debug log.

6. Check environment-variable expansion

Review every variable referenced by the server definition. A missing variable can remain as a literal ${VAR} value or, for certain sensitive values in remote URLs and headers, be read as empty. Both cases can produce an apparently valid but unusable configuration.

Use claude mcp get <name> to locate variable references.
Check that the variable is exported in the shell that launches Claude Code.
Restart Claude Code after exporting or changing it.
Use debug logging to confirm that configuration loading found the variable; do not print the secret itself.

7. Diagnose proxies, firewalls, and custom TLS certificates

Corporate networks can change the failure from a straightforward connection to a proxy authentication, certificate, or allowlist problem. Claude Code’s enterprise network guidance covers HTTP_PROXY, HTTPS_PROXY, NO_PROXY, and custom CA trust: network configuration documentation.

Verify that proxy variables point to the correct protocol and host.
Add internal MCP hosts to NO_PROXY only when your network policy requires a direct route.
Install or configure the organization’s CA certificate according to your Claude Code runtime and operating system.
Check whether a firewall allows outbound traffic to the MCP host and port.
After changing shell-exported variables or certificate settings, launch a fresh Claude Code process.

A TLS error is not fixed safely by disabling certificate verification. Identify whether the certificate is expired, issued by an untrusted corporate CA, mismatched to the hostname, or being intercepted by a proxy, then apply the supported trust configuration.

8. A decision tree for common errors

Symptom	Likely cause	Next action
Server missing from `/mcp`	Wrong scope, duplicate name, or invalid configuration	Run `claude mcp list` and `claude mcp get <name>`; inspect all scopes.
Command not found or spawn failure	Runtime absent from Claude Code’s PATH	Use an absolute executable path and test under the same launch environment.
Process exits immediately	Startup exception, dependency, or invalid argument	Run the command directly and read stderr.
401 or 403	Missing, expired, or incorrect authentication	Use `claude mcp login` for OAuth or correct the configured header.
Literal `${VAR}` in a request	Variable was not expanded	Export the variable before launch and restart Claude Code.
Timeout or connection refused	Wrong endpoint, server down, firewall, or proxy	Reach the endpoint from the Claude Code host and inspect proxy/firewall logs.
Certificate or handshake error	Untrusted CA, hostname mismatch, or interception	Configure the required CA trust and verify the hostname.
Works in a terminal but not Claude Code	Different PATH, scope, working directory, or startup environment	Compare the effective command, environment, and scope; restart Claude Code.

9. Reliability and performance practices

Keep local server startup fast and deterministic. Avoid interactive setup during process launch.
Use one canonical server name per environment to reduce scope-precedence mistakes.
Prefer OAuth or the server’s documented secret mechanism over hard-coded tokens.
For remote servers, monitor endpoint latency, proxy behavior, and certificate expiry.
When debugging, change one variable at a time and re-check /mcp; this preserves a useful cause-and-effect trail.
Cache or reuse expensive upstream connections inside the MCP server when its implementation supports it, while respecting its timeout and session rules.

Claude Code’s MCP documentation and CLI reference are the authoritative places to confirm version-specific commands and configuration behavior: MCP guide and CLI reference. The MCP protocol itself is described by Anthropic as “an open protocol that standardizes how applications provide context to LLMs.”

10. Or skip the browser setup

If your MCP workflow needs screenshots for an agent, ScreenshotNeo provides an MCP server with take_screenshot, get_page_info, and capture_pdf. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; and each response reports its verdict and billing status. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots.

One GET request is enough:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));

See the ScreenshotNeo API documentation for the full option set, including device presets, full-page and element capture, custom CSS and JavaScript, waits, request blocking, cookies and headers, PDF output, caching, signed links, async jobs, bulk capture, and usage reporting.

Create a free ScreenshotNeo account with 1,000 screenshots a month and no credit card.

FAQ

Does `claude mcp add` test the server?

No. It can save a definition without proving that the process starts, the endpoint is reachable, or credentials are valid. Always verify with /mcp.

Should I use OAuth and an Authorization header together?

Use the method the server documents. A manually supplied header can conflict with an OAuth flow; remove it when OAuth is intended.

Why did changing an environment variable do nothing?

Claude Code reads shell environment variables when it starts. Export the value and launch a new session.

Share the redacted server status, transport, scope, non-secret command or endpoint shape, and relevant debug error. Remove tokens, cookies, private hostnames, and complete environment dumps.