Prokso MCP server for AI agents

1. What MCP is

The Model Context Protocol (MCP) is an open protocol that AI apps use to connect external tools. The client (Claude Code, Cursor, Claude Desktop and others) asks the server which tools it has, and the model decides when to call them. You don't need to write code or learn the REST API: just tell the agent what you need.

The Prokso MCP server gives the agent read access to your account: balance, plans, traffic left and connection details. The most useful tool generates proxy lines with a country, city or carrier, already in the format your script or app expects.

2. Address and technical details

• Server address: https://prokso.com/api/v1/mcp.
• Transport: Streamable HTTP in request/JSON-response mode. Only POST, no event stream (SSE) and no sessions. On GET the server returns 405, which the spec allows and clients handle.
• Protocol versions: 2025-06-18 (main), 2025-03-26 and 2024-11-05.
• Sign-in: an API key in the Authorization: Bearer YOUR_API_KEY header (the X-API-Key header works too). There is no OAuth sign-in, so the client must be able to send a custom header.

To buy traffic or do anything else that involves money, use the REST API or the dashboard: the MCP server doesn't do that.

3. Tools

The server exposes five tools. All of them only read data and never spend money.

State, city, ZIP and carrier are precise geo: that traffic counts double. We don't guarantee that a specific city or provider is available. Ports, fixed-IP duration and parameter syntax are the same as in regular lines, see the username and ports reference.

4. API key

1. Open the dashboard and go to "Settings" > "API".
2. Click "Create key" and optionally give it a name, such as "Cursor on laptop".
3. Copy the key right away: it is shown in full only once.

You can have up to 5 keys per account. Create a separate key for each client or computer: if one device is lost, you revoke only its key and the rest keep working. You revoke a key in the same place, "Settings" > "API", with the "Revoke" button, and it stops working immediately.

5. Key security

• The key gives access to your account: with it, anyone can get your plans' username and password and proxy lines, which means spending your traffic. Keep it like a password.
• Store the key in an environment variable (for example PROKSO_API_KEY) and reference it from the client config. Then the config file is safe to commit.
• Don't commit the key to git or paste it into chats. If the key ends up in a public repository or a log, revoke it and create a new one.
• The agent sees everything the tools return, including the plan password. Connect the server only to clients you trust.

6. Limits

Limits are the same as in the REST API: up to 60 requests per minute per key. One tool call by the agent is one request to the server, plus a few service requests from the client when it connects. Over the limit, the server returns 429 with a Retry-After header that says how many seconds to wait. For normal work with an agent this limit leaves plenty of room.

The server also counts failed sign-in attempts: if one address sends a wrong key many times, its next requests also get 429 for a while.

7. Example requests to the agent

Once connected, just tell the agent what you need. It picks the tool and parameters itself:

• "How much traffic is left on my plans?"
• "What's my balance?"
• "Give me 5 SOCKS5 lines with fixed IPs in Poland for plan 12."
• "Generate 20 lines with a new IP on every request, country Germany, format host:port:username:password."
• "Show the connection details for plan 12 and tell me which ports keep a fixed IP."
• "Put a US proxy line into my script and check which IP it comes out from."

The agent can find the plan id itself with list_plans. If you ask for precise geo (city, state, carrier), the agent should warn you that the traffic counts double.

8. Clients and guides

The server works with any MCP client that supports remote servers over HTTP and lets you set an Authorization header. Step-by-step guides:

9. Check the server with curl

Before setting up a client, make sure the key works. This command asks the server for its list of tools:

curl -X POST https://prokso.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response should contain result with five tools:

{"jsonrpc": "2.0", "id": 1, "result": {"tools": [{"name": "get_account", "title": "Account and balance", ...}, ...]}}

The command is written for macOS and Linux. On Windows, run it in WSL or Git Bash: PowerShell handles quotes in JSON differently. A step-by-step proxy check is on the "Proxy not working" page.

10. Common errors

• 401 with Pass your API key in the header: the request has no key. The client didn't send the header or the environment variable is empty.
• 401 with Invalid or revoked API key: the key is wrong or revoked. Check that you copied it in full, with no spaces, and that it follows Bearer and a space.
• 429: the request limit is exceeded. Wait as many seconds as Retry-After says.
• 405 on GET: normal behavior, the server accepts only POST. Opening the address in a browser also gives 405.
• A tool returned an error text (for example about plan_id or an unknown city): this isn't a server failure, it's a hint for the agent to fix the parameters.

For any other error, message support and include the curl output with the key replaced by asterisks. Guides for apps without agents are in the "Guides" section.

MCP in Claude Code →How to use Prokso