[{"_1":2,"_188":-5,"_189":-5},"loaderData",{"_3":4,"_13":14,"_21":22,"_157":158},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","routes/_layout",{"_15":-5,"_16":17,"_18":17,"_19":11,"_20":11},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_23":24,"_25":-5,"_26":11,"_27":11,"_28":29,"_30":31,"_32":-5,"_33":11,"_34":35,"_84":-5,"_85":86,"_150":-5,"_151":11,"_152":17,"_153":11,"_154":-5,"_155":156},"canonicalUrl","https://hub.docker.com/r/superbizon007/proxy-mcp/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","superbizon007","reponame","proxy-mcp","cloudBuildSource","isAutobuildsAvailable","repo",{"_36":37,"_38":39,"_41":42,"_43":44,"_45":11,"_46":47,"_48":49,"_50":51,"_53":31,"_28":29,"_54":55,"_56":-5,"_57":58,"_59":60,"_61":62,"_63":-5,"_64":58,"_65":66,"_67":11,"_68":29,"_69":70,"_75":11,"_76":77,"_81":29,"_82":83},"categories",[],"content_types",[40],"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",[52],"application/vnd.oci.image.index.v1+json","name","pull_count",309,"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",{"_71":11,"_72":73},"enabled","rules",[74],".*","is_automated","permissions",{"_78":17,"_79":11,"_80":11},"read","write","admin","user","storage_size",351841419,"orgData","recentTags",[87,141],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_97":98,"_46":130,"_131":90,"_132":29,"_133":52,"_53":134,"_135":136,"_137":105,"_138":130,"_139":62,"_140":17},"content_type","creator",39089913,"digest","sha256:f0e87bbab1152d07e73c3f3924172415de1253b86c957f2bfebb67c6d7226788","full_size",87630355,"id",1157437437,"images",[99,114,120,126],{"_100":101,"_91":102,"_103":44,"_104":105,"_106":107,"_108":109,"_110":44,"_111":-5,"_112":94,"_59":62,"_113":-5},"architecture","amd64","sha256:bc87e2736e0489c12e540929da9e8d5f620c5e8d2c12914cabe71149bb6ea8b1","features","last_pulled","2026-09-16T15:56:31.072845138Z","last_pushed","2026-05-14T15:28:18.129176367Z","os","linux","os_features","os_version","size","variant",{"_100":115,"_91":116,"_103":44,"_104":117,"_106":118,"_108":109,"_110":44,"_111":-5,"_112":119,"_59":62,"_113":-5},"arm64","sha256:6457db7f223be1cb03e7f9c0a6e6db6fbae2c6784a333813e03141d8b36677f4","2026-09-16T15:56:31.006195865Z","2026-05-14T15:28:19.082999705Z",88322831,{"_100":121,"_91":122,"_103":44,"_104":123,"_106":124,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},"unknown","sha256:51dce02b7584a3fef8e62dcacf07bf114f5e58adc73814abf0ac669ed6dd7968","2026-09-16T15:56:30.998518746Z","2026-05-14T15:28:20.427852835Z",1761,{"_100":121,"_91":127,"_103":44,"_104":128,"_106":129,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},"sha256:da291d90b3c7980a10da9c06c3701876b0186aef1dc340790b3b770835847f4d","2026-09-16T15:56:31.01560023Z","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",{"_88":40,"_89":90,"_91":92,"_93":94,"_95":142,"_97":143,"_46":148,"_131":90,"_132":29,"_133":52,"_53":149,"_135":136,"_137":105,"_138":148,"_139":62,"_140":17},1157437390,[144,145,146,147],{"_100":101,"_91":102,"_103":44,"_104":105,"_106":107,"_108":109,"_110":44,"_111":-5,"_112":94,"_59":62,"_113":-5},{"_100":115,"_91":116,"_103":44,"_104":117,"_106":118,"_108":109,"_110":44,"_111":-5,"_112":119,"_59":62,"_113":-5},{"_100":121,"_91":127,"_103":44,"_104":128,"_106":129,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},{"_100":121,"_91":122,"_103":44,"_104":123,"_106":124,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},"2026-05-14T15:28:21.546954Z","0.1.1","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.tags",{"_34":159,"_166":167,"_155":186,"_187":11},{"_36":160,"_38":161,"_41":42,"_43":44,"_45":11,"_46":47,"_48":49,"_50":162,"_53":31,"_28":29,"_54":55,"_56":-5,"_57":58,"_59":60,"_61":62,"_63":-5,"_64":58,"_65":66,"_67":11,"_68":29,"_69":163,"_75":11,"_76":165,"_81":29,"_82":83},[],[40],[52],{"_71":11,"_72":164},[74],{"_78":17,"_79":11,"_80":11},"tags",{"_168":169,"_170":-5,"_171":-5,"_172":173},"count",2,"next","previous","results",[174,180],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_97":175,"_46":130,"_131":90,"_132":29,"_133":52,"_53":134,"_135":136,"_137":105,"_138":130,"_139":62,"_140":17},[176,177,178,179],{"_100":101,"_91":102,"_103":44,"_104":105,"_106":107,"_108":109,"_110":44,"_111":-5,"_112":94,"_59":62,"_113":-5},{"_100":115,"_91":116,"_103":44,"_104":117,"_106":118,"_108":109,"_110":44,"_111":-5,"_112":119,"_59":62,"_113":-5},{"_100":121,"_91":122,"_103":44,"_104":123,"_106":124,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},{"_100":121,"_91":127,"_103":44,"_104":128,"_106":129,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},{"_88":40,"_89":90,"_91":92,"_93":94,"_95":142,"_97":181,"_46":148,"_131":90,"_132":29,"_133":52,"_53":149,"_135":136,"_137":105,"_138":148,"_139":62,"_140":17},[182,183,184,185],{"_100":101,"_91":102,"_103":44,"_104":105,"_106":107,"_108":109,"_110":44,"_111":-5,"_112":94,"_59":62,"_113":-5},{"_100":115,"_91":116,"_103":44,"_104":117,"_106":118,"_108":109,"_110":44,"_111":-5,"_112":119,"_59":62,"_113":-5},{"_100":121,"_91":127,"_103":44,"_104":128,"_106":129,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},{"_100":121,"_91":122,"_103":44,"_104":123,"_106":124,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-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