Proxy MCP Server: Give Claude Code, Codex and Cursor a Proxy

Two different things called a proxy MCP server

A proxy MCP server is an MCP server that manages IP proxies for an AI assistant. The assistant calls a named tool, for example one that returns a proxy URL for a country or opens a page through a proxy, and the username, password and API key stay in the server's configuration instead of in the chat.

The name is easy to mix up with mcp-proxy, an open-source tool whose repository describes it as "A bridge between Streamable HTTP and stdio MCP transports". It moves MCP messages between two transports so that a client that speaks only one can reach a server that speaks the other. It has no connection to IP addresses, countries or exit nodes. In this guide, "proxy MCP server" always means the first kind.

• Sources:
• mcp-proxy (sparfenyuk) README

Local and remote MCP servers

The MCP documentation separates servers by where they run. A local server uses the stdio transport: the client starts it as a process on your own machine and talks to it over standard input and output, with no network overhead. A remote server uses the Streamable HTTP transport: it runs at a URL, and that transport supports bearer tokens, API keys and custom headers for authentication.

That decides where the key goes. For a local server, the client passes the key to the process as an environment variable. For a remote server, the key is normally sent as an HTTP header on each request. Either way, the point of a proxy MCP server is that the key never has to appear in a prompt.

• Sources:
• MCP documentation: Architecture overview

What to check before you install one

Read the tool list first. A proxy MCP server runs with your credentials and can call paid infrastructure, so look at every tool name and description.

Check whether any tool can buy something or spend your wallet. If one can, decide whether you want that, and prefer servers where purchasing is absent.

Check where the key lives. It belongs in an environment variable or a client configuration file that you do not commit to version control, never in a prompt, because prompts end up in conversation history.

proxy302-mcp, the official MCP server

proxy302-mcp is the official Proxy302 MCP server, open source on GitHub and maintained by the Proxy302 team. Account and billing questions go to Proxy302 support; bugs in the server go to its GitHub issues.

It is free and open source (MIT), installed from GitHub with npx, runs on your own machine over stdio and needs Node.js 20+ and a Proxy302 API key in the PROXY302_API_KEY environment variable. Its tools cover account usage and wallet balance, countries and regions, products and plans, a ready rotating residential proxy URL for a country, your own proxies, and fetching a URL through the proxy (plain HTTP, no JavaScript rendering).

It cannot buy anything or spend your wallet. Its only write is creating a free dynamic proxy credential, which is off by default, and traffic is billed only when used. The Proxy302 API itself is documented in the developer docs.

• developer docs

• Sources:
• proxy302-mcp README (official Proxy302 MCP server)

Install proxy302-mcp in Claude Code, Codex CLI and Cursor

proxy302-mcp is a local stdio server started with npx, so all three tools below start it as a process and pass it PROXY302_API_KEY. Replace <key id>:<secret> with your own API key. The key goes in the environment variable, never in a prompt.

Claude Code. The server name comes before -e, and -- separates Claude Code's options from the server command. -s user makes it available in all projects; leave it out for the current project only.

• Sources:
• Claude Code docs: Connect Claude Code to tools via MCP
• Codex docs: Model Context Protocol
• Cursor docs: Model Context Protocol

Claude Code: install command

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

Example only: replace <key id>:<secret> with your own key.

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

Install in Codex CLI

Codex CLI. Use the command, or write the same server into ~/.codex/config.toml.

Codex CLI: install command

codex mcp add proxy302 --env PROXY302_API_KEY="<key id>:<secret>" -- npx -y github:proxy302/proxy302-mcp

Example only: replace <key id>:<secret> with your own key.

• Sources:
• Codex docs: Model Context Protocol

Codex CLI: config.toml form

[mcp_servers.proxy302]
command = "npx"
args = ["-y", "github:proxy302/proxy302-mcp"]
env = { PROXY302_API_KEY = "<key id>:<secret>" }

The same server written into ~/.codex/config.toml.

• Sources:
• Codex docs: Model Context Protocol

Install in Cursor

Cursor. Add the server to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json inside one project.

Cursor: mcp.json

{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": [
        "-y",
        "github:proxy302/proxy302-mcp"
      ],
      "env": {
        "PROXY302_API_KEY": "<key id>:<secret>"
      }
    }
  }
}

Example only: replace <key id>:<secret> with your own key.

• Sources:
• Cursor docs: Model Context Protocol

Remote MCP endpoint

A remote MCP endpoint is also available at https://proxy302.com/v1/mcp, so nothing has to be installed. The client connects over Streamable HTTP and sends your Proxy302 API key in the Authorization header as Bearer <key id>:<secret>. Its 9 tools cover account balance and usage, country and region lists, products and prices, a rotating residential proxy for a country, your proxies with the exit address of each static IP, changing an IP, an IP purity check and a cost estimate checked against your wallet balance. None of them spends money; purchases stay in the console.

For the Claude and ChatGPT web apps there is a second address, https://mcp.proxy302.com/mcp, with a sign-in page. In Claude, open Settings → Connectors → Add custom connector; in ChatGPT, turn on developer mode and add a connector. Enter the address, and when the Proxy302 authorization page opens, paste the key from the API keys page of the console as <key id>:<secret> and approve. Deleting that key in the console ends the connection. Clients that send headers, such as Claude Code, Cursor and Dify, can use either address with the Authorization header.

• Sources:
• Proxy302 remote MCP endpoint

Claude Code: remote endpoint

