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.
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.
Install the MCP server
Install globally with npm, or skip installation entirely and use npx (the server will be fetched automatically).
npm install -g @1001proxy-mcp/serverAdd 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.
{
"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)
npm install -g @1001proxy-mcp/serverNo install (npx)
Use npx -y to run the latest version without installing anything globally. This is the recommended approach for most MCP client configs.
npx -y @1001proxy-mcp/serverEnvironment 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).
{
"mcpServers": {
"1001proxy": {
"command": "npx",
"args": ["-y", "@1001proxy-mcp/server"],
"env": {
"PROXY_API_KEY": "your_api_key_here"
}
}
}
}Claude Code
Add the server from your terminal with the claude mcp add command.
claude mcp add 1001proxy \
--command "npx -y @1001proxy-mcp/server" \
--env PROXY_API_KEY=your_api_key_hereCursor
Open Cursor Settings, go to Features → MCP Servers, and add the following JSON:
{
"mcpServers": {
"1001proxy": {
"command": "npx",
"args": ["-y", "@1001proxy-mcp/server"],
"env": {
"PROXY_API_KEY": "your_api_key_here"
}
}
}
}Generic MCP client
Any client that follows the MCP spec can connect via stdio. Launch the server process and pipe stdin/stdout:
PROXY_API_KEY=your_api_key_here npx -y @1001proxy-mcp/serverAvailable Tools
12 tools covering the full proxy lifecycle — from discovery to credential retrieval.
get_accountRetrieve account information and current balance.
list_proxy_typesList all available proxy types with current pricing.
get_reference_dataFetch countries, rental periods, and tariffs for a given proxy type.
calculate_orderPreview the total cost of an order before committing. No balance deducted.
create_orderPlace a new proxy order. Debits your balance immediately.
list_ordersList existing orders with optional filters.
get_orderRetrieve full details for a specific order.
get_proxiesGet the proxy host, port, and credentials for an order.
download_proxiesDownload the proxy list as a plain-text or CSV file.
extend_orderExtend an active order's duration. Charges your balance.
get_transactionsRetrieve your balance transaction history (deposits, charges, refunds).
get_deposit_addressesList your crypto deposit wallet addresses.
Example Workflows
How an AI agent handles real proxy tasks end-to-end.
Buy me 10 datacenter proxies in the United States for 30 days.
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)Pricing the order before committing.
calculate_order({
type: "ipv4",
countryId: 1,
periodId: 3,
quantity: 10,
protocol: "http"
})
→ total: $3.0010 US datacenter proxies (HTTP) for 30 days will cost $3.00. Your current balance is $45.20. Shall I proceed?
Yes, go ahead.
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"Order placed. Fetching your proxy credentials now.
get_proxies({ order_id: "ord_abc123" })
→ 10 proxies returnedDone! Here are your 10 US proxies (HTTP, 30 days, expires 2026-05-06): user_abc:pass_xyz@us1.1001proxy.io:10001 user_abc:pass_xyz@us1.1001proxy.io:10002 ... (8 more)
What's my balance and do I have any active proxy orders?
Fetching account info and active orders in parallel.
get_account() → balance: $42.20
list_orders({ status: "active", per_page: 10 })
→ 3 active orders returnedYour 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)
Download my proxy list for order ord_abc123 as a text file.
Calling download_proxies with txt format.
download_proxies({ order_id: "ord_abc123", format: "txt" })
→ plain-text proxy list returnedHere 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.
# 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/serverConnection 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.
# Check Node.js version (18+ required)
node --version
# Confirm npx works
npx --versionRate 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.
# 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.