Skip to main content
The MCP server is a Model Context Protocol façade over the public API. The catalog, order and wallet actions are exposed as 16 MCP tools, so LLM agents can list catalog offers, place orders, manage proxies and inspect wallet balances directly, without you hand-writing HTTP calls. The server is a thin proxy in front of /public/v1: same idempotency, same rate limits, and the same scopes enforced again by the API.
Type the URL exactly as shown, with no trailing slash. https://mcp.proxyjam.com/mcp is the same server and keeps working as the direct address, but a connection signed in on one host does not carry over to the other.

Connect with sign-in

Clients that offer Sign in for a remote MCP server connect with just the URL — no API key copied anywhere. A client that connects with no credential gets 401 Unauthorized, and clients that support MCP authorization start the sign-in themselves. See OAuth and agent registration for the protocol underneath. On the consent screen:
  • Reading is on by default: the catalog, your account details, and your wallet balances and transactions.
  • Your orders (including proxy logins and passwords) are on by default for apps ProxyJam has verified (claude.ai, ChatGPT). For any other app, including one on your own computer such as Claude Code, they are a separate, unticked Show my orders and proxies box; ticking spending ticks it too.
  • Spending is off by default. Tick Allow spending from my wallet only if you want the assistant to place orders, extend proxies, buy bandwidth, or change a proxy’s settings. Paid actions still preview first and charge only after you confirm.

claude.ai and Claude Desktop

They share one list of connectors.
  1. In Claude, open the Connectors settings and add a custom connector.
  2. Name it ProxyJam and paste https://proxyjam.com/mcp as the server address.
  3. Connect, sign in to ProxyJam and approve.
A connector added on claude.ai is also available in Claude Desktop and the Claude mobile apps signed in to the same account.

Claude Code

Then type /mcp in Claude Code, pick proxyjam and choose Authenticate. Your browser opens the ProxyJam consent screen; Claude Code gets the result on a local address, so the screen warns that access goes to an app on your computer. Approve only if you just started the sign-in yourself. Add --scope user to use it in every project.

ChatGPT

In ChatGPT’s settings, create a custom connector (developer mode), enter https://proxyjam.com/mcp as its URL and choose OAuth authentication. ChatGPT identifies itself and opens the ProxyJam sign-in.

Cursor

~/.cursor/mcp.json, or .cursor/mcp.json in a project. Cursor asks you to sign in when it first connects.

Codex CLI

The second command opens your browser to sign in.

Gemini CLI

Then type /mcp auth proxyjam in Gemini CLI to sign in.

Allow spending later

Each approval replaces the previous one, so to turn spending on (or off), reconnect with the box set the way you want:
  • claude.ai / Claude Desktop: in Settings → Connectors, disconnect ProxyJam and connect it again.
  • Claude Code: /mcp → proxyjam → Re-authenticate.
  • ChatGPT: reconnect the connector.
  • Cursor, Codex CLI, Gemini CLI: sign in again the same way you connected.
Access tokens last 15 minutes and the client refreshes them on its own; your granted scopes don’t change until you reconnect. A tool that needs spending while it is off returns: This tool needs the orders:write scope. Spending is not enabled for this connection. Reconnect ProxyJam and tick “Allow spending from my wallet”.

See and revoke connections

Every connection is listed under Settings → Connected apps in your dashboard, with its scopes and last use. Revoking one stops it within 5 minutes, while your other connections keep working. Changing your password or signing out everywhere revokes all of them. Details: OAuth and agent registration.

Connect with an API key

For clients that cannot sign in, or for scripts. An API key has the full access of your account, spending included. Generate one in your dashboard → API Keys, then keep the raw value safe — it is shown only once. See Authentication for the full flow.
Send it as X-API-Key: pj_… (or Authorization: Bearer pj_…) on every request.
A dashboard API key has no narrower permissions: it reads and spends. Prefer signing in where your client supports it, and give any key an agent uses an expiry date.

Claude with a key