claude mcp add --transport http proxy302 https://proxy302.com/v1/mcp --header "Authorization: Bearer <key id>:<secret>"

The --transport http and --header options are from the Claude Code MCP documentation. Cursor, VS Code, Codex and Gemini CLI take the same URL and Authorization header in their own MCP configuration.

• Sources:
• Claude Code docs: Connect Claude Code to tools via MCP
• Proxy302 remote MCP endpoint

Routing the MCP server's own traffic through a proxy

Giving a tool a proxy and sending an MCP server's own outbound requests through a proxy are two separate jobs. Most MCP servers are Node.js or Python programs that the client starts, and they receive the environment the client gives them, so that is where proxy variables go.

Node.js reads proxy variables only if you opt in. Set NODE_USE_ENV_PROXY=1 (Node v24.0.0 and v22.21.0 or later) or start Node with --use-env-proxy (v24.5.0 and v22.21.0 or later), and it reads HTTP_PROXY, HTTPS_PROXY and NO_PROXY. It accepts HTTP or HTTPS proxy URLs only, not SOCKS. Node 20 has no built-in support, so a server running on Node 20 does not pick these variables up.

Python is simpler. httpx and requests read the proxy environment variables by default. requests needs the requests[socks] extra if the proxy URL is SOCKS.

A client passes these variables to the server in its env block, next to the API key. The example is for a server that makes ordinary web requests:

• Sources:
• Node.js docs: command-line options and built-in proxy support
• Requests documentation: Advanced usage, proxies
• HTTPX documentation: Environment variables

env block with proxy variables for an MCP server

{
  "mcpServers": {
    "some-other-server": {
      "command": "npx",
      "args": ["-y", "your-mcp-server-package"],
      "env": {
        "NODE_USE_ENV_PROXY": "1",
        "HTTPS_PROXY": "http://USERNAME:PASSWORD@HOST:PORT",
        "HTTP_PROXY": "http://USERNAME:PASSWORD@HOST:PORT",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

Example only: replace HOST, PORT, USERNAME and PASSWORD with your own values. Use an HTTP proxy URL.

• Sources:
• Node.js docs: command-line options and built-in proxy support

The same variables on a command line

The same variables work on a command line:

Node.js: opting in on the command line

NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://USERNAME:PASSWORD@HOST:PORT node server.js

Example only: replace the placeholders with your own values.

• Sources:
• Node.js docs: command-line options and built-in proxy support

Test the two hops separately

The assistant's own connection and the server's outbound requests are two hops, so test them separately. Compare the exit country and ISP that a lookup shows with the region you asked for.

Measured exits: Proxy302 rotating residential, eight countries

This is Proxy302's hourly connectivity check, not a proxy302-mcp measurement: one request to Amazon per country through a rotating residential exit, on 3 November 2026 at 18:18 UTC. One sample per country, not an average; later checks will differ. Only the first three octets of an IP are public.

• Sources:
• Proxy302 hourly connectivity check

Which proxy type suits which tool call

Rotating residential suits reading public pages from many places, such as price pages, search results or documentation that differs by country. Traffic is bought by the gigabyte and each generated proxy draws on it; pick the country when you generate it.

A static ISP IP suits anything tied to one account: you lease the IP for 1 to 90 days and it stays the same during the lease. Datacenter IPs suit plain API calls where the network type does not matter.

A proxy changes only the network address a service sees. What an account may do, and whether it stays open, is decided by the platform.

• Sources:
• Proxy302 product facts and price list

How to do it with Proxy302

Rotating residential fits most proxy MCP work: the server asks for a proxy URL for a country and the traffic it uses is billed from your wallet. The product page describes the lines and countries.

• rotating residential page

How to do it with Proxy302: steps

1. Step 1

   Create an API key in the Proxy302 console (the page is /api-keys). It has two parts, a key id and a secret, written as <key id>:<secret>.

2. Step 2

   Run the install command for your tool from the section above, with your key in the environment variable.

3. Step 3

   Restart the tool if it asks you to, then ask the assistant to list the server's tools and to get a proxy URL for the country you need.

4. Step 4

   Check the exit with https://ipinfo.io/json through the proxy. The country field should match the country you chose. The guide to checking a proxy covers the other checkers.

   • check a proxy's IP and location

5. Step 5

   From mainland China, open the Helper from the Connect page, click 「一键加速」 (One-click boost) and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

proxy302-mcp is free. Rotating residential traffic costs from US$1.50 per GB on the Budget line and US$5 per GB on the Premium line, and larger packages are cheaper per GB. A static ISP IP costs US$0.50 for one day and US$7.99 for 30 days, 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 1 GB of rotating residential traffic or one IP for one day. A proxy does not lift a restriction, undo a ban or raise a limit.

• 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 Code proxy setup

How to run Claude Code behind an HTTP proxy: HTTPS_PROXY, NO_PROXY, settings.json for background agents, and the checks that show it works.

Using Codex CLI through a proxy

How to run OpenAI Codex CLI through an HTTP proxy with environment variables, make the setup permanent and fix common errors.

Browser Use Proxy: Run an Agent Through an HTTP Proxy

How to run a Browser Use agent through an HTTP proxy: the current ProxySettings API, one proxy per agent, Playwright and Playwright MCP options, time zone and language, and common errors.

Rotating residential proxies

Real household IPs in 195+ countries with state and city targeting. Rotate on every request or keep sticky sessions. From US$1.50/GB, US$1.35/GB at 100 GB. HTTP and SOCKS5.

View options and pricing