Prokso MCP server in Claude Code

1. What you need

• Claude Code, the command-line agent from Anthropic. It connects remote servers over HTTP with --transport http; this guide follows its MCP documentation as of November 2026.
• A Prokso API key: dashboard, "Settings" > "API" > "Create key". The key is shown in full only once, so copy it right away.
• Test the key before setup: the curl command is on the "Prokso MCP server" page.

2. Connect with one command

Run this in a terminal with your key:

claude mcp add --transport http prokso https://prokso.com/api/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Options come first, then the server name prokso and the address. Without --scope the server goes to the local scope: only you can use it, only in the current project, and the entry is stored in ~/.claude.json. To have the server in all your projects, add --scope user:

claude mcp add --transport http --scope user prokso https://prokso.com/api/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

In both cases the key is written to ~/.claude.json in plain text. Don't share this file or commit it.

3. A shared .mcp.json file for the team

The project scope keeps the server in a .mcp.json file at the project root, visible to everyone who works with the repository. Don't put the key in that file: Claude Code expands environment variables in the url and headers fields:

{
  "mcpServers": {
    "prokso": {
      "type": "http",
      "url": "https://prokso.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${PROKSO_API_KEY}"
      }
    }
  }
}

Each person sets their own key in the variable before starting Claude Code, for example in ~/.zshrc:

export PROKSO_API_KEY="YOUR_API_KEY"

For servers from .mcp.json Claude Code asks for approval on first launch. Until you approve, claude mcp list shows the server as pending approval. To reset saved choices, run claude mcp reset-project-choices.

4. Check it and send first requests

Check the server status:

claude mcp list
claude mcp get prokso

Next to prokso you should see ✔ Connected. Inside a Claude Code session the /mcp command shows the same: a checkmark in the server row, and five tools in the details: get_account, get_prices, list_plans, get_plan and get_proxy_lines.

First requests to try:

• "How much traffic is left on my Prokso plans?"
• "Give me 5 SOCKS5 lines with fixed IPs in Poland for plan 12."
• "Save 10 proxy lines from Germany to proxies.txt in host:port:username:password format."

Claude Code asks for permission before it calls a tool. Ports and geo parameters in the lines work as described in the gateway reference.

5. If it doesn't work

• Status ! Needs authentication or a 401 error: the server didn't get a valid key. The Prokso server has no OAuth sign-in, so a sign-in button won't help here. Check the header with claude mcp get prokso.
• The key from the variable wasn't filled in: the variable isn't set in the terminal Claude Code was started from. Check echo $PROKSO_API_KEY and restart Claude Code.
• ✘ Failed to connect: check the address. It must be https://prokso.com/api/v1/mcp with transport http, not sse.
• 429: the limit of 60 requests per minute per key is exceeded. Wait and try again.

Other errors are covered on the MCP server page, and problems with the proxies themselves in the step-by-step check.

6. Key security

The key gives access to the usernames and passwords of your plans. Create a separate key for Claude Code: if anything goes wrong, revoke only that one in "Settings" > "API". Don't commit the key to .mcp.json, use the PROKSO_API_KEY variable. The agent can't buy traffic over MCP; for automation that involves money there is the REST API, and app guides are in the "Guides" section.

MCP in Claude Desktop →How to use Prokso