# How to add the PapaProxy.net MCP server to Claude Code

> Page: https://papaproxy.net/developers/mcp/claude-code.php. The PapaProxy.net MCP server gives Claude Code 56 tools for a proxy account: stock, quotes, orders, IP whitelisting, proxy list export, and error analytics. It's a remote Streamable HTTP server (`--transport http`); nothing is installed locally.

- MCP endpoint: `https://papaproxy.net/account_new/api/v1/mcp`
- Authentication: `Authorization: Bearer <api_key>` header
- Create a key: Dashboard → Settings → API keys (https://papaproxy.net/account_new/settings#api-keys). The full key is shown once.
- Cost: included with every account; you pay only for the proxies you order.

## Step 1. Create an API key with the right scopes

Scopes are enforced by the server, so they limit Claude regardless of permission rules or permission mode.

| What Claude should do | Scopes |
|---|---|
| Analyze only: stock, quotes, services, usage, errors | `catalog:read`, `services:read`, `usage:read` |
| Also configure: IP whitelisting, credentials, auto-renewal | the above plus `services:write` |
| Also pay from the balance: orders, renewals, add-ons, extra IPs | the above plus `wallet:read`, `wallet:spend` |

Start without `wallet:spend`: Claude can still price any order.

## Step 2. Add the server to Claude Code

| Scope | Where it loads | Stored in |
|---|---|---|
| `local` (default) | Only the current project, only for you | `~/.claude.json`, under that project |
| `user` | All your projects on this machine | `~/.claude.json` |
| `project` | Everyone who works in the repository | `.mcp.json` in the project root |

Option A, one command (user scope; replace the placeholder, keep `Bearer `):

```bash
claude mcp add --transport http --scope user papaproxy-net \
  https://papaproxy.net/account_new/api/v1/mcp \
  --header "Authorization: Bearer fb_YOUR_API_KEY"
```

On Windows, put the command on one line (the `\` line breaks work only in macOS and Linux shells). The key is stored in plain text in `~/.claude.json`.

Option B, `.mcp.json` in the project root with the key in an environment variable (Claude Code expands `${VAR}` in `url` and `headers`):

```json
{
  "mcpServers": {
    "papaproxy-net": {
      "type": "http",
      "url": "https://papaproxy.net/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${PAPAPROXY_API_KEY}"
      }
    }
  }
}
```

Set `export PAPAPROXY_API_KEY="fb_..."` in `~/.zshrc` or `~/.bashrc` and open a new terminal before running `claude`. On the first run in the project, Claude Code asks you to approve servers from `.mcp.json`; until then the status is `Pending approval`.

## Step 3. Check the connection

Run `claude mcp get papaproxy-net`: the status should be `✔ Connected`. A `✘ Failed to connect` status includes the HTTP status and the server's error text. Inside a session, `/mcp` lists the server with its tool count. Then send a prompt that can't cost anything:

> Using the papaproxy-net MCP server, list the countries where datacenter proxies are in stock, then quote 100 US IPs for one month. Don't buy anything.

Claude should call `list_countries` and `quote_composite`. Quotes are free and don't reserve anything.

## Permissions

Tools are named `mcp__papaproxy-net__<tool>` in permission rules. Rules are checked in order deny → ask → allow, so an `ask` rule keeps a tool under approval even when a broader rule allows it. Add rules with `/permissions`, or in `.claude/settings.json` (project) or `~/.claude/settings.json` (all projects):

```json
{
  "permissions": {
    "allow": [
      "mcp__papaproxy-net__list_countries",
      "mcp__papaproxy-net__quote_composite",
      "mcp__papaproxy-net__list_services",
      "mcp__papaproxy-net__get_service",
      "mcp__papaproxy-net__list_proxy_ips",
      "mcp__papaproxy-net__get_whitelist",
      "mcp__papaproxy-net__get_usage_overview",
      "mcp__papaproxy-net__get_diagnostics",
      "mcp__papaproxy-net__get_recommendations",
      "mcp__papaproxy-net__wallet_balance"
    ],
    "ask": [
      "mcp__papaproxy-net__order_composite",
      "mcp__papaproxy-net__order_dedicated",
      "mcp__papaproxy-net__add_ips",
      "mcp__papaproxy-net__renew_service",
      "mcp__papaproxy-net__purchase_addon",
      "mcp__papaproxy-net__refresh_ips",
      "mcp__papaproxy-net__rotate_proxy_credentials",
      "mcp__papaproxy-net__remove_whitelist_ip",
      "mcp__papaproxy-net__cancel_service",
      "mcp__papaproxy-net__disable_addon"
    ]
  }
}
```

`cancel_service` and `disable_addon` also require `confirm: true`. The security boundary is the key: a key without `wallet:spend` can't pay for anything, and a key with it pays only from the account balance.

## Workflows

- Build a scraper on live proxies: Claude uses `list_services` and `list_proxy_ips`, then writes code that loads the proxy list from the REST API at startup and reads the key from `PAPAPROXY_API_KEY`.
- Whitelist the server you're on: `get_my_ip` returns the IP the request comes from (on a remote server, the server's public IP); `add_whitelist_ip` adds it.
- Daily error report without a session: `claude -p "Summarize yesterday's proxy errors" --allowedTools "mcp__papaproxy-net__get_usage_timeseries" "mcp__papaproxy-net__get_diagnostics"`. In `-p` mode no one can approve calls, so list the read-only tools the run needs.
- Price before buying: `list_countries`, `quote_composite`; with `wallet:spend`, `order_composite` with an idempotency key.

Large proxy lists: `list_proxy_ips` returns a service's whole list in one response. Claude Code warns above 10,000 tokens and cuts tool output at 25,000 tokens by default, which a package of a few thousand IPs can reach. For big packages, have Claude write code that downloads the list via the REST API (https://papaproxy.net/developers/reference/proxy-access.md), or raise `MAX_MCP_OUTPUT_TOKENS`.

Full tool list with scopes and REST endpoints: https://papaproxy.net/developers/reference/#mcp-tools.

## Troubleshooting

Start with `claude mcp list` or `claude mcp get papaproxy-net`.

| What you see | Cause and fix |
|---|---|
| `Missing or malformed Authorization header` | No `--header`, or the value doesn't start with `Bearer `; with Option B, `PAPAPROXY_API_KEY` isn't set in the terminal you start `claude` from |
| `Invalid or revoked API key` | Typo, revoked key, or `fb_YOUR_API_KEY` left in the command; `claude mcp remove papaproxy-net` and add it again |
| `Leading or trailing whitespace in: headers.Authorization` | The pasted key has a space or line break; remove the server and add it again |
| `⏸ Pending approval` | A `.mcp.json` server you haven't approved; run `claude` in the project and approve it |
| A warning naming `PAPAPROXY_API_KEY` | The variable isn't set; add the `export` line and open a new terminal |
| Same server name in more than one scope | Remove the duplicate with `claude mcp remove papaproxy-net --scope local` |
| A tool call fails with a scope error | The key lacks the tool's scope; errors come back as text with a short code and an explanation |
| Calls fail after many requests | 60 requests per minute per account, shared by all API keys and the MCP server |
| The command fails on Windows | Use the one-line form; `\` line breaks work only in macOS and Linux shells |

Server errors: contact support@papaproxy.net with the time of the failed call.

## Other MCP clients

Cursor guide: https://papaproxy.net/developers/mcp/cursor.md. n8n guide: https://papaproxy.net/developers/mcp/n8n.md. VS Code, Windsurf, Cline, Codex CLI, Gemini CLI, Claude Desktop: https://papaproxy.net/developers.php#mcp