[{"_1":2,"_196":-5,"_197":-5},"loaderData",{"_3":4,"_17":18,"_25":26,"_165":166},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","routes/_layout",{"_19":-5,"_20":21,"_22":21,"_23":11,"_24":21},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":-5,"_89":90,"_154":-5,"_155":11,"_156":21,"_157":11,"_158":-5,"_159":11,"_160":-5,"_161":162,"_163":91,"_164":-7},"canonicalUrl","https://hub.docker.com/r/superbizon007/proxy-mcp/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","superbizon007","reponame","proxy-mcp","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":11,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2026-05-08T18:05:21.566513Z","description","","is_private","last_updated","2026-05-14T15:28:26.536816Z","last_modified","2026-05-14T15:28:28.069152Z","media_types",[56],"application/vnd.oci.image.index.v1+json","name","pull_count",335,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# proxy_mcp\n\nFastMCP service managing a pool of SOCKS5 proxies for dynamic agent spawning. When a spawner creates a new agent container, it calls `get_proxy()` to lease a proxy, injects `SOCKS_PROXY` as an env var, and calls `release_proxy()` when the task finishes.\n\nAgents route all traffic through the proxy transparently via `tun2socks` — no application-level proxy config needed.\n\n## Quick Start\n\n```bash\n# Install\ncd apps/proxy_mcp\nuv sync\n\n# Start with Docker (Postgres + app)\ndocker compose up -d\n\n# Or run locally (requires Postgres)\nexport PROXY_MCP_DATABASE_URL=postgresql+psycopg://proxy_mcp:proxy_mcp@localhost:5432/proxy_mcp\nalembic upgrade head\nproxy-mcp serve --transport streamable-http\n```\n\n## MCP Tools\n\n| Tool | Description |\n| --- | --- |\n| `get_proxy` | Lease a proxy. Inline rotating products bypass the DB; static IPs use `SELECT FOR UPDATE SKIP LOCKED`. Cheapest-first by priority. |\n| `release_proxy` | Release a lease after successful task completion. No-op for inline rotating leases. |\n| `report_failure` | Record a failure. Static IPs auto-disable after 3 consecutive fails (configurable). Inline rotating leases log + return without state change. |\n| `list_proxies` | Read-only pool overview. Returns DB rows unioned with synthesized rows for configured rotating products. |\n| `upsert_proxy` | Insert or update a proxy. Upserts on `(host, port, protocol)`. Used by `cli sync` for static IPs. |\n\n## CLI\n\n```bash\nproxy-mcp serve [--transport stdio|streamable-http] [--host HOST] [--port PORT]\nproxy-mcp sync [--provider brightdata|oxylabs|decodo|dataimpulse]\n # fetch static IPs from provider APIs\n # rotating products are skipped (zero-row mode)\nproxy-mcp list [--enabled-only] [--country US]\nproxy-mcp reset-leases # force-release all static leases\nproxy-mcp enable PROXY_ID\nproxy-mcp disable PROXY_ID\n```\n\n## Proxy Types & Priority\n\nLower priority = cheaper = selected first when no `proxy_type` filter is passed.\n\n| Type | Priority | Typical Cost (Oxylabs) |\n| --- | --- | --- |\n| `free` | 10 | $0 |\n| `datacenter` | 20 | $1.2 / IP |\n| `isp` | 25 | $1.6 / IP |\n| `dedicated_datacenter` | 28 | $2.25 / IP |\n| `dedicated_isp` | 32 | $3.2 / IP |\n| `residential` | 40 | $6 / GB |\n| `mobile` | 50 | $7.5 / GB |\n\n## Two lease modes\n\n### Zero-row (rotating gateways) — no sync, no DB rows\n\nRotating products (BrightData zones, Oxylabs residential/mobile, Decodo rotating, DataImpulse) are leased **inline from settings** at request time. Each lease constructs a fresh URL with a session ID injected into the username, pointing at the provider's gateway. Nothing is written to the database.\n\n- No `cli sync` required.\n- New rotating products go live the moment env config changes.\n- The synthetic lease IDs use the prefix `inline::::` so `release_proxy` and `report_failure` can short-circuit without DB writes.\n- See `app/inline_lease.py` for the candidate iterator + URL builder.\n\n### DB-backed (static IPs) — `cli sync` required\n\nStatic IP products (BrightData static zones, Oxylabs ISP / Datacenter / dedicated-*, Decodo static) carry per-IP state. `cli sync` fetches the current list from each provider's API and upserts rows into the `proxies` table. `get_proxy` then locks one with `SELECT FOR UPDATE SKIP LOCKED` and marks it `in_use=True`.\n\nRun `proxy-mcp sync` once after seeding credentials, then on a cron (daily is plenty — provider IP lists rarely churn).\n\n## Provider setup\n\n### BrightData\n\n```bash\nBRIGHTDATA_API_TOKEN=\nBRIGHTDATA_CUSTOMER_ID=\nBRIGHTDATA_ZONES='[\n {\"name\":\"res_zone\",\"password\":\"\",\"type\":\"rotating\",\"proxy_type\":\"residential\"},\n {\"name\":\"dc_static\",\"password\":\"\",\"type\":\"static\",\"proxy_type\":\"datacenter\"}\n]'\n```\n\n- Gateway: `brd.superproxy.io:22225` for rotating\n- Session pattern: `-session-{sid}` appended to the username\n- Static IPs fetched via `GET /api/zone/ips?zone={name}` (Bearer auth)\n\n### Oxylabs\n\n```bash\nOXYLABS_USERNAME=\nOXYLABS_PASSWORD=\nOXYLABS_PRODUCTS='[\n {\"name\":\"residential\",\"type\":\"rotating\",\"proxy_type\":\"residential\"},\n {\"name\":\"mobile\",\"type\":\"rotating\",\"proxy_type\":\"mobile\"},\n {\"name\":\"isp_shared\",\"type\":\"static\",\"proxy_type\":\"isp\",\n \"list_url\":\"https://stats.oxylabs.io/api/proxy-list/isp\"},\n {\"name\":\"isp_dedicated\",\"type\":\"static\",\"proxy_type\":\"dedicated_isp\",\n \"list_url\":\"https://stats.oxylabs.io/api/proxy-list/dedicated-isp\"},\n {\"name\":\"dc_dedicated\",\"type\":\"static\",\"proxy_type\":\"dedicated_datacenter\",\n \"list_url\":\"https://stats.oxylabs.io/api/proxy-list/dedicated-datacenter\"}\n]'\n```\n\n- Gateway: `pr.oxylabs.io:7777` for rotating\n- Session pattern: `-sessid-{sid}` appended to the username\n- Static IPs fetched via the per-product `list_url` from your dashboard (HTTP Basic auth)\n\n### Decodo (formerly Smartproxy)\n\n```bash\nDECODO_API_TOKEN=\nDECODO_USERNAME=\nDECODO_PASSWORD=\nDECODO_PRODUCTS='[\n {\"name\":\"rot_residential\",\"type\":\"rotating\",\"proxy_type\":\"residential\"}\n]'\n```\n\n- Gateway: `gate.smartproxy.com:5000` (SOCKS5) / `:7000` (HTTP) for rotating\n- Session pattern: `-sessionid-{sid}` appended to the username\n- Static IP list endpoint: not yet verified against current Decodo docs — see `app/providers/decodo.py:13-15`\n\n### DataImpulse\n\n```bash\nDATAIMPULSE_LOGIN=\nDATAIMPULSE_PASSWORD=\nDATAIMPULSE_PRODUCTS='[\n {\"name\":\"rot_residential\",\"country\":\"GB\",\"proxy_type\":\"residential\"}\n]'\n```\n\n- Gateway: `gw.dataimpulse.com:824` (SOCKS5)\n- Country targeting: `__cr.` segment in the username\n- Session pattern: `;sessid.{sid}` appended (semicolon + dot delimiters preserved literally in URL encoding)\n- Gateway-only — no static IPs to sync\n\n## Environment Variables\n\n### Service\n\n```bash\n# Required\nPROXY_MCP_DATABASE_URL=postgresql+psycopg://user:pass@localhost:5432/proxy_mcp\n\n# Optional\nPROXY_MCP_HOST=0.0.0.0\nPROXY_MCP_PORT=8002\nPROXY_MCP_AUTO_DISABLE_FAILS=3 # consecutive fails before static IP auto-disable\nPROXY_MCP_LEASE_TIMEOUT=60 # minutes before stale lease cleanup (static IPs only)\nLOG_LEVEL=INFO\nAPI_KEY= # bearer auth for streamable-http mode (Core sets this on its calls)\n```\n\n### Per-provider\n\nSet credentials + the corresponding `*_PRODUCTS` (or `*_ZONES` for BrightData) JSON array. The full reference is in `.env.example`. Each entry must include `type` (`rotating` or `static`) and `proxy_type` (one of the seven values listed above). Country is optional.\n\n## Minimum viable setup (Oxylabs residential only)\n\n```bash\nPROXY_MCP_DATABASE_URL=postgresql+psycopg://proxy_mcp:proxy_mcp@db:5432/proxy_mcp\nAPI_KEY=\n\nOXYLABS_USERNAME=\nOXYLABS_PASSWORD=\nOXYLABS_PRODUCTS='[{\"name\":\"residential\",\"type\":\"rotating\",\"proxy_type\":\"residential\"}]'\n```\n\nStart the service. Set `PROXY_MCP_URL=http://proxy-mcp:8002/mcp` and `PROXY_AGENTS=linux.chrome.agent` on Core. **No `cli sync` needed** — every Chrome agent spawn now leases an inline residential proxy.\n\n## What needs `cli sync`\n\n| Setup | Sync needed? |\n| --- | --- |\n| Pure rotating (Oxylabs residential, DataImpulse, BrightData rotating zones, Decodo rotating) | **No** |\n| Static IPs (Oxylabs ISP / DC / dedicated-*, BrightData static zones, Decodo static) | **Yes** — daily cron is plenty |\n| Mixed (rotating + static from the same provider) | Yes for the static portion; rotating items in the same `*_PRODUCTS` JSON are skipped automatically with a `'N rotating skipped'` note |\n\n## Agent integration\n\nCore's spawner injects the lease as an env var on the agent pod:\n\n```bash\n# Browser / desktop / scraper / terminal / downloader agents (tun2socks routing)\nSOCKS_PROXY=socks5://user:pass@1.2.3.4:1080\n\n# Android agent (ADB http_proxy)\nANDROID_PROXY=1.2.3.4:1080\n```\n\nBoth values come back in the `ProxyLease` response. Core picks the right env name based on `agent_type_key`.\n\nSee `specs/PLAN_PROXY_INTEGRATION.md` (Core-side wiring) and `specs/PLAN_PROXY_ZERO_ROW.md` (this service's lease model) for the design behind both halves.\n\n## Tests\n\n```bash\nuv sync --dev\nuv run pytest tests/ -v\n```\n","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":21,"_83":11,"_84":11},"read","write","admin","user","storage_size",351841419,"orgData","recentTags",[91,145],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_101":102,"_50":134,"_135":94,"_136":33,"_137":56,"_57":138,"_139":140,"_141":127,"_142":134,"_143":66,"_144":21},"content_type","creator",39089913,"digest","sha256:f0e87bbab1152d07e73c3f3924172415de1253b86c957f2bfebb67c6d7226788","full_size",87630355,"id",1157437437,"images",[103,118,124,130],{"_104":105,"_95":106,"_107":48,"_108":109,"_110":111,"_112":113,"_114":48,"_115":-5,"_116":98,"_63":66,"_117":-5},"architecture","amd64","sha256:bc87e2736e0489c12e540929da9e8d5f620c5e8d2c12914cabe71149bb6ea8b1","features","last_pulled","2026-10-09T16:49:53.651437934Z","last_pushed","2026-05-14T15:28:18.129176367Z","os","linux","os_features","os_version","size","variant",{"_104":119,"_95":120,"_107":48,"_108":121,"_110":122,"_112":113,"_114":48,"_115":-5,"_116":123,"_63":66,"_117":-5},"arm64","sha256:6457db7f223be1cb03e7f9c0a6e6db6fbae2c6784a333813e03141d8b36677f4","2026-10-09T16:49:53.662568596Z","2026-05-14T15:28:19.082999705Z",88322831,{"_104":125,"_95":126,"_107":48,"_108":127,"_110":128,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},"unknown","sha256:51dce02b7584a3fef8e62dcacf07bf114f5e58adc73814abf0ac669ed6dd7968","2026-10-09T16:49:53.676610075Z","2026-05-14T15:28:20.427852835Z",1761,{"_104":125,"_95":131,"_107":48,"_108":132,"_110":133,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},"sha256:da291d90b3c7980a10da9c06c3701876b0186aef1dc340790b3b770835847f4d","2026-10-09T16:49:53.654911426Z","2026-05-14T15:28:19.891274358Z","2026-05-14T15:28:25.780754Z","last_updater","last_updater_username","media_type","latest","repository",31062920,"tag_last_pulled","tag_last_pushed","tag_status","v2",{"_92":44,"_93":94,"_95":96,"_97":98,"_99":146,"_101":147,"_50":152,"_135":94,"_136":33,"_137":56,"_57":153,"_139":140,"_141":127,"_142":152,"_143":66,"_144":21},1157437390,[148,149,150,151],{"_104":105,"_95":106,"_107":48,"_108":109,"_110":111,"_112":113,"_114":48,"_115":-5,"_116":98,"_63":66,"_117":-5},{"_104":119,"_95":120,"_107":48,"_108":121,"_110":122,"_112":113,"_114":48,"_115":-5,"_116":123,"_63":66,"_117":-5},{"_104":125,"_95":131,"_107":48,"_108":132,"_110":133,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},{"_104":125,"_95":126,"_107":48,"_108":127,"_110":128,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},"2026-05-14T15:28:21.546954Z","0.1.1","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":167,"_174":175,"_161":194,"_195":11},{"_40":168,"_42":169,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":170,"_57":35,"_32":33,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":171,"_79":11,"_80":173,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":172},[78],{"_82":21,"_83":11,"_84":11},"tags",{"_176":177,"_178":-5,"_179":-5,"_180":181},"count",2,"next","previous","results",[182,188],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_101":183,"_50":134,"_135":94,"_136":33,"_137":56,"_57":138,"_139":140,"_141":127,"_142":134,"_143":66,"_144":21},[184,185,186,187],{"_104":105,"_95":106,"_107":48,"_108":109,"_110":111,"_112":113,"_114":48,"_115":-5,"_116":98,"_63":66,"_117":-5},{"_104":119,"_95":120,"_107":48,"_108":121,"_110":122,"_112":113,"_114":48,"_115":-5,"_116":123,"_63":66,"_117":-5},{"_104":125,"_95":126,"_107":48,"_108":127,"_110":128,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},{"_104":125,"_95":131,"_107":48,"_108":132,"_110":133,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},{"_92":44,"_93":94,"_95":96,"_97":98,"_99":146,"_101":189,"_50":152,"_135":94,"_136":33,"_137":56,"_57":153,"_139":140,"_141":127,"_142":152,"_143":66,"_144":21},[190,191,192,193],{"_104":105,"_95":106,"_107":48,"_108":109,"_110":111,"_112":113,"_114":48,"_115":-5,"_116":98,"_63":66,"_117":-5},{"_104":119,"_95":120,"_107":48,"_108":121,"_110":122,"_112":113,"_114":48,"_115":-5,"_116":123,"_63":66,"_117":-5},{"_104":125,"_95":131,"_107":48,"_108":132,"_110":133,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},{"_104":125,"_95":126,"_107":48,"_108":127,"_110":128,"_112":125,"_114":48,"_115":-5,"_116":129,"_63":66,"_117":-5},[],"canDeleteTags","actionData","errors"]

Digest	OS/ARCH	Compressed size
bc87e2736e04	linux/amd64	83.57 MB
6457db7f223b	linux/arm64	84.23 MB

superbizon007/proxy-mcp

Tags for superbizon007/proxy-mcp