Claude Code Proxy: Managing Your Account from the Editor

Claude Code ships with a Model Context Protocol client built in, so pointing it at your LightningBytes account gives the assistant a set of tools it can call while you work: list sub-users, generate endpoints, read usage, check a proxy. The useful part is not that you can ask for a status; it is that the agent can fetch the connection details it needs and use them in the code it is already writing.

That removes the round trip through the dashboard that used to sit in the middle of a coding session. You describe the task, the agent asks the proxy account for the endpoint, and the snippet it produces already has the real host, port and credentials in it.

Install the MCP server

The MCP server is one Streamable HTTP endpoint, authenticated with the same API token the HTTP API uses. Create a token on the API Tokens tab of API & MCP in the dashboard, scope it to the products and pools you intend to use, and copy the value, because it is shown once.

Then register the server with Claude Code:

claude mcp add --transport http lightningbytes \
  https://www.lightningbytes.com/api/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Replace YOUR_TOKEN with the value you copied, including the word Bearer and the space. The token is not recoverable from the dashboard, so the placeholder is what ships in examples; the real value only ever goes in your own config.

Two things about that URL are worth stating. Use the www host exactly as written, because the apex redirects and an HTTP client drops the Authorization header when a redirect changes the host, which surfaces as a 401 on a perfectly valid token. And keep the transport flag: --transport http is how Claude Code selects Streamable HTTP.

Confirm the server registered and can list its tools:

claude mcp list

If the server appears but shows no tools, the header or the transport is wrong; that is the first thing to check.

Scope the token before the agent uses it

A token is not an account key. It carries an explicit set of product and pool pairs, and every tool call is checked against that list. A token scoped to residential on one pool cannot generate a mobile endpoint, and the agent cannot widen its own reach.

This matters more with a coding assistant than with a script, because the agent decides which tool to call. Create a token for the task at hand, scope it to the products that task needs, and give the agent that token rather than a broad one. The blast radius of a leaked token is then the products you scoped, not the whole account.

Ask for the connection info, do not paste it

With the server connected, a request can name the tools directly. For example:

Using the lightningbytes MCP server, list my sub-users, then generate one HTTP endpoint for the scraper sub-user targeting Germany. Show me the host, port, username and password.

The generate_endpoints tool returns one row per endpoint with the fields a client needs to connect: protocol, host, port, username, password, plus a combined credential string (host:port:username:password) and a ready url (protocol://username:password@host:port). Each row gets its own sticky session id by default, so N generated endpoints resolve to N different exit IPs.

The agent now has real values to work with. It can drop them into the code under construction instead of leaving a TODO for you to fill in later.

Use the endpoint while you code

The two shapes that cover most cases are a proxy dictionary in Python and a proxy option on a request. Both take the url form the tool returned.

import requests

proxy = "http://user:secret@proxy.lightningbytes.com:1080"
r = requests.get(
    "https://api.ipify.org?format=json",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
print(r.json())

import { ProxyAgent } from "undici";

const proxy = "http://user:secret@proxy.lightningbytes.com:1080";
const agent = new ProxyAgent(proxy);

// Node's fetch ignores proxy environment variables, so pass a dispatcher.
const res = await fetch("https://api.ipify.org?format=json", { dispatcher: agent });
console.log(await res.json());

If the destination is geo-sensitive, pass country, state or city to generate_endpoints and the exit IP is drawn from that market. The same call is what the dashboard's Endpoint Generator does, so the values match what you would copy by hand.

Verify before you trust it

Do not assume a generated endpoint works; ask the agent to check it. The check_proxy tool connects through the endpoint and reports the exit IP, the exit IP's country and the proxy-hop latency. It needs an active plan with a spendable balance, which is the same requirement the dashboard's per-row check has.

check_proxy(product="residential", pool="standard", protocol="http",
            host="proxy.lightningbytes.com", port=1080,
            username="user", password="secret")

Run this at the start of a session rather than at the end. A silent bypass and a working proxy look identical until you read the exit IP, and the whole point of routing the agent is that the address is the address you intended.

Rotate when a check fails

If an endpoint is refused, rotate_endpoints mints fresh session ids for the same sub-user, which gives the row a new exit IP. The agent can call it and re-check without a human in the loop.

Two habits keep that sane. Rotate a row, not the whole task, so a single bad exit does not invalidate the sessions the rest of the run depends on. And treat a 403 from the target differently from a failure through the proxy: a 403 means the destination refused the request, and a new exit IP will not change that answer. The distinction is the one in Fixing 403 Forbidden, and it saves a lot of pointless rotation.

Keep the proxy out of your source control

The token in the claude mcp add command is a live credential. Keep it out of anything tracked by git, and never paste it into a file you commit. On a machine where several projects share one token, an environment variable read at registration time is easier to rotate than a value baked into a shell history:

export LB_TOKEN="sk-lb_..."
claude mcp add --transport http lightningbytes \
  https://www.lightningbytes.com/api/mcp \
  --header "Authorization: Bearer $LB_TOKEN"

To revoke, delete the token on the API Tokens tab; the next call fails immediately. Create a replacement with the same scope and rerun the command. A token that ever reached a commit needs rotating, not deleting, because the object history keeps it.

The boundary: operate, do not spend

There is a line between what an agent should do unattended and what should ask a person, and spending money is on the far side of it. The MCP server exposes the operational surface and nothing financial: no tool can buy traffic, create a checkout, change a plan or read an invoice. When the balance runs low, get_topup_link returns the Add Traffic URL for a product, and a signed-in person completes the purchase.

That boundary is worth respecting in your own prompting too. An agent that can top up a balance on its own is one injected instruction away from buying traffic you did not intend, and the fix is not a better prompt but a tool that does not exist.

If a call fails

Branch on the code, not on prose. The server returns the same envelope as the HTTP API.

Two of those are configuration problems rather than transient ones. scope_denied is fixed on the API Tokens tab, not by retrying.

Getting started

Install the server, create a narrow token, and start with a read-only request: list sub-users, list the pools, read the usage overview. When the tool list looks right, ask for one endpoint, check its exit IP, and wire the returned url into a snippet. That is the whole loop, and it is the same account the dashboard shows, with the same sub-users, allocations and credentials.

For the endpoint, the token table and the per-client configs, see Using the MCP Server. For the same operations over plain HTTP, see The API and API Tokens. If you are deciding how much autonomy to hand the assistant, Giving an AI Agent Control of Your Proxy Account covers the design, and AI Agents and Proxies covers the failure modes. The Proxy Checker is the quick way to confirm what any endpoint is actually exiting from.