Task-led troubleshooting · official Anthropic docs checked Nov 3, 2026
Fix Claude Code MCP connection problems behind a proxy
Separate local stdio and remote HTTP MCP setup, configure documented proxy variables, and use Claude Code status and debug output to narrow connection failures.
How do I connect Claude Code to an MCP server behind a proxy?
First identify the server transport. For a remote HTTP server, use `claude mcp add --transport http <name> <url>`. For a local process, configure a stdio server with its launch command after `--`; it is a different connection path. For Claude Code's own network requests, Anthropic documents `HTTPS_PROXY` and `HTTP_PROXY` environment variables, with `NO_PROXY` for destinations that should bypass the proxy. Set shell variables before launching Claude Code, since the process reads them at startup.
What should I check when an MCP server says Failed to connect?
Run `claude mcp list` and `claude mcp get <name>` to see the server status and failure detail, then check `/mcp` in an interactive session. A failed status means Claude Code could not connect; an HTTP status or error text can help distinguish a server response from a network failure. Start Claude Code with `--debug` and inspect the session log for proxy or certificate configuration. Check the server URL, transport, proxy reachability, and any required authentication with your administrator or server owner.
Does a pending approval mean the proxy is broken?
No. Anthropic documents `Pending approval` for a project-scoped server in `.mcp.json` that has not been approved in a trusted interactive session. Review and approve the project server in Claude Code first. A rejected, disabled, or enterprise-policy-blocked status is also a configuration decision rather than proof of a network failure.
Can I use NO_PROXY for a local MCP server?
Anthropic's current enterprise network documentation supports `NO_PROXY` and says Claude Code avoids proxying WebSocket connections to loopback addresses. A February 2026 GitHub issue reported a different failure for HTTP MCP requests to localhost in Claude Code 2.1.31; the issue was later closed as inactive, so it does not establish current behavior or a fix. Check the documentation and behavior for your installed version, and use debug output to verify which route the MCP request takes.
Which proxy settings are unsupported?
Anthropic's current network guide says Claude Code does not support SOCKS proxies. For proxies using advanced authentication such as NTLM or Kerberos, Anthropic points to an LLM Gateway that supports that method. Do not put long-lived credentials into a shared command or repository file; follow your organization's approved secret handling.
Why does a setting work in my terminal but not in Claude Desktop?
The connection owner and session type matter. Anthropic says that in Claude Desktop sessions where the app manages the provider connection, proxy variables are read from managed settings and `~/.claude/settings.json`, not repository settings. For shell-launched sessions, export the variables before starting Claude Code. Check the documentation for the specific Desktop or hosted session type you use.
What is the safest way to test a proxy change?
Use a test MCP server and a non-sensitive session. Confirm the expected proxy value in `/status` or the debug log, check `claude mcp list` and `claude mcp get <name>`, and make one connection attempt. Keep secrets out of logs and shared settings. This guide summarizes official documentation checked November 3, 2026; it does not claim every MCP server or corporate proxy behaves the same way.
Sources
- Anthropic Claude Code Docs: Connect Claude Code to tools via MCP · checked Nov 3, 2026
- Anthropic Claude Code Docs: Enterprise network configuration · checked Nov 3, 2026
- Anthropic Claude Code Docs: Settings files and precedence · checked Nov 3, 2026
- GitHub issue #23344: HTTP MCP client and NO_PROXY report · observed Nov 3, 2026