Claude Code Proxy: Set HTTPS_PROXY and settings.json

The variables Claude Code reads

The table lists the variables and what the documentation says about each. Lowercase names work as well. Claude Code uses the first one that is set, in this order: https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. Its WebSocket connections to localhost, ::1 and 127.0.0.0/8 never go through the proxy, so you do not need a loopback entry in NO_PROXY.

• Sources:
• Claude Code docs: Enterprise network configuration

The variables Claude Code reads: comparison

Summarised from the Claude Code documentation page cited below, read on 22 October 2026. Quoted phrases are the documentation's own.

HTTP proxies only, no SOCKS

The documentation states it directly: Claude Code does not support SOCKS proxies. A SOCKS5 endpoint will not work here, so use a proxy that speaks HTTP. For proxies that need advanced authentication such as NTLM or Kerberos, the documentation suggests an LLM gateway service instead.

A proxy URL with a username and password

For basic authentication, put the credentials in the URL, as in the example below.

The documentation warns against hardcoding passwords in scripts and recommends environment variables or secure credential storage instead. If the password contains characters such as @, : or /, percent-encode them in the URL, as in any URL with credentials.

A proxy URL with a username and password: example

export HTTPS_PROXY=http://username:[email protected]:8080

Example only: replace the placeholder values with your own.

Set the variables before you start

Variables exported in your shell are read once at startup, so a running session does not pick up later changes. Set them first, then launch Claude Code from the same shell.

In Command Prompt the session form is set HTTPS_PROXY=http://username:[email protected]:8080.

Set the variables before you start: macOS, Linux, WSL

# macOS, Linux, WSL
export HTTPS_PROXY=http://username:[email protected]:8080
claude

Example only: replace the placeholder values with your own.

Set the variables before you start: Windows PowerShell

# Windows PowerShell
$env:HTTPS_PROXY = "http://username:[email protected]:8080"
claude

Example only: replace the placeholder values with your own.

Make it permanent in settings.json

Every environment variable on that documentation page can also be set in settings.json. That matters for background agents. A per-user supervisor process hosts sessions started with claude agents, --bg and /background. It outlives your shell and inherits the environment of whichever shell started it first, so a variable exported only in your shell reaches background agents by luck. The documentation says settings are the only configuration that reaches every background session.

Put the block below in ~/.claude/settings.json, or in managed settings if an administrator deploys them.

• Sources:
• Claude Code docs: Enterprise network configuration

Make it permanent in settings.json: example

{
  "env": {
    "HTTPS_PROXY": "http://username:[email protected]:8080"
  }
}

Example only: replace the placeholder values with your own.

Custom certificate authorities

By default Claude Code trusts its bundled Mozilla certificates and your operating system's certificate store. The documentation says enterprise TLS-inspection proxies work without extra configuration when their root certificate is installed in the OS trust store and Claude Code can read it. The native installer always can. npm installs need Node 22.15 or later. Otherwise point NODE_EXTRA_CA_CERTS at the certificate file, as shown below.

This only matters for a proxy that inspects traffic. A plain forward proxy does not need it.

Custom certificate authorities: example

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Example only: replace the placeholder values with your own.

Check what Claude Code is actually using

Claude Code does not validate most network settings when it reads them. The one exception is the proxy URL: if it cannot parse the value, for example because http:// is missing, it stops at launch with an error naming the variable to fix. To confirm the rest:

• Run /status in an interactive session. The Proxy row shows the active proxy URL, and marks a value it cannot parse as invalid and ignored.

• Start with claude --debug. The log goes to ~/.claude/debug/<session-id>.txt, or to a path you set with --debug-file.

• Test the proxy itself from a terminal with the command below. It shows the exit IP, country and network that sites will see.

The fields ip, country, city and org are explained in the guide on how to check your proxy's IP, country and ISP.

• how to check your proxy's IP, country and ISP

• Sources:
• Claude Code docs: Enterprise network configuration

Check what Claude Code is actually using: example

curl -x http://username:[email protected]:8080 https://ipinfo.io/json

Example only: replace the placeholder values with your own.

If it does not connect

• Claude Code stops at launch: the proxy URL has no scheme. Write the full http://... URL.

• 407 Proxy Authentication Required: the proxy rejected the username or password. Copy them again instead of retyping them.

• A SOCKS5 address: not supported. Use an HTTP proxy.

• Works in your shell but not in a background agent: set the variable in settings.json.

• A firewall in between: the documentation lists the hosts Claude Code needs, including api.anthropic.com, claude.ai and platform.claude.com. Allow them in your proxy rules.

