Proxies for AI Agents: MCP, Claude Code, Codex, Cursor

Install in your AI client

Two ways in: connect to the remote endpoint (nothing to install), or run proxy302-mcp on your own computer. Both need a Proxy302 API key.

Create an API key on the API keys page of the console, then put it in the command or config below as <key id>:<secret>. API keys
Keep the key in the environment variable as shown. Do not paste it into a chat or commit it to a repository.
Connect your client straight to https://proxy302.com/v1/mcp. It uses Streamable HTTP; send your API key in the Authorization header as Bearer <key id>:<secret>. No Node.js needed.
https://proxy302.com/v1/mcp
Run in a terminal.
```
claude mcp add --transport http proxy302 https://proxy302.com/v1/mcp --header "Authorization: Bearer <key id>:<secret>"
```
Add to ~/.codex/config.toml, then set PROXY302_API_KEY in the shell that starts Codex.
```
# ~/.codex/config.toml
[mcp_servers.proxy302]
url = "https://proxy302.com/v1/mcp"
bearer_token_env_var = "PROXY302_API_KEY"

# then, in the shell that starts codex:
export PROXY302_API_KEY="<key id>:<secret>"
```
Add to ~/.gemini/settings.json.
```
{
  "mcpServers": {
    "proxy302": {
      "httpUrl": "https://proxy302.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer <key id>:<secret>"
      }
    }
  }
}
```
Add to ~/.cursor/mcp.json.
```
{
  "mcpServers": {
    "proxy302": {
      "url": "https://proxy302.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer <key id>:<secret>"
      }
    }
  }
}
```
Add to CursorOpens Cursor with the remote server filled in. Then replace <key id>:<secret> in ~/.cursor/mcp.json with your key.
Add to .vscode/mcp.json; VS Code asks for the key the first time.
```
{
  "inputs": [
    {
      "type": "promptString",
      "id": "proxy302-key",
      "description": "Proxy302 API key (<key id>:<secret>)",
      "password": true
    }
  ],
  "servers": {
    "proxy302": {
      "type": "http",
      "url": "https://proxy302.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:proxy302-key}"
      }
    }
  }
}
```
In Claude (web and Desktop) and ChatGPT, add https://mcp.proxy302.com/mcp as a custom connector: in Claude, Settings → Connectors → Add custom connector; in ChatGPT, a connector in developer mode. The Proxy302 authorization page asks for your API key as <key id>:<secret>; deleting the key in the console ends the connection.
https://mcp.proxy302.com/mcp
In the Cline panel: MCP Servers > Configure > Configure MCP Servers.
```
{
  "mcpServers": {
    "proxy302": {
      "type": "streamableHttp",
      "url": "https://proxy302.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer <key id>:<secret>"
      }
    }
  }
}
```
9 tools
- 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, scored the same way as on the order page
- A cost estimate checked against your wallet balance
None of them spends money: purchases stay in the console.
proxy302-mcp runs on your own computer and starts when your AI client needs it. You need Node.js 20 or later and a Proxy302 API key.
Run in a terminal. -s user makes it available in every project.
```
claude mcp add proxy302 -s user -e PROXY302_API_KEY="<key id>:<secret>" -- npx -y github:proxy302/proxy302-mcp
```
Run in a terminal. Codex saves it to ~/.codex/config.toml.
```
codex mcp add proxy302 --env PROXY302_API_KEY="<key id>:<secret>" -- npx -y github:proxy302/proxy302-mcp
```
Add to ~/.gemini/settings.json, or to .gemini/settings.json inside a project.
File: ~/.gemini/settings.json
```
{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": [
        "-y",
        "github:proxy302/proxy302-mcp"
      ],
      "env": {
        "PROXY302_API_KEY": "<key id>:<secret>"
      }
    }
  }
}
```
Add to ~/.cursor/mcp.json, or to .cursor/mcp.json inside a project.
File: ~/.cursor/mcp.json
```
{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": [
        "-y",
        "github:proxy302/proxy302-mcp"
      ],
      "env": {
        "PROXY302_API_KEY": "<key id>:<secret>"
      }
    }
  }
}
```
Add to CursorOpens Cursor with the server filled in. Then replace <key id>:<secret> in ~/.cursor/mcp.json with your key.
Add to .vscode/mcp.json, or to your user configuration with the command "MCP: Open User Configuration". VS Code asks for the key the first time the server starts.
File: .vscode/mcp.json
```
{
  "inputs": [
    {
      "type": "promptString",
      "id": "proxy302-key",
      "description": "Proxy302 API key (<key id>:<secret>)",
      "password": true
    }
  ],
  "servers": {
    "proxy302": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "github:proxy302/proxy302-mcp"
      ],
      "env": {
        "PROXY302_API_KEY": "${input:proxy302-key}"
      }
    }
  }
}
```
Open Settings > Developer > Edit Config, add this, then quit and reopen Claude Desktop.
File: claude_desktop_config.json
```
{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": [
        "-y",
        "github:proxy302/proxy302-mcp"
      ],
      "env": {
        "PROXY302_API_KEY": "<key id>:<secret>"
      }
    }
  }
}
```
In the Cline panel, click the MCP Servers icon, open Configure and click Configure MCP Servers, then add this.
File: cline_mcp_settings.json
```
{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": [
        "-y",
        "github:proxy302/proxy302-mcp"
      ],
      "env": {
        "PROXY302_API_KEY": "<key id>:<secret>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```
