Playwright MCP proxy setup
Playwright MCP gives AI agents such as Claude Code, Cursor and VS Code a real browser. One flag sends that browser through our gateway, login included.
- Protocols
- HTTP proxy on port 7000 with a login. SOCKS5 only without a login
- Authentication
- Login and password inside the
--proxy-serverURL - Rotation
- One proxy for the whole session: a sticky
-sid-login, and a restart for a new IP - Works with
- Residential and mobile proxies. Written for @playwright/mcp 0.0.85 (November 2026)
Before you start
- Node.js on the machine that runs the server: the clients start it with
npx. - Your proxy login and password from the Residential or Mobile page of the dashboard.
- Traffic on the product you use: a login without traffic gets 402.
- Host
gate.aeonproxy.com- Port (HTTP / HTTPS)
7000- Login
- your proxy login, with targeting keys if you need them:
LOGIN-cc-us-sid-abc123 - Password
- your proxy password
Copy the login and password from the Residential or Mobile page of the dashboard; the generator there also writes ready lines. Key syntax: targeting and sessions.
The proxy flag
Start the server with --proxy-server and put the login and password in the URL. The server takes them out of the URL and answers the proxy’s login request itself, so the login works although Chromium’s own proxy flag cannot carry one.
npx @playwright/mcp@latest --proxy-server "http://LOGIN-cc-us-sid-ab12cd34-time-1800:[email protected]:7000"The same URL can go in the PLAYWRIGHT_MCP_PROXY_SERVER environment variable instead. A password with @, : or / must be percent-encoded in the URL (%40, %3A, %2F).
Claude Code
Add the server once, with the flag after --:
claude mcp add playwright -- npx @playwright/mcp@latest --proxy-server "http://LOGIN-cc-us-sid-ab12cd34-time-1800:[email protected]:7000"Cursor and other clients
Cursor and Claude Desktop read servers from an mcpServers JSON file. The flag goes into args:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--proxy-server",
"http://LOGIN-cc-us-sid-ab12cd34-time-1800:[email protected]:7000"
]
}
}
}In VS Code the server entry takes the same command and args.
One browser, one proxy
The proxy is set when the browser starts and holds for the whole MCP session: the agent has no tool to change it. Use a sticky login, so every page the agent opens leaves from one IP, and restart the server with a new sid value when you want a new IP. With a rotating login each connection gets a new IP, and sites that keep you signed in can treat that as a new device.
The flag applies to the browser the server starts itself. When it attaches to a browser that is already running, set the proxy in that browser instead, for example as in the Chrome guide.
SOCKS5
The server’s help lists socks5:// addresses, but Playwright refuses SOCKS5 with a login: the browser fails to start with Browser does not support socks5 proxy authentication. Our SOCKS5 port needs a login, so use port 7000.
Check the exit
Ask the agent to open IP checker and read out the IP and the country. If they are your own, the client started the server without the flag: check which config file it actually reads.
Google and YouTube
If google.com or youtube.com time out while other sites open, it is a Chromium issue with Playwright’s proxy login, described in the Playwright guide. Save this as playwright-mcp.json and add --config playwright-mcp.json to the server’s arguments:
{
"browser": {
"launchOptions": {
"args": ["--disable-features=AcceptCHFrame"]
}
}
}If it does not work
| What you see | What to check |
|---|---|
| Every page times out | The login, the password or a key. With a wrong login Chromium waits on the proxy’s 407 instead of failing. |
| google.com or youtube.com time out, other sites open | Add the launch argument from Google and YouTube above. |
| The agent reports that the site cannot be reached | The gateway refused the tunnel: 402 (no traffic left), 403 (a target blocked by default) or 502 (the exit failed, retry). curl with the same login prints the code. |
Questions
Yes. Add two servers under different names, each with its own login and -cc- key.
No. Use --proxy-server or PLAYWRIGHT_MCP_PROXY_SERVER.