Give Claude Code a proxy tool with MCP

MCP adds tools to Claude Code. With the proxy302-mcp server, Claude Code can get a Proxy302 proxy and fetch pages through it from the chat, without switching to the console. The command below adds it for all your projects.

proxy302-mcp is the official Proxy302 MCP server, open source on GitHub and maintained by the Proxy302 team. Proxy302 also runs it at https://proxy302.com/v1/mcp: clients that can send an Authorization header, such as Claude Code, Cursor and VS Code, connect with an API key and install nothing.

This is a separate setting from the rest of this page. The proxy that Claude Code itself uses to reach Anthropic is set with HTTPS_PROXY, as described above; the MCP server's tools have their own settings, and installing the server does not change how Claude Code connects. The guide to the Proxy302 MCP server covers the tools, the other clients and the limits.

• Proxy302 MCP server guide

• Sources:
• Claude Code docs: Connect Claude Code to tools via MCP
• proxy302-mcp README (official Proxy302 MCP server)

Give Claude Code a proxy tool with MCP: command

claude mcp add proxy302 -s user -e PROXY302_API_KEY="<key id>:<secret>" -- npx -y github:proxy302/proxy302-mcp

Replace <key id>:<secret> with your Proxy302 API key. -s user makes the server available in every project; without it, Claude Code adds it to the current project only.

• Sources:
• Claude Code docs: Connect Claude Code to tools via MCP

How to do it with Proxy302

A static ISP proxy fits this task: the IP stays fixed while the lease runs and does not rotate, and you choose HTTP at purchase, which is the protocol Claude Code needs. The Claude preset in the console starts on SOCKS5, so switch Protocol to HTTP before you generate. The page on Claude proxies has the preset and the full setup. The table below is our latest hourly check of Claude through exits in seven countries, with the network of each exit and the response time of the site.

• Claude proxies

Measured exits: Claude from seven countries

Hourly check of the Proxy302 probe, 22 October 2026, 14:18 UTC: one request to Claude per country through a dynamic residential exit, using the public Proxy302 entry. Only the first three octets of an IP are public. One sample per country, not an average; later checks will differ.

• Sources:
• Proxy302 hourly connectivity check

How to do it with Proxy302: steps

1. Step 1

   Open the static ISP page, choose the country, set Protocol to HTTP, choose the term and the quantity, then click Review cost and generate.

2. Step 2

   Open My assets and copy HOST, PORT, USERNAME and PASSWORD. The Tools & checks page shows a ready example with your own endpoint.

3. Step 3

   Set HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT in your shell, or in the env block of ~/.claude/settings.json.

4. Step 4

   Start claude, run /status, and check the exit with the curl command above.

Prices and limits

A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days, about US$0.27 per day, and the price is the same in every country. Availability changes daily and is shown on the order page. There is no free trial, and the smallest purchase is one IP for one day. A proxy changes only the network exit: Anthropic's rules on supported regions still apply to you, as the guide to Claude, ChatGPT and Gemini supported countries explains.

• Claude, ChatGPT and Gemini supported countries
• On a budget? Choose a regular static residential IP

• Sources:
• Proxy302 product facts and price list

Proxy302 at a glance

Prices are in PTC, paid from the wallet; 1 PTC = US$1. There is no free trial: the smallest purchase is 1 GB of rotating residential traffic or one IP for one day. Checked on 4 November 2026.

• Sources:
• Proxy302 product facts and price list
• Proxy302 ISP for AI subscriptions: public catalog

FAQ

Read next

Claude proxy

Claude proxy is the Claude ISP: a dedicated native IP in the US, Frankfurt, Japan or London, 15 PTC for 30 days, HTTP for Claude Code — and Anthropic's region rules.

View options and pricing

ChatGPT, Claude and Gemini supported countries

The four official availability lists compared country by country — China, Hong Kong, Russia and more — plus hourly checks of the OpenAI and Anthropic APIs from 7 countries.

Check a proxy's IP, country and ISP

Check the exit IP, country and ISP your proxy really gives you in 30 seconds — and why IP databases disagree on the city. With our own test of three lookup services.

Cursor proxy setup

Set a proxy in Cursor with http.proxy, handle special characters in the password, switch to HTTP/1.1 when streaming hangs, and verify with Run Diagnostics.

Proxy MCP server for AI coding tools

What a proxy MCP server is, how local and remote MCP servers differ, how to install one in Claude Code, Codex CLI and Cursor, and how to route the server's own traffic through a proxy.