Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@proxy302-mcp Get me a rotating residential proxy in Germany for scraping"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your AI assistant a real residential-proxy toolbox. proxy302-mcp is a Model Context Protocol server for Proxy302: check your traffic and usage, browse countries and plans, get a rotating residential proxy URL for any country, list your proxies and static IPs, and fetch a web page through a proxy, all from Claude Code, Claude Desktop, Cursor or any MCP client.
v1 is deliberately read-only and spend-free: it never buys, renews or tops up anything. The one write it can do (creating a dynamic proxy credential) is free, off by default, and only bills traffic when you actually use it.
Create an API key in the Proxy302 console and note its key id and secret.
Install:
claude mcp add proxy302 -e PROXY302_API_KEY="<key id>:<secret>" -- npx -y proxy302-mcpRequires Node.js 20+.
claude_desktop_config.json:
{
"mcpServers": {
"proxy302": {
"command": "npx",
"args": ["-y", "proxy302-mcp"],
"env": { "PROXY302_API_KEY": "<key id>:<secret>" }
}
}
}~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"proxy302": {
"command": "npx",
"args": ["-y", "proxy302-mcp"],
"env": { "PROXY302_API_KEY": "<key id>:<secret>" }
}
}
}Related MCP server: atheris-mcp
Tool | What it does |
| Account, wallet (PTC) balance, remaining prepaid traffic, per-pool balance and daily usage for the last N days |
| Countries you can target, with ids and ISO codes (name filter) |
| States of a country, or cities of a state |
| Product lines and static IP plans (data center and residential) |
| A ready |
| Your dynamic proxies and static IPs, passwords masked unless asked |
| Request a URL through your proxy (optionally from a given country) and return Markdown, text or raw |
Not in v1, on purpose: purchases, renewals, top-ups.
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."
"Fetch https://example.com/pricing from a US exit and summarise it."
"List my static IPs that expire in the next 7 days."
get_dynamic_proxy returns host, port, username and password:
import { chromium } from 'playwright';
const browser = await chromium.launch({
proxy: { server: 'http://HOST:PORT', username: 'USERNAME', password: 'PASSWORD' },
});
const page = await browser.newPage();
await page.goto('https://ipinfo.io/json');
console.log(await page.textContent('body'));from browser_use import Agent, Browser, BrowserConfig
browser = Browser(config=BrowserConfig(
proxy={"server": "http://HOST:PORT", "username": "USERNAME", "password": "PASSWORD"},
))
agent = Agent(task="Open ipinfo.io and tell me the country", llm=llm, browser=browser)fetch_url is a plain HTTP request without JavaScript rendering. For JavaScript-heavy sites, hand the proxy URL to a browser as above.
Variable | Meaning |
| Required. |
| Optional; use with |
| Optional; default |
Credentials are read from the environment only. Never commit them. Requests identify themselves with User-Agent: proxy302-mcp/<version> and X-Proxy302-Client.
npm install
npm run build
npm test
PROXY302_API_KEY="<id>:<secret>" npm run smoke # read-only checks against the live APIMIT
Request a URL from your machine through one of your Proxy302 proxies (optionally exiting in a given country) and return the page as Markdown, plain text or raw. No JavaScript rendering: for JS-heavy sites use a browser with the proxy URL from get_dynamic_proxy. Uses your proxy traffic.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| format | No | markdown | |
| country | No | Exit country; picks one of your dynamic proxies for it | |
| token_id | No | Use a specific proxy from list_my_proxies | |
| max_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and open-world natures, yet the description adds real context: requests are made from the user's machine, traffic is consumed from the proxy quota, and JS content will not render. It doesn't cover error behavior or truncation semantics beyond max_chars, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, followed by the caveat and alternative. Efficient, though the parenthetical about exiting country interrupts the main clause slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does state the return shape (page as Markdown/text/raw), which is the key missing piece. Quota consumption and the no-JS limitation are disclosed; pagination/truncation behavior is only implied by max_chars.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 40%; the description adds meaning for format (markdown/text/raw) and country exits, but token_id and max_chars are left to the schema, and max_chars has no description at all. Adequate but not compensating for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (request a URL through a Proxy302 proxy) plus the return forms (Markdown, plain text, raw), and distinguishes itself from get_dynamic_proxy for JS-heavy sites. An agent can tell what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the exclusion case (no JavaScript rendering) and points to the alternative route via get_dynamic_proxy. It lacks a positive when-to-use statement relative to the other siblings, but the routing guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the account tied to the API key, wallet balance (PTC), remaining prepaid traffic, and traffic used per day for the last N days. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many past days of usage to include |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description repeats 'Read-only' but adds useful scope about what data is returned, though it does not describe authentication requirements, response shape, or rate limits. With annotations carrying the behavioral burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence followed by a short safety note. Every element contributes: the enumerated data fields tell the agent what to expect, and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one fully documented parameter and annotations covering safety, the description is nearly complete. It lists the returned data categories, though without an output schema it could do slightly more to describe the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema fully documents the single 'days' parameter with default, minimum, and maximum. The description's phrase 'last N days' mirrors the schema but adds no syntax, constraints, or interpretation beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Show') and enumerates the exact resources returned: account, wallet balance (PTC), remaining prepaid traffic, and daily traffic usage. No sibling tool overlaps with account usage, so an agent can identify this as the account/billing endpoint without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the listed return data — an agent would call this when it needs account identity, balance, or prepaid traffic. However, the description does not state when to use this versus alternatives or mention any prerequisites beyond being tied to an API key.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a ready-to-use rotating residential proxy URL for a country (optionally state/city). Reuses an existing matching proxy of yours; with create_if_missing=true it creates a new credential if none exists (creating is free, traffic is billed only when used from your prepaid pool).
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | ||
| line | No | budget | |
| state | No | ||
| country | Yes | Country name, ISO code or id, e.g. "United States" or "US" | |
| protocol | No | http | |
| create_if_missing | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description is consistent with them. On top of that it discloses non-obvious behavior: credential reuse when a match exists, free creation, and that traffic is billed from a prepaid pool only when used. It omits rotation/expiry behavior of the returned URL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler, front-loading the return value and then the reuse/create semantics. Every clause carries information an agent would otherwise have to guess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly identifies the return value as a proxy URL, which covers the essentials. However, for a 6-parameter tool with 17% schema coverage, the budget/premium traffic distinction and protocol selection go unexplained, and nothing is said about how long a returned credential stays valid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, with country being the lone documented parameter, so the description must compensate. It adds real meaning for create_if_missing and implicitly covers state/city scoping, but says nothing about line (budget vs premium) or protocol (http vs socks5), which are meaningful choices affecting cost and client compatibility.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: return a ready-to-use rotating residential proxy URL scoped to a country (optionally state/city). That is clearly distinguishable from list_countries, list_regions, and get_account_usage. It stops short of explicitly contrasting with list_my_proxies, which is the sibling an agent might confuse it with.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear operating context: reuse an existing matching proxy by default, and set create_if_missing=true only when none exists. It does not name any alternative tool or state when-not-to-use it, so it lands at 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List countries Proxy302 can target. Optional name filter (substring). Returns ids usable in other tools. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Filter, e.g. "ger" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so "Read-only" in the description merely repeats structured data. What does add value is the downstream note that returned ids feed other tools. Nothing is said about result size, ordering, or behavior when the filter matches nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short front-loaded sentences with the scope stated first and the filter and return semantics after. The trailing "Read-only" sentence is redundant with the annotations and is the one piece that doesn't earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-param read tool with no output schema, the description covers purpose, filtering, and the shape of returned values (ids usable downstream). Only the relationship to list_regions and the no-match/ordering behavior remain unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already gives an example ("ger"), so the baseline is 3. The description's "(substring)" does clarify match semantics beyond the schema, but that is a marginal gain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource ("List countries Proxy302 can target") and adds the key qualifier that results are usable as ids in other tools. It does not, however, distinguish itself from the sibling list_regions, which an agent could plausibly confuse with country listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "Returns ids usable in other tools" implies a discovery-then-use workflow, which is useful context. But there is no explicit when-to-use guidance and no statement of when to prefer list_regions or how the two differ.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List proxies on the account: dynamic or static, billed by traffic or by IP. Passwords are masked unless include_credentials=true. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | static | |
| page | No | ||
| billing | No | ip | |
| page_size | No | ||
| active_only | No | ||
| include_credentials | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so "Read-only" is redundant, but the description adds a genuinely non-obvious behavior: passwords are masked unless include_credentials=true. That is a security-relevant disclosure an agent could not derive from the schema, which carries a bare boolean with no description. It stops short of covering pagination or what an empty result means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short clauses, each carrying distinct information, with the resource and scope front-loaded and the credential caveat immediately after. Nothing is wasted or repeated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six optional params, zero schema descriptions, and no output schema, the description covers the interesting filters but leaves pagination and the active_only default unexplained. An agent could call it correctly for the happy path but would not know that inactive proxies are excluded by default or how to page through large accounts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across six parameters, so the description must compensate and it only partially does: it explains include_credentials' effect and maps to the kind and billing enums. page, page_size, and especially active_only (which defaults to true and silently hides inactive proxies) get no explanation anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List proxies on the account") and enumerates the two axes it can be sliced by (dynamic/static, billed by traffic/IP). It is clear what the tool returns, but it never distinguishes itself from the sibling get_dynamic_proxy, which an agent could plausibly confuse it with for a single-proxy lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the description says what can be listed but never says when to reach for this versus get_dynamic_proxy or get_account_usage. The one guidance-like statement is the include_credentials condition, which is really a behavior note rather than a when-to-use rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe the proxy products and list the static IP plans (data center and residential) with their plan ids. Read-only; prices are shown on proxy302.com.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read-only' in the description is redundant. The one genuinely additive note is that prices are not returned and must be read on proxy302.com, which tells the agent what the output will lack — useful but a single sentence of extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action, with the price caveat and read-only note last. Slight redundancy between 'describe the proxy products' and 'list the ... plans', but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description does the needed work: it names the two categories of plans, says plan ids are included, and warns prices are absent. An agent has enough to call it and interpret the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no filtering inputs are needed since the entire catalog is returned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource pair: describe proxy products and list static IP plans (data center and residential) with their plan ids. The catalog scope is clearly distinct from siblings like list_my_proxies or list_countries, though it never explicitly names those siblings to reinforce the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied — an agent can infer this is the discovery step to get plan ids before selecting a plan, but the description does not say when to call it versus list_my_proxies or get_dynamic_proxy. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List states of a country, or cities of a state. Pass either country (name/code/id) or state_id. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| country | No | Country name, ISO code or id; lists its states | |
| state_id | No | State id; lists its cities |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the trailing 'Read-only' restates structured data and earns little. The description does add the useful detail that country accepts a name, ISO code, or id, but it never explains the zero-argument case or whether results are paginated or complete, which matters for a list tool with all-optional params.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core capability, then the parameter routing, then the safety note. Nothing is padded and the most decision-relevant information comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-mode read lookup with a documented schema and no output schema, this covers the essential contract: what it returns (states or cities) and how to select each mode. The unaddressed zero-argument case and the 'name' parameter are the only gaps, and both are minor for a read-only listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%; 'country' and 'state_id' are documented in the schema and the description mirrors that ('name/code/id'), adding only the name-or-code flexibility which the schema already implies. The third parameter, 'name', is undocumented in both places, and the description gives no indication of what it does, leaving a real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb plus resource pair — lists states of a country or cities of a state — which is more precise than the generic tool name 'list_regions'. It implicitly separates itself from the sibling list_countries by scoping to sub-country regions, but never names that sibling, so differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Pass either country (name/code/id) or state_id' gives clear, actionable guidance on which parameter drives which behavior, which is the main usage decision for this tool. What it omits is the failure mode: it does not say what happens if neither is passed (all three params are optional), nor does it point at list_countries as the alternative for country-level results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0fetch_urlget_account_usageget_dynamic_proxylist_countrieslist_my_proxieslist_productslist_regionsScored across 7 tools
Most tools are cleanly separated by resource and action: geo lookups (list_countries/list_regions), catalog (list_products), account state (get_account_usage/list_my_proxies), and actions (get_dynamic_proxy/fetch_url). The only mild overlap is between get_dynamic_proxy and list_my_proxies, since get_dynamic_proxy may reuse an existing proxy, but the descriptions make the boundary (return a usable URL vs. enumerate proxies) clear enough.
All names follow a consistent snake_case verb_noun pattern (get_*, list_*, fetch_url). The verb choice matches read-only vs. action semantics predictably. Minor quirks like 'my' in list_my_proxies don't break the pattern.
Seven tools is a tight, well-scoped surface for a proxy service: discovery, account state, credential retrieval, and a fetch helper. Every tool maps to a distinct step in a plausible workflow, with no obvious filler.
The read/lookup and proxy-use lifecycle is covered, but there are notable gaps: list_products exposes static IP plan ids yet there is no tool to order/purchase a static plan, and there is no delete/revoke operation for proxies or credentials. Agents can still accomplish core scraping workflows but hit dead ends on provisioning and cleanup.
Free proxy list, live proxy checker and IP lookup for AI agents. No key, nothing to install.
Create and manage residential and mobile proxies: geo targeting, usage limits, spend reports.
Proxy-rotated web scraping and cross-platform intelligence for AI agents.
Residential and static proxies: check usage, build proxy URLs, open tickets, get payment links.
