Using the MCP Server

Point an MCP client at the LightningBytes server so an agent can manage sub-users, endpoints and usage with an API token.

The MCP server lets an agent client manage your account directly instead of calling each HTTP endpoint itself. It is on the MCP tab of API & MCP in the dashboard (/dashboard/api?tab=mcp), next to API Tokens and API Reference.

It uses the same API tokens as the HTTP API and covers the same operational actions. Setup is one endpoint URL and one authorization header.

Before you start

Create a token on the API Tokens tab if you do not have one, and choose the product and pool pairs it may use. See The API and API Tokens for the token table and its scope.

The token value is shown once. Copy it when you create the key; the MCP tab uses the placeholder YOUR_TOKEN because the real value cannot be read back.

The endpoint and the header

Point a Streamable HTTP client at:

https://www.lightningbytes.com/api/mcp

Important

Use the www host exactly as written. The apex (lightningbytes.com) redirects to www, and an HTTP client drops the Authorization header when a redirect changes the host, so an apex URL fails with 401 even with a valid token.

Send the token as a bearer credential. The word Bearer is part of the header value, with a space before the token:

Authorization: Bearer YOUR_TOKEN

That is the whole contract. Every client guide on the MCP tab is just a different way to write those two lines.

Important

If you copy the token value alone into the Authorization header, without the Bearer prefix, every request fails with 401. The prefix is not optional, and the error says so.

Adding it to a client

The MCP tab lists a copy-ready block per client. Pick the one you use, replace YOUR_TOKEN, and paste it.

Client	Where it goes
Claude Code	Run the `claude mcp add` command once in a terminal
Roo Code / Zoo Code	Add the server to `.roo/mcp.json` in your project, or the global `mcp_settings.json`
Claude Desktop	`claude_desktop_config.json` runs local servers only, so the block bridges the endpoint with `mcp-remote`, then you restart the app
Cursor	Add the server to `.cursor/mcp.json` in your project, or the global config
VS Code	Add the server to `.vscode/mcp.json` in your workspace
Cline	Add the server to `~/.cline/mcp.json` for the CLI, or to the extension's MCP settings
Other clients	Use the URL and the Authorization header in whatever config shape the client expects

Each block has a Copy button. The block is the exact text to paste, so a wrong server entry is visible before you save it.

The field clients disagree about

The endpoint is Streamable HTTP, and clients differ on how they ask for it:

Roo Code and Zoo Code require an explicit "type": "streamable-http" on a url entry. They cannot infer the transport from a url alone, and an entry without type fails to load, so the tools never appear in the list. The block above includes the line.
Cline requires an explicit "type": "streamableHttp" on a url entry. Without it Cline silently falls back to the legacy SSE transport and the connection fails.
Cursor infers Streamable HTTP from the url and needs no type.
VS Code uses "type": "http".
Claude Desktop does not accept a url at all: its config file validates local (stdio) servers only, so an HTTP entry is dropped on the next save or crashes the app on load. Use the mcp-remote block, or register the endpoint as a Custom Connector in the app's settings.
Claude Code takes the transport on the command line (--transport http).

If a client lists the server but shows no tools, a missing or wrong type is the first thing to check.

What the agent can do

The tools are grouped the same way on the tab:

Group	Actions
Account and catalog	Read the token's identity and scope, list products and pools, and browse the places a pool supports with `list_locations`, `list_regions` and `list_cities` (each takes a product and a pool and returns only what that pool serves)
Sub-users	List, create and delete sub-users, reset a proxy password, enable or disable access, set a traffic allocation
Endpoints and checks	Generate proxy endpoints, rotate their exit IPs, check an endpoint's connectivity and exit IP
Usage	Read balances and traffic totals, read traffic and request history, break usage down by sub-user and by country

A failed call returns a code and a message, the same envelope the HTTP API uses, so the agent can branch on the code rather than parse a sentence.

Two boundaries worth knowing

Scope applies to MCP exactly as it does to the HTTP API. A token carries an explicit set of product and pool pairs. A tool call outside them is refused, and the agent cannot widen its own reach. If a call is denied, check the token's permissions on the API Tokens tab.

MCP is operational only. No tool can buy traffic, create a checkout, change a plan or read an invoice. That is deliberate: an agent should not be able to spend money. When the balance runs low, the agent can return the Add Traffic link for a product, and a signed-in person completes the purchase. See Buying Traffic.

Note

The endpoint is server to server. It reads no cookies and is not opened to browser cross-origin requests, so a client must send the Authorization header itself.

The optional event stream a client opens with GET ends after five minutes, and a token can hold eight at once; past that the oldest closes. MCP clients reconnect on their own, so neither limit needs any configuration.

If a call fails

Symptom	Cause
Server listed but no tools appear, or the config fails to load	A `url` entry with no `type`. Roo Code and Zoo Code need `"type": "streamable-http"`, Cline needs `"type": "streamableHttp"`; Claude Desktop needs the `mcp-remote` bridge instead of a `url`
`401 unauthorized`	Missing, revoked or expired token. Create a new one and update the client config
`401 unauthorized` with a valid, correct token	The URL uses the apex host, which redirects and drops the `Authorization` header. Use the `www` host
`401` naming the Bearer scheme	The header has the token but not the `Bearer` prefix. The message says so; add the prefix
`403 scope_denied`	The token is not scoped to that product or pool. Widen its permissions or use a different token
`403 no_entitlement`	The proxy check needs an active plan with a spendable balance
`409 not_provisioned`	The sub-user has no active proxy for that product yet. It may still be provisioning; retry shortly
`403 account_on_hold`	The account is on hold. Contact support@lightningbytes.com
`403 forbidden_origin`	The request came from a web page on another site. The endpoint serves MCP clients, not browser pages
`400` "Batch requests are not supported"	The client sent several JSON-RPC calls in one array. Send one call per request
`413`	The request body is over 1 MB
`429 rate_limited`	Too many calls, or too many proxy checks at once. Wait a few seconds and retry
`502 pool_error` or `503`	A temporary problem on our side or in the pool. Retry shortly

Revoking a token on the API Tokens tab takes effect immediately, so a client using it fails with 401 on its next call. See The API and API Tokens for the token lifecycle.