What it adds
get_account_usage
Wallet balance, remaining traffic and daily usage
list_countries
Countries you can target, with their codes
list_regions
States of a country, or cities of a state
list_products
Product lines and static IP plans
get_dynamic_proxy
A ready http://user:pass@host:port rotating residential URL for a country
list_my_proxies
Your dynamic proxies and static IPs, with passwords masked
fetch_url
Fetch a page through your proxy, from a given country if you like, as Markdown or text (no JavaScript rendering)
It cannot buy anything or spend your wallet. Its only write, creating a dynamic proxy credential, is free and off by default; traffic is billed only when you use it.
Then ask your assistant
- How much proxy traffic do I have left, and what did I use this week?
- Which countries can I use? Get me a Germany proxy.
- What does a 30-day static ISP IP cost, and which plans are there?

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. Developer docs Source on GitHub

Using the proxy from mainland China? Turn on One-click boost in the Helper first. Helper guide

Paid accounts get 1 PTC the first time a call through MCP succeeds, once per account, while the offer runs.

Sources:
Claude Code docs: MCP
Codex docs: MCP
Gemini CLI docs: MCP servers
Cursor docs: MCP
VS Code docs: MCP servers
Cline docs: configuring MCP servers
proxy302-mcp source code

Proxy302 at a glance for agent work

Scroll horizontally with the arrow keys to read all content.

Proxy302 at a glance for agent work
Item	Price	Protocols	Locations	Fits agent work like
Rotating residential	From US$1.50 per GB (Budget line); US$5 per GB (Premium line); lower per GB in larger packages	HTTP, SOCKS5	195+ countries and regions; state and major city on lines that support it	Browsing and research agents, data collection
Static ISP, per IP	US$0.50 for 1 day, US$7.99 for 30 days, the same in every country	HTTP or SOCKS5, chosen per IP	30 countries on the order form; stock changes daily	One fixed IP for each account an agent signs in to
ISP for AI subscriptions	Per 30 days: Claude 15 PTC, GPT / Grok 10 PTC, Gemini 8 PTC; the first order in each tier is 50% off	HTTP or SOCKS5	Claude: US, UK, DE, JP. GPT / Grok: US, UK, FR, JP, KR. Gemini: US, UK, FR, JP	Coding tools and agents signed in to ChatGPT, Claude, Gemini or Grok
Datacenter, per IP	US$0.25 for 1 day, US$3.99 for 30 days	HTTP or SOCKS5, chosen per IP	8 countries	API calls and tool traffic where the IP type does not matter
proxy302-mcp	Free, open source (MIT)	MCP over stdio, started with npx	Uses the products above	Lets Claude Code, Codex, Cursor and other MCP clients get a proxy and fetch pages through it

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 8 November 2026.

Agents that open a browser

Browser Use, Playwright MCP and other browser agents take a proxy URL with a username and password; use the HTTP endpoint for that. Give each agent its own rotating residential proxy, check the exit country on an IP lookup page first, and keep one IP for a multi-step task.

Data collection

Ask the assistant to fetch a public page from another country with the fetch_url tool, or point the crawler that feeds your retrieval pipeline at a rotating residential proxy. Follow each site's terms and robots.txt, and keep request rates reasonable.

AI subscriptions

Claude Code, Codex and Gemini CLI run on your own subscription account. Use one fixed ISP IP for each account, in a country the provider supports. A proxy changes only the network address the service sees; the provider's terms and supported-country list still apply.

FAQ

What is an AI-native proxy?

A proxy your AI tools can use on their own: through MCP tools inside the assistant, such as getting a proxy for a country or fetching a page through it, or as a proxy URL that an agent's browser or command-line tool sends its traffic through.

Does Proxy302 have an MCP server?

Yes, in two forms. The remote endpoint https://proxy302.com/v1/mcp needs no install: add it to your client with your API key in the Authorization header; it has 9 tools, and none of them spends money. proxy302-mcp is the open-source version that runs on your own computer, with 7 tools. Both are official and maintained by the Proxy302 team.

Can the MCP server spend my balance?

No. It cannot buy anything or spend the wallet. Its only write, creating a dynamic proxy credential, is free and off by default, and traffic is billed only when you use it.

Which proxy should my agent use?

Rotating residential for reading public pages from many countries, a fixed static ISP IP for each account an agent signs in to, and datacenter or no proxy for plain API calls. The table above lists prices and protocols.

Do AI coding tools work with SOCKS5?

Use the HTTP endpoint. Anthropic's Claude Code documentation says Claude Code does not support SOCKS proxies, and Playwright accepts a username and password only for HTTP proxies, so browser agents need the HTTP endpoint too.

Sources:
Claude Code docs: network configuration
Playwright docs: HTTP proxy

Is there a free trial?

No. The smallest purchase is 1 GB of rotating residential traffic or one IP for one day. The MCP server itself is free.

Will a proxy let me use an AI service where it is not offered?

A proxy changes only the network address a service sees. Each AI provider's terms and supported-country lists still apply, and account decisions are made by the provider.

Reference links

9

Claude Code docs: MCP
Official documentation · Confirmed on: 2026-11-04
Claude Code docs: network configuration
Official documentation · Confirmed on: 2026-11-04
Codex docs: MCP
Official documentation · Confirmed on: 2026-11-04
Gemini CLI docs: MCP servers
Official documentation · Confirmed on: 2026-11-04
Cursor docs: MCP
Official documentation · Confirmed on: 2026-11-04
VS Code docs: MCP servers
Official documentation · Confirmed on: 2026-11-04
Cline docs: configuring MCP servers
Official documentation · Confirmed on: 2026-11-04
Playwright docs: HTTP proxy
Official documentation · Confirmed on: 2026-11-04
proxy302-mcp source code
Official documentation · Confirmed on: 2026-11-08

Install in your AI client

9 tools

What it adds

Then ask your assistant

Proxy302 at a glance for agent work

Agents that open a browser

Data collection

AI subscriptions

FAQ

Setup guides

Reference links

Ready to connect?