Proxy fixed at startup
One exit, chosen before the agent starts.
- ✕You pick the exit once, in a launch flag
- ✕Changing country means restarting the server
- ✕No tool to check where a request landed
Browser MCP for AI agents.
Let your agent pick the country it browses from.
Aethyn Browser MCP is an MCP server that gives an AI agent a local Chromium whose requests exit through a residential IP the agent chooses — one sticky identity per task, verified before the page is trusted.
npx -y aethyn-browser-mcpClaude Desktop · Cursor · Claude Code · Codex- aethyn_launch_browser { country: "jp", session: "price_jp" }
- { session_id: "price_jp", tier: "premium", sticky: true }
- aethyn_check_exit_ip { session_id: "price_jp" }
- { country: "JP", is_residential: true }
- aethyn_navigate { url: "https://shop.example.jp/p/buds" }
- { status: 200, final_url: "https://shop.example.jp/p/buds" }
- aethyn_get_content { format: "markdown" }
- { format: "markdown", content: "# Buds Pro …" }
exit JPstickyverified
Why it exists
The exit is a tool argument, not a startup flag.
Three ways an agent's browser reaches the web — and who decides where each request exits.
Hosted scraping MCP
Real geography, decided where you can't see it.
- ✕The provider picks the exit
- ✕The browser runs on their infrastructure
- ✕Where a request landed is opaque
Aethyn Browser MCP
The agent chooses the exit on every launch.
- ✓The agent passes the country on each launch
- ✓One sticky session per task, on your machine
- ✓aethyn_check_exit_ip confirms the exit first
In one paragraph
Most browser tools fix the proxy once, when the server starts, so every later call leaves through the same address: the machine the agent happens to run on. Hosted scraping MCPs take the other path. Traffic exits through their infrastructure, the geography is real, and the agent still cannot pick the exit or check where a request landed. Country-gated prices, local availability, and region-specific results all come back from a vantage point the agent never chose. Aethyn Browser MCP makes the exit a tool argument instead. Playwright Chromium runs on your machine and you supply the proxy credentials. The server defaults to Aethyn and works with any HTTP proxy. The agent picks the country, and on Elite the city, at call time, holds one sticky identity for the task, and calls aethyn_check_exit_ip before it trusts the page. It speaks the Model Context Protocol over stdio, so any MCP client can load it.
How a task runs
Launch, verify, read, close.
The same four calls cover a single lookup or a loop across a dozen countries.
- 01
Launch in a country
aethyn_launch_browserThe agent passes a two-letter country code. On Elite it can add a city or state. The session pins one exit IP for the task.
- 02
Verify the exit
aethyn_check_exit_ipFetches IP info through the session proxy and returns country, city, org, and a best-effort is_residential flag.
- 03
Read the page
aethyn_get_contentAfter aethyn_navigate, returns the page as markdown, text, or HTML — a cleaned read instead of the raw DOM.
- 04
Close the session
aethyn_closeFrees the browser context. Loop the same block per country to build a comparison table.
Tool reference
Ten tools, all prefixed aethyn_.
Launch returns a session_id. Every other tool takes it as its first argument.
Session
aethyn_launch_browserStart Chromium through a residential exit in a chosen country.aethyn_new_identityRotate to a fresh IP in the same country and clear cookies.aethyn_closeClose the session's browser context and free memory.
Geo
aethyn_list_countriesDiscover available exit countries, and Elite cities, at runtime.aethyn_check_exit_ipConfirm the exit country before trusting a localized page.
Page
aethyn_navigateGo to a URL and wait for load.aethyn_get_contentReturn the page as markdown, text, or HTML.aethyn_snapshotAccessibility tree with ref handles to act on.aethyn_clickClick an element by ref or selector.aethyn_typeType into an input and optionally press Enter.
Install
One config block in your MCP client.
- Add the server.Paste the block into Claude Desktop's
claude_desktop_config.jsonor Cursor's~/.cursor/mcp.json. - Add your credentials. Username and password come from the Aethyn dashboard and stay in this file on your machine. The password is redacted from every error the server returns.
- Match the tier to your plan, then restart. A mismatched tier is rejected with a 407.
Premium:2099
Country targeting
Elite:5499
Country, city, and state
mcp.json
{
"mcpServers": {
"aethyn-browser": {
"command": "npx",
"args": ["-y", "aethyn-browser-mcp"],
"env": {
"AETHYN_USERNAME": "aethyn-XXXXX",
"AETHYN_PASSWORD": "your-proxy-password",
"AETHYN_DEFAULT_TIER": "premium"
}
}
}
}HTTP-only by design — Chromium cannot authenticate to SOCKS5. The first install downloads Playwright Chromium, about 170 MB.
FAQ
Browser MCP questions, answered.
Which MCP clients can load Aethyn Browser MCP?
Any client that speaks the Model Context Protocol over stdio, including Claude Desktop, Cursor, Claude Code, and Codex. Add the server to the client's MCP config and restart it.
Why is it HTTP-only?
Chromium cannot authenticate to SOCKS5 proxies, so the server is HTTP-only by design. All Aethyn country, city, and state targeting works over HTTP, so nothing is lost.
Can I use a proxy provider other than Aethyn?
Yes. Aethyn is the default, but any HTTP proxy works. Set PROXY_HOST, PROXY_PORT, and credentials, then describe the provider's username format with PROXY_USERNAME_TEMPLATE.
Does it detect blocks or solve CAPTCHAs?
No. A 200 response can still be a soft-block, so the agent reads the content and decides, then calls aethyn_new_identity for a fresh same-country exit. There is no CAPTCHA solving and no login automation — public, unauthenticated data only.
What does the first install download?
A Playwright Chromium build, about 170 MB, one time. If your environment blocks post-install scripts, run npx playwright install chromium once.