Skip to content

Playwright MCP Proxy: --proxy-server, Profiles, Exit Check

Three ways to set the proxy, how to keep each logged-in profile on one IP, and a check the agent can run itself.

Where the proxy goes in Playwright MCP

Playwright MCP is Microsoft's MCP server that lets an AI agent drive a real browser. It needs Node.js 18 or newer and is started by your MCP client with npx @playwright/mcp@latest. The proxy is not a tool the agent calls: it is an option the server reads when it starts, so the agent's browser traffic goes through it from the first page.

The README lists --proxy-server, for example http://user:password@myproxy:3128, with the environment variable PLAYWRIGHT_MCP_PROXY_SERVER. The simplest setup is to add it to the args of the server entry in your client's MCP configuration.

mcpServers entry with --proxy-server

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

Example only: replace the placeholder values with your own, then restart the MCP client so the server starts again with the new arguments.

Three places to put the proxy

Three places to put the proxy
ItemCredentials sit inPick it when
--proxy-server in argsThe client configuration file, and the command line of the server processYou want the shortest setup, or a quick test
PLAYWRIGHT_MCP_PROXY_SERVER in envThe env block of the server entryYour client lets you keep secrets in env, and args stay the same for every project
--config file with browser.launchOptions.proxyA separate JSON file, with username and password as their own fieldsThe password has characters such as @ or :, or several settings travel together

Source: Playwright MCP README and Playwright network documentation, read on 16 November 2026. The README gives the option names and their environment variables; the config schema shows browser.launchOptions.

The same proxy through environment variables

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_MCP_PROXY_SERVER": "http://LOGIN:PASSWORD@HOST:PORT"
      }
    }
  }
}

Example only: replace the placeholder values with your own.

The same proxy in a config file

// pw-mcp-proxy.json, started with: npx @playwright/mcp@latest --config ./pw-mcp-proxy.json
{
  "browser": {
    "launchOptions": {
      "proxy": {
        "server": "http://HOST:PORT",
        "username": "LOGIN",
        "password": "PASSWORD"
      }
    }
  }
}

Example only: replace the placeholder values with your own. Playwright's proxy object has separate server, username and password fields.

One profile, one IP

By default Playwright MCP keeps a persistent profile on disk, like a regular browser, so cookies and logins survive between sessions. The README gives a folder per MCP client workspace, and --user-data-dir to choose another. A persistent profile can be used by one browser instance at a time, so two clients sharing one profile will conflict.

A site sees the IP a logged-in profile connects from. If one profile keeps appearing from different IPs, the site sees that too. Give each profile that holds a login its own fixed IP, and do not share one account between profiles. For a throwaway task use --isolated, which keeps the profile in memory and forgets it when the session closes.

Putting both settings in the same server entry makes the pairing explicit, and nothing else needs changing when you add an account.

Two server entries, each with its own profile and its own proxy

{
  "mcpServers": {
    "browser-account-a": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir", "/home/me/pw-profiles/account-a",
        "--proxy-server", "http://LOGIN_A:PASSWORD_A@HOST_A:PORT"
      ]
    },
    "browser-account-b": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--user-data-dir", "/home/me/pw-profiles/account-b",
        "--proxy-server", "http://LOGIN_B:PASSWORD_B@HOST_B:PORT"
      ]
    }
  }
}

Example only: replace the placeholder values and folders with your own. Each entry starts its own browser, so the agent picks the entry that matches the account.

Choosing the IP type for an agent task

A browser opens several connections for one page. On a rotating line without a session, each new connection can leave from a new IP and a reused connection keeps its IP, so one page view may use more than one. That suits fetching many public pages. It does not suit a task that signs in and stays signed in.

For a login that must stay put, use a static ISP IP, which keeps its address for the whole lease, or open a session on the rotating Budget line, which takes 1 to 120 minutes. The agent-proxy-types guide compares the options for agents in more detail.

Check the exit before the task, in 3 steps

  1. Step 1

    Restart the MCP client so Playwright MCP starts with the proxy, and check that the server entry shows as running.

  2. Step 2

    Ask the agent: Open https://ipinfo.io/json with browser_navigate and tell me the "ip" and "country" values.

  3. Step 3

    Compare the ip and country with the proxy you set up. If it shows your own address, the arguments did not reach the server: see the table below. Only then give the agent the real task.

When the proxy does not seem to apply

The IP page shows your own address

Check Was the MCP client restarted after the edit, and is the entry you edited the one in use? Arguments are read when the server starts.

Fix Restart the client and ask again. If a persistent profile is locked by another running browser, close that one or point this server at a different --user-data-dir.

