Playwright MCP, Microsoft's browser server for AI clients, takes a proxy in three places: the --proxy-server flag, the PLAYWRIGHT_MCP_PROXY_SERVER variable, or a config file. Two traps sit behind them. The flag has no room for a login, so a user:pass written into its URL is dropped without an error. And once a proxy is set, Playwright sends localhost through it too, so your own app stops loading. We read every setting on this page in Playwright MCP 0.0.82, released on 18 September 2026, and in the Playwright code it runs.
Why would Playwright MCP need a proxy?
Playwright MCP opens Chrome on the machine that runs it, so every page sees that machine's IP. On your laptop that is usually your home IP. On a server it is a hosting IP, and some sites refuse those on the first request, as our test below shows. A proxy also lets the agent see a site from another country, or spread many sessions over many IPs.
We tested what the address alone changes, on 19 September 2026: plain requests to thirteen sites, twice from our server and twice through a residential line. A residential IP changed the answer at four of them: Zillow, Instagram, Reddit and DuckDuckGo. Indeed, Glassdoor, Amazon and Booking refused both. That test sent plain requests, not a browser. Chrome runs the scripts a plain request skips, so it may get further on some of these sites. We did not test that. The table per site is on our OpenClaw page.
How do I set a proxy in Playwright MCP?
Add the two flags to the server's arguments in your MCP client's config:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--proxy-server", "http://GATEWAY_HOST:GATEWAY_PORT",
"--proxy-bypass", "localhost,127.0.0.1"
]
}
}
}
The same values work as PLAYWRIGHT_MCP_PROXY_SERVER and PLAYWRIGHT_MCP_PROXY_BYPASS in the server's environment. This route fits a proxy that needs no login, such as a line that allows your server's IP. Playwright handles each form of the value in its own way:
| You pass | What Playwright does |
|---|---|
http://host:port | uses the proxy |
host:port, with no scheme | uses it as an HTTP proxy |
http://user:pass@host:port | uses the proxy, drops the login, shows no error |
socks5://host:port | uses the proxy, but SOCKS5 takes no login here |
The third row is the trap. Playwright rebuilds the address from the scheme and the host, and the user:pass part is lost on the way. The proxy then asks for a login the browser never got. Our Playwright proxy guide shows the same rule in plain Playwright code.
How do I give Playwright MCP a proxy login?
Put the proxy in a config file, with the login as separate fields:
{
"browser": {
"launchOptions": {
"proxy": {
"server": "http://GATEWAY_HOST:GATEWAY_PORT",
"username": "USERNAME",
"password": "PASSWORD",
"bypass": "localhost,127.0.0.1"
}
}
}
}
Then point the server at the file:
"args": ["@playwright/mcp@latest", "--config", "/full/path/to/playwright-mcp.json"]
Use the full path. The server reads a relative path from the folder the MCP client starts it in, and you may not know which folder that is.
With these fields set, Playwright answers the proxy's login request itself. Its own test suite checks exactly this: a proxy that replies 407 gets the username and password.
Two rules keep the login in place:
- Set no proxy flag next to the file. Playwright MCP reads the file first, then the environment, then the command line. A
--proxy-serverflag orPLAYWRIGHT_MCP_PROXY_SERVERreplaces the whole proxy entry of the file, login included. The flag has won over the file since a fix in April 2026. - Use no SOCKS5 line with a login. Playwright then refuses to start the browser, with the error "Browser does not support socks5 proxy authentication". Use the HTTP line of the same proxy.
Why does localhost stop working with a proxy?
Chrome on its own never sends localhost, 127.0.0.1 or other loopback addresses through a proxy. Playwright changes that. When a proxy is set and the bypass list names no loopback host, it adds a rule that sends loopback traffic through the proxy too. Your request for localhost:3000 then goes to the proxy, which cannot reach your machine.
This is on purpose. Playwright's test suite checks that localhost, 127.0.0.1 and link-local addresses go through the proxy by default. For Playwright MCP it hits a common job: testing your own app on your own machine. The fix is the bypass list:
--proxy-bypass "localhost,127.0.0.1"
Once localhost or 127.0.0.1 is on that list, Playwright leaves out its rule, and Chrome sends every loopback address direct again. In the config file, the same list goes in the bypass field.
Which settings and modes does the proxy reach?
Playwright MCP itself never reads HTTPS_PROXY. Chrome may pick it up on Linux outside GNOME and KDE. On Windows and macOS, Chrome follows the system proxy settings instead.
The mode matters too, because the proxy is set when Playwright MCP starts the browser:
| Mode | Does the proxy apply? |
|---|---|
| Default, with a saved profile | yes |
--isolated | yes |
--cdp-endpoint | no, it attaches to a running browser |
--extension | no, it drives your own Chrome |
In the last two modes the browser keeps whatever proxy it already has. Set the proxy where that browser starts.
Which proxy type fits Playwright MCP?
By default Playwright MCP keeps a saved profile, so cookies and logins survive between sessions. An agent that logs in should keep one IP for the whole session, so a sticky line fits it. One-off reads, for example with --isolated, suit a rotating line.
HProxy residential gateways fit both routes. On a server with a fixed IP, allow that IP on a Residential Premium plan, up to 150 per plan. The line then needs no login, so the flag works as it is: --proxy-server http://GATEWAY_HOST:GATEWAY_PORT, with a sticky port for an agent that logs in. An allowed IP takes no country or city targeting. For a country, or on a laptop whose IP changes, use a generated line. Its username carries the targeting, so it goes in the config file. A sticky IP can still change early if its device leaves the network, so let the agent retry. The residential proxies page lists the plans, and the plan API generates lines and manages allowed IPs from code.
What breaks when the proxy is on?
- The proxy asks for a login. The login sits in the flag's URL, where it is dropped. Move it to the config file.
- The login in the config file is ignored. A flag or
PLAYWRIGHT_MCP_PROXY_SERVERreplaced it. Remove them. - Your local app does not load. Add
localhost,127.0.0.1to the bypass list. - "Browser does not support socks5 proxy authentication". Use the HTTP line instead of SOCKS5.
- Nothing changed at all. The server runs with
--cdp-endpointor--extension, or the proxy sits only inHTTPS_PROXY. - 407 Proxy Authentication Required. The proxy refused the login. On our gateways this means a wrong password or a line from another plan. Our 407 guide walks through it.
- The site still shows a check. A proxy changes the address, not the browser or the way the agent acts.
What this page does not cover
We read Playwright MCP 0.0.82, the Playwright code it runs and Playwright's own tests. We did not run Playwright MCP. The blocking test used plain requests from one server IP and one residential line, over one afternoon. We did not watch what Chrome shows when a proxy asks for a login it never got. Firefox and WebKit pass the login by other routes, and we read those only in passing. Playwright MCP ships a new release every few weeks, sometimes days apart, so we will read these settings again by 19 October 2026.
Where to go from here
Proxies for Playwright covers the library itself, and how to use proxies with Playwright shows the proxy object in code. Proxies for OpenClaw and proxies for Hermes Agent cover two agents that drive a browser the same way. Sticky vs rotating sessions explains the choice above.
Sources
- README (options table, profiles, configuration file) and package.json. Microsoft, microsoft/playwright-mcp, release v0.0.82, 18 September 2026.
- MCP config and browser factory, normalizeProxySettings, the Chromium launch arguments and loopback rule, the proxy option docs and the proxy tests. Microsoft, microsoft/playwright at commit 78ff4260d79b, 18 September 2026.
- Proxy support in Chrome (implicit bypass rules), Linux proxy config and Network Settings. The Chromium Authors, read 19 September 2026.
- Issues #1549, #1444 and #1057 and pull request #274 in microsoft/playwright-mcp; issue #40204 and pull request #40212 in microsoft/playwright. 2025 to 2026.
- Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
- Our own test of 19 September 2026: plain GET requests to 13 sites and 3 controls, two runs from our server and two through a residential line of our own house plan, with curl 8.5.0. Raw output is kept in the research folder of our OpenClaw page.
