Products

Residential Proxies

10M+ real device IPs

Datacenter Proxies

Dedicated static IPv4

Mobile Proxies

Real 4G/5G carrier IPs

ISP Proxies

Static residential IPs

Rotating Proxies

Billions of IPv6 IPs

View all proxy types →

Pricing

Use Cases

Locations

Get Started — FreeLogin

Model Context Protocol

MCP Server for AI Agents

Let Claude, GPT, Cursor, and any MCP-compatible AI agent buy and manage proxies through natural language. No custom integrations required — just point your client at the server and start talking.

Quick StartView Installation

Works with:Claude DesktopClaude CodeCursorWindsurfAny MCP client

Overview

What MCP is and why it matters for proxy automation.

The Model Context Protocol (MCP) is an open standard that lets AI agents communicate with external services through a structured tool-call interface. Instead of building brittle prompt-based integrations, MCP gives your AI agent typed, documented tools it can call with confidence.

The 1001Proxy MCP Server bridges your AI client directly to 1001Proxy's proxy infrastructure. The agent can check your balance, browse available proxy types and countries, price out an order, place it, and retrieve credentials — all through natural-language conversation, with no custom code on your end.

Zero integration code

Add one JSON block to your AI client config and you are live.

Safe by default

Destructive tools like create_order require explicit user confirmation in the agent loop.

Full proxy lifecycle

12 tools covering purchasing, management, credentials, and billing.

Quick Start

Get up and running in three steps.

1

Get your API key

Log in to your 1001Proxy dashboard, navigate to Settings → API Keys, and create a new key. Copy it — you will need it in the next step.

Open Dashboard

2

Install the MCP server

Install globally with npm, or skip installation entirely and use npx (the server will be fetched automatically).

bash

npm install -g @1001proxy-mcp/server

3

Add config to your AI client

Open your Claude Desktop config file (claude_desktop_config.json) and add the server block below. Replace your_api_key_here with your actual key.

claude_desktop_config.json

