/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 gets401 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.- In Claude, open the Connectors settings and add a custom connector.
- Name it ProxyJam and paste
https://proxyjam.com/mcpas the server address. - Connect, sign in to ProxyJam and approve.
Claude Code
/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), enterhttps://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
/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.
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.X-API-Key: pj_… (or Authorization: Bearer pj_…) on every
request.
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\):
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
/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.
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 requireconfirm=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_indexis an index into the offer’soptionsfromlist_offersand is the primary way to choose a price and period for every offer kind; mobile rotating offers require it.period_daysis 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 bytarification_index, and only those can be paid withpayment_currency="STAR". - Bandwidth.
buy_proxy_bandwidthapplies 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 needsorders:write for these, as for the purchases above.
Wallet
End-to-end example: place an order
Three calls — discover, preview, confirm.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 viaresources/read.
Response formats
Tools that return tabular data acceptresponse_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.
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:
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 asToolError with the full
HTTP response body and the X-Correlation-ID. Example:
Idempotency
Every destructive tool that hits aPOST 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).
Troubleshooting
The client never asks you to sign in — check the address is exactlyhttps://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.