How to use a proxy with Playwright MCP

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

Add the proxy to your MCP client config

Most MCP clients use a JSON config with an mcpServers section. Add the proxy as an argument.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--proxy-server=http://USERNAME:PASSWORD@HOST:PORT"
      ]
    }
  }
}

Restart the MCP server (or your AI client) after changing the config, then ask the agent to open https://ipinfo.io/json to confirm the exit IP.

Or use a config file

A config file keeps the credentials out of your client config, and lets you set the proxy as separate fields.

{
  "browser": {
    "launchOptions": {
      "proxy": {
        "server": "http://HOST:PORT",
        "username": "USERNAME",
        "password": "PASSWORD"
      }
    }
  }
}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--config", "/absolute/path/to/playwright-mcp.json"]
    }
  }
}

Use a sticky line

An agent often works on one site for several minutes. A sticky line keeps the same IP for the whole task, so logins and carts survive. Pick a Sticky Duration in the generator that covers the task. For accounts the agent uses over days, use a static ISP IP. To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand.

Browse from a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them. Agents then see local prices, search results and language.

Skip the proxy for local sites

Add --proxy-bypass=localhost,127.0.0.1 so the agent can still reach apps on your machine directly.

Troubleshooting

• The agent sees a proxy sign-in prompt or a 407

  The credentials aren’t reaching the browser. Check the --proxy-server value or the config file path, then restart the server.More on this error →

• The agent still shows your own IP

  The client is running an older server process. Restart the client, and check that the args are in the right server entry.

• net::ERR_TUNNEL_CONNECTION_FAILED

  The proxy refused the CONNECT request. Run the line through curl -v to see the real status (407, 502 or 503).More on this error →

• The site shows CAPTCHAs

  Use residential sticky lines and slow the agent down.More on this error →

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions