# 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](/users/settings), then add the server to your MCP host.

Claude Code:

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

Codex:

```bash
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:

```toml
[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:

```json
{
  "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` | unset | API key from Settings. Not a proxy username or password. Without it, only the support and documentation tools load, and support questions go to a guest conversation. |
| `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, UDP support (`udp`), 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 |
| `contact_support` | Ask Litport support a question. With an API key it goes to your account's conversation; without one it starts a guest conversation and needs your email. | yes |
| `get_support_replies` | Read new messages in the support conversation. | no |
| `reply_to_support` | Add a message to the support conversation. | yes |

Every account tool that writes needs the same API key as every read; there is no separate write scope. The support tools work with or without a key: see [Contact support](/docs/api/support). 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](/docs/proxy-errors) 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](/docs/ppg-proxies) 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.

## Related

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