Stop when If it still shows your address, run the same proxy with curl to see whether the proxy itself works.

A SOCKS5 proxy with a login fails

Check Chrome does not support SOCKS5 with a username and password, and Playwright's username and password fields are for HTTP(S) proxies.

Fix Use the HTTP endpoint of the same IP, for example port 2222 on Proxy302.

Stop when Do not keep retrying socks5:// with a login in the same argument.

The agent reports ERR_PROXY_CONNECTION_FAILED

Check The host, port and protocol in --proxy-server, and whether the proxy answers at all.

Fix Fix the address, or use the connection-failed guide to go through the checks in order.

Stop when If curl through the same proxy also fails, open a ticket with your order number.

The page shows a sign-in prompt or a 407 error

Check Is the username and password complete, including characters such as @ or : that are easy to mistype?

Fix Copy them again from My assets, or move them into the config file where username and password are separate fields.

Stop when If the same login also fails in curl, see the proxy authentication guide or open a ticket with your order number.

On Proxy302: what to buy for an agent browser

Proxy302 endpoints speak HTTP on port 2222 and SOCKS5 on port 3333. For a Playwright MCP browser with a login, copy an HTTP asset from My assets into --proxy-server. A static ISP IP costs US$0.50 for 1 day or US$7.99 for 30 days, the same in every country, and does not change during the lease. Rotating residential Budget line traffic costs US$1.50 per GB.

There is no free trial, and the smallest purchase is 1 GB of rotating traffic or one IP for one day. Follow each platform's terms and the countries it supports, and complete any verification the platform asks for.

Set up Proxy302 for Playwright MCP in 4 steps

  1. Step 1

    Open the static residential page, choose the country, keep Protocol on HTTP and place the order.

  2. Step 2

    Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD.

  3. Step 3

    Put them into --proxy-server http://USERNAME:PASSWORD@HOST:PORT in the Playwright MCP entry and restart your MCP client.

  4. Step 4

    Ask the agent to open https://ipinfo.io/json and confirm the IP and country before it starts the task.

Playwright MCP proxy FAQ

Does Playwright MCP have a proxy setting?

Yes. The README lists --proxy-server and the environment variable PLAYWRIGHT_MCP_PROXY_SERVER.

Can I change the proxy while the agent is running?

The README does not describe changing it at run time. Change the arguments and restart the MCP client, which starts the server again.

Can the same setup use a SOCKS5 proxy?

The README shows socks5:// in the proxy address, but a SOCKS5 proxy that needs a username and password does not work in Chrome. Use an HTTP endpoint for those.

Does each agent need its own profile?

If an agent signs in to an account, yes: give it its own --user-data-dir and its own fixed IP. For anonymous reading, --isolated is enough.

Is it headed or headless?

Headed by default; add --headless to run without a window. The proxy options are the same.

Reference links

5
  1. Playwright MCP README (microsoft/playwright-mcp)

    Official documentation · Confirmed on:

    Read on 16 November 2026: --proxy-server (examples http://myproxy:3128, http://user:password@myproxy:3128, socks5://myproxy:8080) with the PLAYWRIGHT_MCP_PROXY_SERVER environment variable; --config with browser.launchOptions and browser.contextOptions; persistent profile by default, --isolated, --user-data-dir and --storage-state; a persistent profile can be used by one browser instance at a time; Node.js 18 or newer; tools including browser_navigate, browser_evaluate and browser_network_requests.

  2. Playwright docs: Network, HTTP proxy

    Official documentation · Confirmed on:

    Read on 16 November 2026: a proxy can be set for the whole browser or for each browser context; HTTP(S) and SOCKSv5 are supported; username and password are for HTTP(S) proxies.

  3. Chromium docs: Proxy support in Chrome (net/docs/proxy.md)

    Official documentation · Confirmed on:

    Read on 16 November 2026: no authentication methods are supported for SOCKSv5 in Chrome.

  4. Proxy302 product facts and price list

    Product observation · Confirmed on:

    Product facts file of the site (values checked against the console, the backend and the price table on 18-19 October 2026): products, prices in US$ (1 PTC = US$1), lease terms, protocols and ports, no free trial.

  5. Proxy302 line tests (11 November 2026)

    Product observation · Confirmed on:

    Proxy302 tests of the dynamic lines on 11 November 2026: without a session each new connection gets a new IP and a reused connection keeps its IP; the Budget line takes a session of 1 to 120 minutes.

Ready to try it?

Create an account, top up once, then pick rotating residential, static ISP or datacenter IPs and have one running in your browser within minutes.