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

Before you start

• Claude Code installed and signed in. Check with claude --version. The commands below work the same on macOS, Linux, and Windows, apart from line breaks in the shell.
• A PapaProxy.net account. Access to the API and the MCP server is included at no additional charge; you pay only for the proxies you order.
• No Node.js, Python, or local package. The server runs at https://papaproxy.net/account_new/api/v1/mcp and speaks Streamable HTTP, which Claude Code supports natively as --transport http.

Step 1. Create an API key with the right scopes

In the Dashboard, open Settings → API keys, name the key (for example, “Claude Code”), and select scopes. The full key is shown once, right after creation. Scopes are enforced on our end, so they limit Claude regardless of your permission rules or permission mode.

Start without wallet:spend. Claude can still price any order and show you the quote; add the scope, or create a second key, when you actually want it to buy. The full scope list is on the developers page.

Step 2. Add the server to Claude Code

Claude Code stores MCP servers in one of three scopes. The scope decides where the server loads and whether your team gets it too.

Option A: one command

For a personal setup, add the server in user scope so it’s available in every project. Replace fb_YOUR_API_KEY with your key and keep Bearer and the space before it.

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

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

Claude Code prints an Added ... line on success. Drop --scope user to limit the server to the current project. The key is saved in plain text in ~/.claude.json; if that’s a concern, use Option B.

Option B: .mcp.json with the key in an environment variable

Use this to share the setup with a team through Git. Claude Code expands ${VAR} in url and headers, so the committed file names the variable and each developer keeps their own key outside the repository.

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

export PAPAPROXY_API_KEY="fb_..."

Open a new terminal, or run source ~/.zshrc, before starting claude, so it sees the variable. On Windows, set the variable in System Properties → Environment Variables. The first time you run claude in the project, it asks you to approve servers from .mcp.json; until you do, the server shows Pending approval.

Step 3. Check the connection

Run this in your terminal. The status should read ✔ Connected; if it reads ✘ Failed to connect, the line also shows the HTTP status and the error text from our server.

claude mcp get papaproxy-net

Inside a session, /mcp lists the server with its tool count. Then send a request 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 and reply with a price in dollars. Quotes are free and don’t reserve or charge anything. If a call fails, see Troubleshooting.

Permissions: what Claude can run without asking

Claude Code asks before it calls an MCP tool unless a permission rule allows it. In rules, a tool is named mcp__papaproxy-net__<tool>. Rules are checked in a fixed order: deny, then ask, then allow. That means an ask rule keeps a paid tool under approval even if a broader rule allows it. Add rules with /permissions in a session, or put them in .claude/settings.json (this project) or ~/.claude/settings.json (all projects):

{
  "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"
    ]
  }
}

The allow list holds read-only tools: nothing changes and nothing is charged. The ask list holds tools that charge your balance or change access; cancel_service and disable_addon also require an explicit confirmation from Claude. The real boundary is still the key: a key without wallet:spend can’t pay for anything, whatever permission mode Claude Code runs in, and a key with it can pay only from your account balance.

What to do with it in Claude Code

Claude Code already writes and runs your scrapers from the terminal. With the MCP server connected, the same session can manage the proxies they use.

Large proxy lists. list_proxy_ips returns the whole list of a service in one response. Claude Code warns when a tool response exceeds 10,000 tokens and cuts it at 25,000 tokens by default, which a package of a few thousand IPs can reach. For big packages, ask Claude to write code that downloads the list through the REST API instead of reading it into the chat, or raise the limit with MAX_MCP_OUTPUT_TOKENS.

All 56 tools, with the scope each needs and the REST endpoint it calls, are in the API reference. When a workflow becomes a fixed job, move it to the REST API: plain code is cheaper and easier to test than an agent.

Troubleshooting: Claude Code MCP not working

Start with claude mcp list or claude mcp get papaproxy-net: they show the status of the server, configuration warnings, and the error our server returned.

If the status shows a server error rather than a configuration problem, contact support with the time of the failed call; we’ll check it on our end.

Other MCP clients

The same URL and header work in other clients; only the config file and its format differ. There are step-by-step guides for Cursor and n8n, and setup for VS Code, Windsurf, Cline, Codex CLI, Gemini CLI, and Claude Desktop is on the developers page.