ipvolt proxy toolkit MCP ServerVerifiedFeatured

What is ipvolt Proxy Toolkit MCP?

ipvolt Proxy Toolkit MCP is an open-source MCP server that gives AI agents reviewed proxy documentation, tested proxy configuration templates and structured diagnosis of proxy errors, with no API key and no proxy account.

It is published by ipvolt, a proxy provider, under the MIT licence. The toolkit is separate from ipvolt's commercial proxy service, which is not open yet. It does not provision proxies, buy traffic, read account data or change another agent's network route. The four public tools run against a bundled, versioned catalog of ipvolt's public guides, so the local server makes no network requests and sends no telemetry.

How to use ipvolt Proxy Toolkit MCP?

There are three ways to run it: the npm package, a source build, or the hosted endpoint.

npm package

Version 0.1.0 is published as @ipvolt/proxy-toolkit-mcp. The README recommends pinning the version:

{
  "mcpServers": {
    "ipvolt": {
      "command": "npx",
      "args": ["--yes", "@ipvolt/proxy-toolkit-mcp@0.1.0"]
    }
  }
}

Build from source

This requires Node.js 24 or newer and npm. From the repository directory:

npm ci
npm run build
npm run check:content
node dist/transports/stdio.js --version

Then point your client at the compiled entry with an absolute path:

{
  "mcpServers": {
    "ipvolt": {
      "command": "node",
      "args": ["/absolute/path/to/proxy-toolkit-mcp/dist/transports/stdio.js"]
    }
  }
}

The same mcpServers block works in Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json). For Claude Code:

claude mcp add ipvolt -- npx --yes @ipvolt/proxy-toolkit-mcp@0.1.0

Hosted endpoint

The public URL is https://mcp.ipvolt.com/mcp (Streamable HTTP). It needs no signup or API key and exposes the four public tools.

claude mcp add --transport http ipvolt https://mcp.ipvolt.com/mcp

In Claude Desktop or claude.ai, add it as a custom connector with that URL. In Cursor or VS Code, add a url entry:

{
  "mcpServers": {
    "ipvolt": {
      "url": "https://mcp.ipvolt.com/mcp"
    }
  }
}

(VS Code uses a servers key with "type": "http".) The hosted service rejects the local route diagnostic and accepts no proxy configuration.

Key features of ipvolt Proxy Toolkit MCP

• Search and read reviewed proxy guides with canonical links, excerpts and a content revision.
• Exact-version request templates for curl 8.22.0, Requests 2.34.2, HTTPX 0.28.1 and Playwright 1.63.0, each tested against controlled authenticated proxies.
• Templates use an HTTP proxy with HTTPS CONNECT, verify destination TLS, turn off redirects and automatic retries, and keep the destination and proxy in local TARGET_URL and PROXY_URL variables.
• Structured error diagnosis that states its uncertainty and retry limits.
• An optional, explicitly enabled local route check.
• No telemetry from the local server. Hosted metrics record only the tool name, status, duration and version.

ipvolt Proxy Toolkit MCP tools

• Documentation: search_proxy_docs searches the reviewed guides and articles. get_proxy_doc returns a named document or section in bounded chunks, with continuation cursors tied to the revision.
• Configuration: generate_proxy_config returns an exact-version HTTPS GET template with local environment placeholders. It does not run code.
• Diagnosis: diagnose_proxy_error interprets structured observations such as a CONNECT 407, a TLS failure or an ambiguous timeout.
• Route check (local only): check_proxy_route makes one bounded request through your configured proxy to the fixed echo endpoint https://mcp.ipvolt.com/egress. It is off by default.

Example arguments from the README: {"query":"curl proxy","topic":"setup"} for a search and {"client":"httpx","version":"0.28.1","phase":"proxy_connect","status":407} for a diagnosis.

Use cases of ipvolt Proxy Toolkit MCP

• Set up a client: "Show me a tested HTTPX 0.28.1 example that goes through an HTTP proxy."
• Debug a failure: "My curl request through the proxy returns 407 on CONNECT. What does that point to?"
• Look up a guide: "Find ipvolt's guide on setting up a proxy with curl."
• Check egress: with the route check enabled, confirm which exit address one request goes out from.

Troubleshooting ipvolt Proxy Toolkit MCP

• check_proxy_route is missing: set IPVOLT_ENABLE_ROUTE_CHECK=1 and provide IPVOLT_PROXY_URL through your client's local environment, then call it with {"profile":"default"}. It is not available on the hosted server.
• A 407 diagnosis doesn't name the cause: that is by design. A 407 points to proxy authentication but does not show whether the password, the account state or an access policy is at fault.
• Build fails: the source build needs Node.js 24 or newer.
• Hosted calls are throttled: the service allows 120 requests per minute per address and 32 KiB request bodies by default.