> For the complete documentation index, see [llms.txt](https://help.proxidize.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.proxidize.com/proxidize-proxies/proxidize-mcp-server.md).
# Proxidize MCP Server
Manage mobile and residential proxies from any MCP-compatible AI client.
Rotate IPs, monitor usage, manage tags, and control access through natural language.
The server checks your active subscriptions when it starts. It loads only tools available to your account.
## Requirements
You need Node.js 18 or later and a Proxidize API token.
To get your token:
1. Sign in to the Proxidize Dashboard.
2. Select your avatar, then select **Settings**.
3. Copy your API token.
{% hint style="warning" %}
Keep your API token private. Do not commit it to version control.
{% endhint %}
## Connect a client
{% tabs %}
{% tab title="Claude Code" %}
Use the local scope for the current project:
```bash
claude mcp add proxidize -e PROXIDIZE_API_TOKEN=YOUR_API_TOKEN -- npx -y @proxidize/mcp
```
Use the user scope for every local project:
```bash
claude mcp add proxidize --scope user -e PROXIDIZE_API_TOKEN=YOUR_API_TOKEN -- npx -y @proxidize/mcp
```
For shared projects, configure the token through secret management:
```bash
claude mcp add --scope project proxidize -- npx -y @proxidize/mcp
```
Run `/mcp` to verify the connection.
{% endtab %}
{% tab title="Claude Desktop" %}
Add this configuration to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"proxidize": {
"command": "npx",
"args": ["-y", "@proxidize/mcp"],
"env": {
"PROXIDIZE_API_TOKEN": "YOUR_API_TOKEN"
}
}
}
}
```
{% endtab %}
{% tab title="Cursor, Windsurf, or VS Code" %}
Add this configuration to `.mcp.json` or your IDE's MCP settings:
```json
{
"mcpServers": {
"proxidize": {
"command": "npx",
"args": ["-y", "@proxidize/mcp"],
"env": {
"PROXIDIZE_API_TOKEN": "YOUR_API_TOKEN"
}
}
}
}
```
{% endtab %}
{% endtabs %}
## Available tools
Every installation provides these account tools:
* `get_subscription` lists active subscriptions.
* `get_outbound_ip` returns the server's public IP.
The server loads subscription-specific tools automatically.
Per Proxy Mobile
Manage dedicated mobile proxies with tools to:
* List and inspect proxies, locations, carriers, and tags.
* Rotate IPs and configure automatic rotation.
* Manage passwords, IP allowlists, and proxy tags.
Per GB Mobile and Residential
Each plan provides plan-prefixed tools:
* Check usage, locations, carriers, and access point settings.
* Create access points and IP allowlist entries.
* Update allowlist entries and access point routing.
Mobile tools start with `mobile_`. Residential tools start with `residential_`.
Analytics
Any active plan enables analytics tools:
* `get_traffic_analytics` returns bandwidth and request trends.
* `get_top_domains` lists destinations by usage or request count.
* `get_connection_history` returns per-request connection logs.
## Configuration
| Variable | Required | Default | Purpose |
| ----------------------------- | -------- | ---------------------------------- | ------------------------------------------------ |
| `PROXIDIZE_API_TOKEN` | Yes | — | API token for your Proxidize account. |
| `PROXIDIZE_BASE_URL` | No | `https://api.proxidize.com/api/v1` | API base URL. |
| `PROXIDIZE_PROXY_HOST` | No | `pg.proxi.es` | Proxy gateway host for connection URLs. |
| `PROXIDIZE_TIMEOUT` | No | `30000` | Request timeout in milliseconds. |
| `PROXIDIZE_MAX_RETRIES` | No | `2` | Server-error retries, from `0` to `5`. |
| `PROXIDIZE_DISABLE_ANALYTICS` | No | — | Set to `1` to disable anonymous usage analytics. |
The server collects anonymous tool, latency, and error data by default. It never sends tool responses. Sensitive parameters are redacted.
Set `PROXIDIZE_DISABLE_ANALYTICS=1` or `DO_NOT_TRACK=1` to opt out.
## Troubleshooting
| Issue | Resolution |
| --------------------------------- | -------------------------------------------------------------------- |
| `PROXIDIZE_API_TOKEN is required` | Add the token to your MCP client configuration. |
| Only account tools appear | Confirm your token and active subscription. |
| `HTTP 401: Invalid token` | Generate a new token in **Settings**, then update the configuration. |
| Requests time out | Set `PROXIDIZE_TIMEOUT=60000` in the server environment. |
## FAQ
What is the Proxidize MCP Server?
It gives AI agents direct access to your Proxidize account. Use natural language to rotate IPs, change locations, check usage, and manage access points.
Is it free to use?
The MCP Server is free and open source under the MIT License. You need an active Proxidize subscription to use proxy-management tools.
Which AI tools does it work with?
It works with any MCP-compatible client. Supported clients include Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code with an MCP extension.
Do I need to install anything?
There is no build step. Configure your client to run `npx -y @proxidize/mcp`. Node.js 18 or later downloads and runs it when needed.
Why do I only see `get_subscription` and `get_outbound_ip`?
Those tools always load. The server registers other tools from your active subscriptions. Check your token and subscription if expected tools are missing.
Does it send my data anywhere?
The server collects anonymous tool, latency, and error data through PostHog. It never sends tool responses. Sensitive parameters are redacted automatically.
Set `PROXIDIZE_DISABLE_ANALYTICS=1` or `DO_NOT_TRACK=1` to opt out.
Can I run it from source instead of npm?
Yes. Clone the repository, run `npm install` and `npm run build`, then configure your client to run the build output.
## Resources
Review the [MCP Server repository](https://github.com/proxidize/proxidize-mcp) for source code and development instructions.
Visit the [Proxidize MCP Server overview](https://proxidize.com/tools/mcp-server/) for product details.
## Need Help?
Contact for connection help.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.proxidize.com/proxidize-proxies/proxidize-mcp-server.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.