Add the custom connector as above (https://proxyjam.com/mcp), but instead of signing in, open Request headers, add a header named X-API-Key with your key, and connect. If your version of Claude Desktop has no Request headers field, bridge to the remote endpoint with mcp-remote instead (needs Node.js; this fallback is for Claude Desktop only). Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
The key goes through env rather than straight into args so the header has no space in it — some platforms split arguments on spaces. Restart Claude Desktop; the ProxyJam tools appear in the tools menu.

Claude Code with a key

Then /mcp to see registered servers, or just ask Claude something like “list my proxy orders” — it will discover and call the right tool.

VS Code

.vscode/mcp.json, with an API key. VS Code asks for the key once and stores it securely.

OpenAI Agents SDK

With an API key.

Generic FastMCP client (Python)

auth="oauth" opens your browser to sign in; pass headers={"X-API-Key": "pj_..."} instead to use a key.

Agents without an account

An agent with no account behind it can also register a key of its own that only reads the catalog, then ask a person to claim it into their account with an emailed code. It never spends. Full steps: Agent registration (machine-readable summary: auth.md).

Tool catalog

Money-spending tools default to dry-run. create_proxy_order, extend_proxy_period, and buy_proxy_bandwidth require confirm=true to actually charge the wallet. Without it they return a preview with the offer, current balance, and what would happen. Always supply an idempotency_key (any unique string, typically a UUIDv4) so retries replay the stored answer instead of double-charging.
When you signed in, each tool needs one scope: Every tool is listed whatever you granted; a call outside your scopes returns an error that names the missing one. An API key from the dashboard reaches every tool.

Catalog

list_offers

List available proxy offers, optionally filtered. Returns a flat table — one row per offer, with kind, id, name, country_code, mode, ip_version, is_available, currency, locations (JSON-encoded list of {region, city}, empty when none is known), and options (JSON-encoded list of tariff variants; each variant carries a price in the row’s currency). Use id as offer_id in create_proxy_order.
A location narrows the choice of ISP, not a delivery guarantee: an order is placed against the whole pool of the matched ISP, so a specific city is not guaranteed. While location filtering is not enabled for your platform, passing region or city returns the same 403 the HTTP API would (check the isp.city.enable flag via GET /flags first).

Orders

Reads

Destructive — dry-run by default

These require confirm=true + an idempotency_key to actually execute. Without confirm=true they return a preview and don’t touch the API mutation path. idempotency_key is 8–64 characters.
  • Picking a tariff. tarification_index is an index into the offer’s options from list_offers and is the primary way to choose a price and period for every offer kind; mobile rotating offers require it. period_days is the legacy alternative for residential and datacenter offers and must equal one of the offer’s option periods exactly.
  • Extending. Static (residential/datacenter) proxies extend by months; mobile rotating proxies extend by tarification_index, and only those can be paid with payment_currency="STAR".
  • Bandwidth. buy_proxy_bandwidth applies to static proxies only; a mobile rotating order rejects it.
  • External payment methods (cryptocloud, stripe, telegram_stars, rollypay) return a payment URL instead of charging the wallet — see Payment methods.

Non-destructive mutations

No dry-run because nothing is charged. A signed-in client still needs orders:write for these, as for the purchases above.

Wallet

End-to-end example: place an order

Three calls — discover, preview, confirm.
If step 3 errors out (network hiccup, etc.) you can safely retry with the same idempotency_key — the API returns the stored answer instead of creating a second batch of orders.

Reference resources

Static enums are exposed as MCP resources so they don’t bloat tool descriptions. Most clients let the agent fetch resources on demand via resources/read.

Response formats

Tools that return tabular data accept response_format:
  • csv (default) — one header row, one data row per record; nested values are JSON-encoded inside a single cell. Roughly half the tokens of equivalent JSON.
  • json — list of objects; use when you need to script over nested structures.
Non-list tools always return JSON.

Paginated tools

list_my_orders and list_wallet_transactions always wrap the rows in a pagination envelope so the LLM knows when more pages exist:
If has_more is true, request the next page with offset = previous offset + returned. Loop until has_more is false.

Errors

Tools surface upstream errors verbatim as ToolError with the full HTTP response body and the X-Correlation-ID. Example:
The LLM sees the entire body, so it can either retry with a corrected argument or pass the error back to the user with a clear explanation.

Idempotency

Every destructive tool that hits a POST endpoint takes idempotency_key. The MCP server forwards it as Idempotency-Key on the HTTP request, and the API persists (key, response) pairs. Replays return the original answer (so confirm=true on a previously created order won’t double-charge). Use a fresh key per logical operation:
  • Place an order → one key.
  • A retry of the same order → same key.
  • A different order → new key.

Out of scope

The MCP server intentionally does not expose:
  • /users/* and /auth/* — account management needs a signed-in session (a token from sign-in), not a key or an OAuth connection.
  • /payments/* — payment intents are user-initiated through the dashboard.
  • /api-keys/* — you cannot manage keys through a key (security).
If you need any of these, use the HTTP API directly.

Troubleshooting

The client never asks you to sign in — check the address is exactly https://proxyjam.com/mcp (no trailing slash; https://proxyjam.com/mcp/ is the web page). Clients without MCP authorization need an API key instead. 401 Unauthorized when connecting — neither a sign-in nor an API key reached the server. Sign in, or send the key as X-API-Key: pj_… (or Authorization: Bearer pj_…): in Claude Code re-run claude mcp add with --header; in Claude or Claude Desktop check Request headers, or your mcp-remote arguments in claude_desktop_config.json. Spending is not enabled for this connection — the connection was approved without Allow spending from my wallet. Reconnect and tick it (see Allow spending later). This API key cannot spend, or HTTP 403 with INSUFFICIENT_SCOPE — the key is an agent-registered key, which only reads. Use a dashboard API key or sign in. A read tool refuses an agent-registered key with “This tool needs the {scope} scope. This API key does not have it. Claim the key with the claim_token you received at registration, or use a dashboard API key.” — an unclaimed key only holds catalog:read, so list_my_orders and the other read tools are out of reach until the person claims it. HTTP 401 Invalid API key — the key is wrong, revoked, or expired. Generate a new one via the dashboard. Tools list is empty — the MCP client cached an old session. Restart the client or reconnect the server. HTTP 422 on list_offers — only the values listed in ref://offer-kinds are accepted for kind. Earlier docs mentioned mobile_rotating — that’s wrong, use mobile.