MCP Server & API

Connect IpnProxy to your AI assistant with the MCP server

The IpnProxy MCP server lets AI assistants manage your proxies and browse the web through them. Ask in plain language:

“How much residential traffic do I have left, and when will it run out at this rate?”
“Give me 20 sticky US proxies in New York, in user:pass@host:port format.”
“Rotate the IP on port 11003.”
“Open this product page through a German residential IP and summarize the price.”

The same key also works with the REST API for your own scripts.

1. Create an API key

Open Dashboard → API Keys.
Give the key a name (e.g. Claude Desktop) and choose its permissions:

Permission	Allows
Read (always on)	Balance, orders, usage, locations, generating proxy lists, fetching pages through your proxies
Manage	Rotating IPs, rebooting, changing allowed / whitelisted IPs, resetting the residential proxy password
Orders	Buying bandwidth and plans, extending proxies — paid from your balance only and capped by a daily spend limit you set

Copy the key. It is shown once; we only store a fingerprint of it.

Treat the key like a password. If it leaks, revoke it in Dashboard → API Keys — it stops working immediately.

2. Connect your AI assistant

The server runs on your computer with Node.js 20.18 or newer.

Claude Code
Claude Desktop
Cursor
Other clients

claude mcp add ipnproxy --env IPNPROXY_API_KEY=ipn_live_YOUR_KEY -- npx -y @ipnproxy/mcp-server

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "ipnproxy": {
      "command": "npx",
      "args": ["-y", "@ipnproxy/mcp-server"],
      "env": { "IPNPROXY_API_KEY": "ipn_live_YOUR_KEY" }
    }
  }
}

Restart Claude Desktop.

Add the same block to ~/.cursor/mcp.json (or Settings → MCP → Add new server).

Any MCP client that supports stdio servers works: run npx -y @ipnproxy/mcp-server with the IPNPROXY_API_KEY environment variable.

Tools

The assistant only sees the tools your key is allowed to use.

Account

Tool	What it does
`get_account`	Balance, key permissions and daily spend limit
`list_orders`	Orders across all products
`list_plans`	Plans and prices of a product

Residential

Tool	Permission	What it does
`residential_get_plan`	Read	Credentials, total / used / remaining GB
`residential_get_usage`	Read	Traffic and requests per hour or day
`residential_list_countries`	Read	Available countries
`residential_list_targets`	Read	States, cities, ZIP codes and ASNs inside a country
`residential_generate_proxies`	Read	Proxy lines, identical to the dashboard generator
`residential_list_allowed_ips`	Read	IPs allowed without a password
`residential_rotate_ip`	Manage	New IP for one sticky port
`residential_add_allowed_ip` / `residential_remove_allowed_ip`	Manage	Edit allowed IPs
`residential_reset_password`	Manage	New proxy password (old proxy lines stop working)
`residential_buy_bandwidth`	Orders	Buy GB with your balance

Sticky sessions are port based. Each sticky line uses its own port starting at 11000; rotate a session by its port. Rotating proxies get a new IP on every request.

Premium datacenter

Tool	Permission	What it does
`datacenter_list_orders`	Read	Active orders, threads and expiry
`datacenter_list_countries`	Read	Available countries
`datacenter_generate_proxies`	Read	Rotating or sticky proxy lines for an order
`datacenter_buy`	Orders	Buy a plan with your balance

Mobile

Tool	Permission	What it does
`mobile_list_orders`	Read	Active orders
`mobile_get_proxies`	Read	Endpoints of an order
`mobile_list_locations` / `mobile_list_carriers`	Read	Available locations and carriers
`mobile_update_whitelist_ip`	Manage	Change the whitelisted IP (once per 30 minutes)
`mobile_buy`	Orders	Buy ports with your balance

Premium mobile

Tool	Permission	What it does
`premium_mobile_list_orders`	Read	Active proxies with credentials and expiry
`premium_mobile_rotate_ip`	Manage	Change the IP
`premium_mobile_reboot`	Manage	Reboot the device
`premium_mobile_set_rotation_interval`	Manage	Automatic IP change every N minutes
`premium_mobile_extend`	Orders	Extend by one period with your balance

Browsing and testing (run on your computer)

Tool	What it does
`fetch_url`	Fetches a page through a proxy and returns markdown, text or HTML. Uses a rotating residential proxy in the country you choose, or any proxy line you pass.
`check_ip`	Shows the public IP a proxy exits from
`test_proxy`	Success rate, latency and exit IPs of a proxy

fetch_url does not run JavaScript and caps pages at 5 MB. Traffic counts towards your plan.

Safety

Spending is opt-in. Paid tools exist only for keys with the Orders permission, pay from your balance only, and stop at the key’s daily limit.
Price confirmation. Every paid tool requires max_price: the assistant has to show you the price first, and the purchase is refused if the real price is higher.
Untrusted pages. Pages fetched with fetch_url are marked as untrusted content so the assistant does not follow instructions hidden in them.
Emails. You get an email whenever a new API key is created on your account.

REST API

Base URL: https://api.ipnproxy.com/api/v1 — send the key as Authorization: Bearer ipn_live_YOUR_KEY (or X-API-Key).

curl https://api.ipnproxy.com/api/v1/residential/proxies \
  -H "Authorization: Bearer ipn_live_YOUR_KEY" \
  -G -d type=sticky -d country=us -d quantity=5 -d format=user:pass@host:port

Method	Path	Permission
GET	`/account`, `/orders`, `/products/{product}/plans`	Read
GET	`/residential`, `/residential/usage`, `/residential/countries`, `/residential/targets`, `/residential/proxies`, `/residential/allowed-ips`	Read
POST	`/residential/rotate-ip`, `/residential/allowed-ips`, `/residential/reset-password` · DELETE `/residential/allowed-ips`	Manage
POST	`/residential/buy`	Orders
GET	`/premium-datacenter/orders`, `/premium-datacenter/countries`, `/premium-datacenter/proxies`	Read
POST	`/premium-datacenter/buy`	Orders
GET	`/mobile/orders`, `/mobile/orders/{id}/proxies`, `/mobile/locations`, `/mobile/carriers`	Read
POST	`/mobile/buy`	Orders
POST	`/mobile/orders/{id}/whitelist-ip`	Manage
GET	`/premium-mobile/orders`	Read
POST	`/premium-mobile/orders/{id}/rotate`, `/reboot`, `/rotation-time`	Manage
POST	`/premium-mobile/orders/{id}/extend`	Orders

{product} is one of residential, premium-datacenter, mobile, premium-mobile. Limits: 120 requests per minute per key; 20 per minute for changes and purchases. Errors are JSON with a message: 401 invalid or revoked key · 403 missing permission or daily spend limit reached · 402 insufficient balance · 409 price above max_price · 422 validation error · 429 too many requests.

Proxies

AI & API

Proxy Configurations

Resources

1. Create an API key

2. Connect your AI assistant

Tools

Account

Residential

Premium datacenter

Mobile

Premium mobile

Browsing and testing (run on your computer)

Safety

REST API

​1. Create an API key

​2. Connect your AI assistant

​Tools

​Account

​Residential

​Premium datacenter

​Mobile

​Premium mobile

​Browsing and testing (run on your computer)

​Safety

​REST API

1. Create an API key

2. Connect your AI assistant

Tools

Account

Residential

Premium datacenter

Mobile

Premium mobile

Browsing and testing (run on your computer)

Safety

REST API