Documentation menu

Start

Proxy fundamentals

Proxy APIs

Response cache

Litport API

MCP server

MCP server for AI assistants

Connect an AI coding assistant to your Litport account with the Model Context Protocol (MCP) server. The assistant lists your proxy tokens, reads usage and charges, discovers the countries a pool can target, and assembles working proxy connection strings, without you writing an HTTP client first.

The server cannot create tokens, buy or cancel packages, or spend balance. It can change a movable token's location, rotation interval, or IP, and a package's allowed IPs, as described below. IPv6 requests are unsupported; contact support.

Install#

The server runs on your own machine and talks to this site over HTTPS. Create an API key in Settings, then add the server to your MCP host.

Claude Code:

claude mcp add litport --env LITPORT_API_KEY=lit_your_key_here -- npx -y @litportnet/litport-mcp

Codex:

codex mcp add litport --env LITPORT_API_KEY=lit_your_key_here -- npx -y @litportnet/litport-mcp

That writes the server into ~/.codex/config.toml. You can also add the block by hand:

[mcp_servers.litport]
command = "npx"
args = ["-y", "@litportnet/litport-mcp"]

[mcp_servers.litport.env]
LITPORT_API_KEY = "lit_your_key_here"

Check it with codex mcp list, inspect one entry with codex mcp get litport, and remove it with codex mcp remove litport.

Claude Desktop, Cursor, Windsurf, and other hosts that launch a local process use a configuration block:

{
  "mcpServers": {
    "litport": {
      "command": "npx",
      "args": ["-y", "@litportnet/litport-mcp"],
      "env": { "LITPORT_API_KEY": "lit_your_key_here" }
    }
  }
}

Environment variables#

Variable Default Effect
LITPORT_API_KEY required API key from Settings. Not a proxy username or password.
LITPORT_API_URL https://litport.net Override the API origin.
LITPORT_MCP_REVEAL_CREDENTIALS unset Set to 1 to include proxy passwords directly in list_tokens output.

Tools#

Tool What it does Writes
list_tokens List your tokens with type, status, and ingress details. no
get_token_credentials Full credentials for one token. no
get_token_usage Traffic and charge components for one token. no
get_token_location Read a movable token's saved and effective location. no
list_location_options List the values currently usable for a token's next location field. no
set_token_location Change a movable token's location. yes
set_rotation Change a rotating token's rotation interval. yes
get_new_ip Get a new IP in the same location (static datacenter/ISP only). yes
list_packages List owned packages with status, product, add-ons, and token IDs. no
get_package Read one package. no
get_allowed_ips Read a package's allowed-IP list. no
set_allowed_ips Set a package's whole allowed-IP list. yes
add_allowed_ip Add one IP to a package's allowed-IP list. yes
remove_allowed_ip Remove one IP from a package's allowed-IP list. yes
list_pools Selectable pay-per-GB pools with effective per-GB price, ports, eligible hubs, and geo levels. no
list_targeting_options Countries, regions, and cities a pool can target. no
get_balance Balance, reserved units, and plan. no
build_proxy_url Assemble a working proxy URL with geo and session parameters. no
explain_proxy_error Translate a proxy error code into a retry decision. no
search_docs Find the documentation page covering a topic. no
get_doc Read a documentation page as Markdown. no

Every tool that writes needs the same API key as every read; there is no separate write scope. Creating or deleting tokens, and buying, renewing, or cancelling a package, stay in the dashboard.

explain_proxy_error answers from a copy of the proxy error reference shipped inside the package, so diagnosing a failure costs nothing and consumes no rate limit.

How proxy passwords are handled#

list_tokens is a browse operation, so it masks passwords by default: each token reports password: null with passwordSet: true. This keeps a listing of many tokens from placing every password into the assistant's context and, through it, your chat history.

Nothing is withheld. get_token_credentials and build_proxy_url both return the real password for the single token you asked about. Set LITPORT_MCP_REVEAL_CREDENTIALS=1 if you would rather have credentials inline in listings.

build_proxy_url also accepts credentialStyle: "env", which returns the URL with $LITPORT_PROXY_PASSWORD in place of the password and hands the value back separately. Use it when the assistant is writing a script you intend to keep, so the password does not end up in your source.

Building a connection string#

build_proxy_url applies the rules on PPG proxy parameters before returning anything, so a malformed country slug or an out-of-range session lifetime is reported immediately rather than after a refused request.

For a pay-per-GB token it appends the pool, geo, and session segments to the username and selects the port matching the chosen protocol. A token with a saved pool does not take a pool argument, and a conflicting one is refused. A token without a saved pool requires the pool argument, because the pool sets the price.

An unlimited token connects to the one endpoint it is assigned, so it takes neither a pool nor geo or session parameters.

Questions#

Can it create proxies or spend my balance? No. Some tools write (see the table above: a movable token's location, rotation, or new IP, and a package's allowed IPs), but none of them can create or delete a token, or move money. Creating tokens and buying traffic stay in the dashboard.

Does it need my proxy password to start? No. It authenticates with an API key, which is separate from proxy credentials. A proxy username and password will be rejected as an API key.

Which assistants work with it? Any MCP host that can launch a local process, including Claude Code, Codex, Claude Desktop, Cursor, Windsurf, and Zed.

Is my key sent to the model? No. The key stays in the server process on your machine and is used only in the Authorization header to this site.

What happens when I hit the rate limit? The API allows a fixed number of requests per minute per key and answers 429 beyond it. Three tools need no API key at all (explain_proxy_error, search_docs, and get_doc), so they keep working when the rate limit is hit. The last two still fetch documentation pages from this site.

Why does a token show no host? An unlimited token reports ingress.status: "hub-unavailable" when it names a hub that is no longer in service. The token's own status only ever reports active, expired, or disabled. Contact support to move a hub-unavailable token to a current hub.

The API these tools call is documented at Litport API, with its error codes at API errors. The machine-readable contract is at /docs/openapi.json.

MarkdownOpenAPI