{
  "mcpServers": {
    "1001proxy": {
      "command": "npx",
      "args": ["-y", "@1001proxy-mcp/server"],
      "env": {
        "PROXY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The 1001Proxy tools will appear automatically in the tool list.

Installation

Multiple install options and environment variable reference.

Global install (npm)

bash

No install (npx)

Use npx -y to run the latest version without installing anything globally. This is the recommended approach for most MCP client configs.

bash

npx -y @1001proxy-mcp/server

Environment variables

Variable	Required	Default	Description
PROXY_API_KEY	required	—	Your 1001Proxy API key.
PROXY_API_URL	optional	https://api.1001proxy.io/api/v1	Override the API base URL. Useful for self-hosted or staging environments.

Configuration

Config examples for every supported MCP client.

Claude Desktop

Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Claude Code

Add the server from your terminal with the claude mcp add command.

bash

claude mcp add 1001proxy \
  --command "npx -y @1001proxy-mcp/server" \
  --env PROXY_API_KEY=your_api_key_here

Cursor

Open Cursor Settings, go to Features → MCP Servers, and add the following JSON:

Cursor settings.json

Generic MCP client

Any client that follows the MCP spec can connect via stdio. Launch the server process and pipe stdin/stdout:

bash

PROXY_API_KEY=your_api_key_here npx -y @1001proxy-mcp/server

Available Tools

12 tools covering the full proxy lifecycle — from discovery to credential retrieval.

get_account

Account

Retrieve account information and current balance.

Params: None

list_proxy_types

Reference

List all available proxy types with current pricing.

Params: None

get_reference_data

Reference

Fetch countries, rental periods, and tariffs for a given proxy type.

Params: type: ipv4 | ipv6 | mobile | isp | resident

calculate_order

Orders

Preview the total cost of an order before committing. No balance deducted.

Params: type, countryId, periodId, quantity, protocol, tarifId

create_order

Orders

Place a new proxy order. Debits your balance immediately.

Params: type, countryId, periodId, quantity, protocol, tarifId, idempotency_key

list_orders

Orders

List existing orders with optional filters.

Params: page, per_page, status, type

get_order

Orders

Retrieve full details for a specific order.

Params: order_id

get_proxies

Proxies

Get the proxy host, port, and credentials for an order.

download_proxies

Proxies

Download the proxy list as a plain-text or CSV file.

Params: order_id, format: txt | csv

extend_order

Orders

Extend an active order's duration. Charges your balance.

Params: order_id, periodId

get_transactions

Account

Retrieve your balance transaction history (deposits, charges, refunds).

Params: page, per_page

get_deposit_addresses

Account

List your crypto deposit wallet addresses.

Params: None

Example Workflows

How an AI agent handles real proxy tasks end-to-end.

Workflow 1 — "Buy 10 datacenter proxies in the US"

User

Buy me 10 datacenter proxies in the United States for 30 days.

Agent

Calling get_reference_data to find the US country ID and the 30-day period ID for IPv4 proxies.

get_reference_data({ type: "ipv4" })
→ countryId: 1 (United States), periodId: 3 (30 days)

Agent

Pricing the order before committing.

calculate_order({
  type: "ipv4",
  countryId: 1,
  periodId: 3,
  quantity: 10,
  protocol: "http"
})
→ total: $3.00

Agent

10 US datacenter proxies (HTTP) for 30 days will cost $3.00. Your current balance is $45.20. Shall I proceed?

User

Yes, go ahead.

Agent

Placing the order.

create_order({
  type: "ipv4",
  countryId: 1,
  periodId: 3,
  quantity: 10,
  protocol: "http",
  idempotency_key: "ord_20260406_001"
})
→ order_id: "ord_abc123", status: "active"

Agent

Order placed. Fetching your proxy credentials now.

get_proxies({ order_id: "ord_abc123" })
→ 10 proxies returned

Agent

Done! Here are your 10 US proxies (HTTP, 30 days, expires 2026-05-06): user_abc:[email protected]:10001 user_abc:[email protected]:10002 ... (8 more)

Workflow 2 — "Check my balance and list active orders"

User

What's my balance and do I have any active proxy orders?

Agent

Fetching account info and active orders in parallel.

get_account()          → balance: $42.20
list_orders({ status: "active", per_page: 10 })
  → 3 active orders returned

Agent

Your balance is $42.20. You have 3 active orders: • ord_abc123 — 10x IPv4 US (expires 2026-05-06) • ord_def456 — 5x IPv6 DE (expires 2026-04-20) • ord_ghi789 — 2x Mobile UK (expires 2026-04-15)

Workflow 3 — "Download proxy list for order ord_abc123"

User

Download my proxy list for order ord_abc123 as a text file.

Agent

Calling download_proxies with txt format.

download_proxies({ order_id: "ord_abc123", format: "txt" })
→ plain-text proxy list returned

Agent

Here is your proxy list as plain text (host:port:user:pass format): us1.1001proxy.io:10001:user_abc:pass_xyz us1.1001proxy.io:10002:user_abc:pass_xyz ... (8 more) You can paste this directly into your scraper or bot config.

Troubleshooting

Solutions to the most common issues.

API key not set — tools return an auth error

Make sure the PROXY_API_KEY environment variable is set in your MCP client config. In Claude Desktop, check that the "env" block in claude_desktop_config.json contains your key and restart the app. The server will refuse all requests if the variable is missing or blank.

bash

# Verify the variable is set before running
echo $PROXY_API_KEY

# Or pass it inline for a quick test
PROXY_API_KEY=sk_live_... npx -y @1001proxy-mcp/server

Connection refused / server not found

Confirm that Node.js 18+ is installed and available on your PATH. The npx command must be able to reach the npm registry to download the package on first run. Check your network or corporate proxy settings if you are behind a firewall.

bash

# Check Node.js version (18+ required)
node --version

# Confirm npx works
npx --version

Rate limiting (429 responses)

The 1001Proxy API enforces per-minute rate limits. If your agent is calling tools in a tight loop, add a short pause between calls or reduce the frequency. The MCP server will surface the 429 status in the tool result so the agent can back off automatically.

bash

# The server returns structured error results:
{
  "error": "rate_limited",
  "message": "Too many requests. Retry after 10s.",
  "retryAfter": 10
}

Insufficient balance (402 on create_order)

Your account balance is too low for the requested order. Use get_account to check your current balance, then deposit funds via get_deposit_addresses and send crypto to the returned wallet address.

Ready to connect your AI agent?

Create your account, fund your balance, and have an AI agent buying proxies in under five minutes.

Create Free AccountREST API Docs