# How to add the PapaProxy.net MCP server to Cursor

> Page: https://papaproxy.net/developers/mcp/cursor.php. The PapaProxy.net MCP server gives Cursor's agent 56 tools for a proxy account: stock, quotes, orders, IP whitelisting, proxy list export, and error analytics. It's a remote Streamable HTTP server; 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 the agent regardless of Cursor's settings.

| What the agent 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`: the agent can still price any order.

## Step 2. Add the server to Cursor

Cursor reads `~/.cursor/mcp.json` (all projects) and `.cursor/mcp.json` (one project) and merges them; the project file wins on a name conflict.

Option A, one-click install: https://papaproxy.net/developers/mcp/cursor.php#one-click adds the server with the placeholder `fb_YOUR_API_KEY` to the global file `~/.cursor/mcp.json` (the hidden `.cursor` folder in the home folder). To replace the placeholder:

1. Open the file in Cursor with Cmd+O (macOS) or Ctrl+O (Windows, Linux) and enter the path: on macOS press Cmd+Shift+G and paste `~/.cursor/mcp.json` (or run `open -a Cursor ~/.cursor/mcp.json`); on Windows paste `%USERPROFILE%\.cursor\mcp.json` into File name (`C:\Users\<user name>\.cursor\mcp.json`); on Linux press Ctrl+L and paste `~/.cursor/mcp.json`.
2. In the `papaproxy-net` entry, replace only `fb_YOUR_API_KEY` with your key; keep `Bearer ` before it. Leave other servers unchanged.
3. Save, then turn the server off and on in Customize or restart Cursor.

Option B, `mcp.json` (a remote server needs only `url` and `headers`; the value must start with `Bearer ` and a space):

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

Option C, key in an environment variable (for a committed `.cursor/mcp.json`; Cursor resolves `${env:NAME}` in `url` and `headers`):

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

Set `export PAPAPROXY_API_KEY="fb_..."` in `~/.zshrc` or `~/.bashrc` (on Windows, in System Properties → Environment Variables), then quit and reopen Cursor. `envFile` works only for local stdio servers.

## Step 3. Check the connection

In Cursor, open Customize in the sidebar: `papaproxy-net` should be turned on and list its tools. 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.

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

## Tool approvals

Cursor asks before every MCP tool call by default. MCP tools follow the Run Modes in Settings → Agents → Approvals & Execution (Auto-review, Allowlist, Run Everything).

- Safe to allowlist (read-only): `list_countries`, `quote_composite`, `list_services`, `get_service`, `list_proxy_ips`, `get_whitelist`, `get_usage_overview`, `get_diagnostics`, `get_recommendations`, `wallet_balance`.
- Keep under approval (charge the balance or change access): `order_composite`, `order_dedicated`, `add_ips`, `renew_service`, `purchase_addon`, `refresh_ips`, `rotate_proxy_credentials`, `remove_whitelist_ip`. `cancel_service` and `disable_addon` also require `confirm: true`.

The security boundary is the key, not Cursor's approvals: 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: the agent 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 machine: `get_my_ip` returns the IP the request comes from (for Cursor on your computer, usually your public IP); `add_whitelist_ip` adds it.
- Diagnose errors: `get_usage_timeseries`, `get_diagnostics` (errors by status code and affected hosts), `get_top_destinations`, `get_recommendations`.
- Price before buying: `list_countries`, `quote_composite`; with `wallet:spend`, `order_composite` with an idempotency key.

Full tool list with scopes and REST endpoints: https://papaproxy.net/developers/reference/#mcp-tools. For fixed scheduled jobs, use the REST API: https://papaproxy.net/developers.php#api.

## Troubleshooting

Logs: Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows and Linux) → MCP Logs.

| What you see | Cause and fix |
|---|---|
| `Missing or malformed Authorization header` | No `headers` block, or the value doesn't start with `Bearer `; with an env variable, it may be empty — set it and restart Cursor |
| `Invalid or revoked API key` | Typo, revoked key, or `fb_YOUR_API_KEY` left after a one-click install |
| 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 |
| Server not listed or has no tools | Invalid JSON (for example, a trailing comma), server turned off in Customize, or Cursor not restarted |
| Works locally, not in Cloud Agents | Cloud Agents keep their own MCP configuration; add the server there separately |

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

## Other MCP clients

Claude Code guide: https://papaproxy.net/developers/mcp/claude-code.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