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 Access 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 supplier 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
Claude Desktop	Add the server to `claude_desktop_config.json`, then 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
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.

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, suppliers and covered locations
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 supplier 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.

If a call fails

Symptom	Cause
`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 supplier. 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

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.