Proxy4agent MCP Server

Proxy4Agents MCP

Residential proxy MCP server for AI agents. Route any HTTP request through 2M+ real home devices — Android phones, Windows PCs, Macs — to bypass anti-bot systems, geo-target by country or city, and maintain sticky sessions across multi-step workflows.

Works with Claude Code, Cursor, Windsurf, Cline, Continue, and any MCP-compatible AI agent. Powered by Novada.

Free tier available — sign up at novada.com, no credit card required. Get free access to Scraper API, Web Unblocker, and residential proxies to start building immediately.

---

Why Proxy4Agents MCP

AI agents get blocked on 60–70% of commercial websites. Standard HTTP requests are detected and rejected by Cloudflare, Akamai, DataDome, and PerimeterX. Proxy4Agents MCP routes your agent through real residential IPs — indistinguishable from a human browser.

---

8 Tools at a Glance

---

When To Use Which Tool

Goal: "Scrape a single URL"
  └─ Static HTML page?          → agentproxy_fetch
  └─ Need specific fields?      → agentproxy_extract
  └─ React/Vue SPA / blank page? → agentproxy_render

Goal: "Scrape multiple URLs"
  └─ You have the URLs already  → agentproxy_batch_fetch
  └─ You need to discover URLs  → agentproxy_map → agentproxy_batch_fetch

Goal: "Search the web"          → agentproxy_search → agentproxy_batch_fetch

Goal: "Login + multi-page flow" → agentproxy_session (same session_id)

Goal: "Check if proxy works"    → agentproxy_status

---

Quick Install

Core — fetch any URL through residential proxy:

claude mcp add bestproxy4agents-mcp \
  -e NOVADA_PROXY_USER=your_username \
  -e NOVADA_PROXY_PASS=your_password \
  -- npx -y bestproxy4agents-mcp

Search only:

claude mcp add bestproxy4agents-mcp \
  -e NOVADA_API_KEY=your_key \
  -- npx -y bestproxy4agents-mcp

All tools (proxy + search + browser render):

claude mcp add bestproxy4agents-mcp \
  -e NOVADA_PROXY_USER=your_username \
  -e NOVADA_PROXY_PASS=your_password \
  -e NOVADA_API_KEY=your_key \
  -e NOVADA_BROWSER_WS=your_browser_ws_url \
  -- npx -y bestproxy4agents-mcp

Cursor / Windsurf / Cline — add to MCP config:

{
  "mcpServers": {
    "bestproxy4agents-mcp": {
      "command": "npx",
      "args": ["-y", "bestproxy4agents-mcp"],
      "env": {
        "NOVADA_PROXY_USER": "your_username",
        "NOVADA_PROXY_PASS": "your_password"
      }
    }
  }
}

Get credentials: novada.com → Dashboard → Residential Proxies → Endpoint Generator

---

Providers

Proxy4Agents MCP works with any HTTP proxy provider. Novada is the built-in default with the deepest integration.

Priority: Novada → BrightData → Smartproxy → Oxylabs → Generic. First configured provider wins.

claude mcp add bestproxy4agents-mcp \
  -e BRIGHTDATA_USER="brd-customer-abc123-zone-residential" \
  -e BRIGHTDATA_PASS=your_password \
  -- npx -y bestproxy4agents-mcp

BRIGHTDATA_USER is your full username including zone. Optional: BRIGHTDATA_HOST, BRIGHTDATA_PORT (default zproxy.lum-superproxy.io:22225).

claude mcp add bestproxy4agents-mcp \
  -e SMARTPROXY_USER=your_username \
  -e SMARTPROXY_PASS=your_password \
  -- npx -y bestproxy4agents-mcp

Optional: SMARTPROXY_HOST, SMARTPROXY_PORT (default gate.smartproxy.com:10001).

claude mcp add bestproxy4agents-mcp \
  -e OXYLABS_USER=your_username \
  -e OXYLABS_PASS=your_password \
  -- npx -y bestproxy4agents-mcp

Optional: OXYLABS_HOST, OXYLABS_PORT (default pr.oxylabs.io:7777).

claude mcp add bestproxy4agents-mcp \
  -e PROXY_URL="http://username:password@geo.iproyal.com:12321" \
  -- npx -y bestproxy4agents-mcp

country, city, session_id params are ignored with Generic — encode targeting directly in your proxy URL.

---

Tools

agentproxy_fetch

Fetch any URL through a residential proxy. Returns structured JSON with content, status code, and metadata. Auto-retry on network errors. Caches repeated calls (default 300s TTL — meta.cache_hit: true means no proxy credit used).

Response:

{
  "ok": true,
  "tool": "agentproxy_fetch",
  "data": { "url": "...", "status_code": 200, "content": "...", "size_bytes": 34000 },
  "meta": { "latency_ms": 1800, "cache_hit": false, "quota": { "credits_estimated": 1 } }
}

---

agentproxy_batch_fetch

Fetch 2–20 URLs concurrently through residential proxy. Up to 5x faster than sequential fetches. Per-URL errors are captured individually — the batch itself succeeds even if some URLs fail. Reuses response cache for URLs already fetched.

Response:

{
  "ok": true,
  "tool": "agentproxy_batch_fetch",
  "data": {
    "requested": 3,
    "succeeded": 3,
    "failed": 0,
    "results": [
      { "url": "https://...", "ok": true, "content": "...", "cache_hit": false, "latency_ms": 1200 },
      { "url": "https://...", "ok": true, "content": "...", "cache_hit": true,  "latency_ms": 0 },
      { "url": "https://...", "ok": false, "error": { "code": "TLS_ERROR", "message": "..." } }
    ]
  },
  "meta": { "latency_ms": 4100, "quota": { "credits_estimated": 3 } }
}

---

agentproxy_extract

Extract structured fields from any URL using heuristic pattern matching (meta tags, Open Graph, JSON-LD, Schema.org). Lightweight — no LLM needed. Set render_fallback: true to automatically retry via real Chromium if the proxy fetch fails.

Response:

{
  "ok": true,
  "tool": "agentproxy_extract",
  "data": {
    "url": "https://books.toscrape.com/...",
    "fields": { "title": "A Light in the Attic", "price": "£51.77", "description": null },
    "extracted_via": "proxy_fetch"
  },
  "meta": { "latency_ms": 2100, "quota": { "credits_estimated": 1 } }
}

---

agentproxy_map

Crawl a URL and return all internal links as a structured JSON array. Use as the discovery step before agentproxy_batch_fetch to crawl an entire site without guessing URLs.

Response:

{
  "ok": true,
  "tool": "agentproxy_map",
  "data": {
    "domain": "books.toscrape.com",
    "internal_url_count": 20,
    "internal_urls": ["https://books.toscrape.com/catalogue/...", "..."],
    "sitemap_hint": "https://books.toscrape.com/sitemap.xml (check manually)"
  },
  "meta": { "latency_ms": 3800, "quota": { "credits_estimated": 1 } }
}

---

agentproxy_session

Sticky session fetch — every call with the same session_id uses the same residential IP. Essential for login flows, paginated scraping, and price monitoring. Supports verify_sticky: true to confirm IP consistency before relying on it.

---

agentproxy_search

Structured Google search via Novada Scraper API. Returns titles, URLs, and snippets as clean JSON — no HTML parsing needed.

---

agentproxy_render [BETA]

Render JavaScript-heavy pages using Novada's Browser API (real Chromium, full JS execution). Use for SPAs, React/Vue apps, and pages that return blank with a standard HTTP fetch.

Requires: NOVADA_BROWSER_WS — copy the Puppeteer URL from Dashboard → Browser API → Playground

Costs ~5 proxy credits per call vs 1 for agentproxy_fetch. Use agentproxy_extract with render_fallback: true for automatic escalation when needed.

---

agentproxy_status

Check proxy network connectivity and version. Makes a live proxy call to verify the connection is working. No credentials required.

---

Agent Workflows

Site crawl pipeline (map → batch)

# Agent task: "Read all products on this catalogue"
1. agentproxy_map(url="https://books.toscrape.com", limit=50)
   → returns 20–50 internal URLs in 4s, 1 credit

2. agentproxy_batch_fetch(urls=[...20 URLs], concurrency=5)
   → fetches all 20 pages in parallel, ~4s wall time, 20 credits
   (vs ~60s sequential = 15x speedup)

Research pipeline (search → batch)

# Agent task: "Find and read top 5 pages about X"
1. agentproxy_search(query="residential proxy MCP", num=5)
   → structured JSON: titles, URLs, snippets

2. agentproxy_batch_fetch(urls=[...5 URLs], format="markdown")
   → full content of all 5 pages in parallel

Sticky session — login + multi-page scrape

# Same IP across all calls
agentproxy_session(session_id="job_001", url="https://example.com/login")
agentproxy_session(session_id="job_001", url="https://example.com/dashboard")
agentproxy_session(session_id="job_001", url="https://example.com/data/page/1")
agentproxy_session(session_id="job_001", url="https://example.com/data/page/2")

Price monitoring — same product, three markets

agentproxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="US")
agentproxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="DE")
agentproxy_fetch(url="https://amazon.com/dp/B0BSHF7WHW", country="JP")
# Second call per URL is a cache hit (0ms, 0 credits) if within 300s TTL

Extract structured data

# Agent task: "Get product details without parsing HTML"
agentproxy_extract(
  url="https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
  fields=["title", "price", "description", "rating"],
  render_fallback=true  # auto-retry via Chromium if proxy gets blocked
)

---

Response Cache

All agentproxy_fetch and agentproxy_batch_fetch calls are cached in-process. Repeated fetches to the same URL within the TTL window consume zero proxy credits.

Reading cache status from response:

"meta": {
  "cache_hit": true,          // served from cache — no proxy credit used
  "cache_age_seconds": 12,    // seconds since the entry was stored
  "latency_ms": 0             // ~0ms for cache hits
}

---

Typed Error Codes

Every error response includes a typed error.code, recoverable flag, and agent_instruction with the correct next step. Agents never need to parse error messages.

Error response format:

{
  "ok": false,
  "error": {
    "code": "BOT_DETECTION_SUSPECTED",
    "message": "HTTP 403 — request blocked by target",
    "recoverable": true,
    "agent_instruction": "Try agentproxy_render (real browser). Or retry with a different country/session_id."
  }
}

---

Geo Coverage

195+ countries including:

US GB DE FR JP CA AU BR IN KR SG NL IT ES MX RU PL SE NO DK FI CH AT BE PT CZ HU RO UA TR IL ZA NG EG AR CL CO PE VN TH ID MY PH TW HK NZ + 148 more

City-level targeting: newyork · losangeles · chicago · london · paris · berlin · tokyo · seoul · sydney · toronto · singapore · dubai · mumbai · saopaulo

---

Compatible With

---

Network

---

Confirmed Working

E-commerce: Amazon, eBay, Walmart, Etsy, Shopify stores
Professional: LinkedIn
Anti-bot protected: Cloudflare, Akamai, DataDome
News & content: HackerNews, Reddit, BBC, CNN, NYTimes
Tech: GitHub, Wikipedia, Stack Overflow, IMDB

---

Known Limitations

• Sites requiring full JS execution → use agentproxy_render
• agentproxy_render requires NOVADA_BROWSER_WS (separate Novada Browser API subscription)
• Session IDs must not contain hyphens (Novada uses - as its auth delimiter)
• Sticky sessions are best-effort infrastructure — use verify_sticky: true to confirm before relying on them
• API-protected sites (ip-api.com, similar) block proxy IP ranges — agentproxy_render may help

---

Feedback & Support

• Email: tong.wu@novada.com
• GitHub Issues: github.com/NovadaLabs/proxy4agent/issues
• Website: novada.com

---

License

MIT © Novada — see LICENSE

---

---

Proxy4Agents MCP（中文文档）

AI 智能体的住宅代理 MCP 服务器。 通过 200 万+ 真实家庭设备（Android 手机、Windows 电脑、Mac）路由 HTTP 请求，绕过反机器人系统，按国家/城市精准定位，跨请求保持同一 IP。

支持 Claude Code、Cursor、Windsurf、Cline、Continue 及所有 MCP 兼容智能体。由 Novada 提供支持。

---

8 个工具

agentproxy_fetch       → 通过住宅代理抓取任意 URL
agentproxy_batch_fetch → 并发抓取 2-20 个 URL（最高 5 倍加速）
agentproxy_extract     → 从页面提取结构化字段（标题、价格、评分…）
agentproxy_map         → 爬取页面，返回所有内部链接 JSON 数组
agentproxy_session     → 粘性会话 — 同一 session_id 始终同一 IP
agentproxy_search      → Google 搜索，返回结构化 JSON（无需解析 HTML）
agentproxy_render      → 真实 Chromium 渲染 JS 页面 [BETA]
agentproxy_status      → 检查代理网络健康状态

---

工具选择决策树

目标：抓取单个 URL
  ├─ 静态 HTML 页面？            → agentproxy_fetch
  ├─ 需要特定字段（价格/标题）？  → agentproxy_extract
  └─ React/Vue SPA / 内容为空？  → agentproxy_render

目标：批量抓取多个 URL
  ├─ 已有 URL 列表？             → agentproxy_batch_fetch
  └─ 需要先发现 URL？            → agentproxy_map → agentproxy_batch_fetch

目标：网页搜索                   → agentproxy_search → agentproxy_batch_fetch

目标：登录 + 多步骤流程           → agentproxy_session（相同 session_id）

目标：验证代理是否正常工作        → agentproxy_status

---

三大流水线模式

全站爬取流水线（推荐）

agentproxy_map(url, limit=50)
        │
        ▼
  返回 20-50 个内部链接（1 credit，4 秒）
        │
        ▼
agentproxy_batch_fetch(urls, concurrency=5)
        │
        ▼
  并发抓取所有页面（N credits，~4 秒，比串行快 15x）

搜索研究流水线

agentproxy_search(query, num=10)
        │
        ▼
  结构化 JSON：标题 + URL + 摘要
        │
        ▼
agentproxy_batch_fetch(urls, format="markdown")
        │
        ▼
  全部页面内容并行返回

粘性会话 — 登录 + 多页抓取

session_id = "job_001"

agentproxy_session(session_id, url="/login")    → 同一 IP
agentproxy_session(session_id, url="/dashboard") → 同一 IP
agentproxy_session(session_id, url="/data/1")    → 同一 IP
agentproxy_session(session_id, url="/data/2")    → 同一 IP

---

核心特性

1. 住宅 IP 网络

• 200 万+ 真实设备：Android 手机、Windows 电脑、Mac
• 7,000+ 活跃节点，99.9% 在线率
• 真实家庭 IP 指纹，绕过 Cloudflare、Akamai、DataDome 检测

2. 地理定向

• 195+ 国家，两字母 ISO 代码（US、DE、JP、BR…）
• 城市级定位：newyork、london、tokyo、singapore…
• 同一 URL 不同国家 = 独立缓存键，互不干扰

3. 响应缓存

重复抓取相同 URL 不消耗代理额度：

// 第一次调用（live fetch）
"meta": { "cache_hit": false, "latency_ms": 1800, "quota": { "credits_estimated": 1 } }

// 第二次调用（cache hit）
"meta": { "cache_hit": true, "cache_age_seconds": 5, "latency_ms": 0 }

4. 智能体优先的 JSON 输出

所有工具返回统一结构：

{
  "ok": true / false,
  "tool": "工具名称",
  "data": { ... },
  "meta": {
    "latency_ms": 1800,
    "cache_hit": false,
    "quota": { "credits_estimated": 1 }
  }
}

5. 类型化错误码 + 恢复指令

每个错误都包含 code（枚举）、recoverable（布尔）、agent_instruction（下一步操作）：

{
  "ok": false,
  "error": {
    "code": "BOT_DETECTION_SUSPECTED",
    "recoverable": true,
    "agent_instruction": "Try agentproxy_render (real browser). Or retry with a different country/session_id."
  }
}

6. 批量并发抓取

agentproxy_batch_fetch 内置信号量并发控制：

// 10 个 URL，concurrency=5，wall time = ~8.8s（串行估计 ~50s）
{
  "data": {
    "results": [
      { "url": "...", "ok": true, "cache_hit": false, "latency_ms": 1200 },
      { "url": "...", "ok": true, "cache_hit": true,  "latency_ms": 0 },
      { "url": "...", "ok": false, "error": { "code": "TLS_ERROR" } }
    ]
  },
  "meta": { "latency_ms": 8800, "quota": { "credits_estimated": 10 } }
}

7. 多供应商支持

8. 渐进式降级（render_fallback）

agentproxy_extract 支持自动升级到浏览器渲染：

代理抓取失败（TLS / Bot检测）
        │
        ▼ render_fallback=true
agentproxy_render（真实 Chromium）
        │
        ▼
data.extracted_via = "render"  （agent 知道走了哪条路径）
data.fetch_warning = "Proxy fetch failed... escalated to render"

---

快速安装

# 核心（住宅代理抓取）
claude mcp add bestproxy4agents-mcp \
  -e NOVADA_PROXY_USER=你的用户名 \
  -e NOVADA_PROXY_PASS=你的密码 \
  -- npx -y bestproxy4agents-mcp

# 仅搜索
claude mcp add bestproxy4agents-mcp \
  -e NOVADA_API_KEY=你的_API_Key \
  -- npx -y bestproxy4agents-mcp

# 全功能（代理 + 搜索 + 浏览器渲染）
claude mcp add bestproxy4agents-mcp \
  -e NOVADA_PROXY_USER=你的用户名 \
  -e NOVADA_PROXY_PASS=你的密码 \
  -e NOVADA_API_KEY=你的_API_Key \
  -e NOVADA_BROWSER_WS=你的_Browser_WS_URL \
  -- npx -y bestproxy4agents-mcp

获取凭证：novada.com → 仪表盘 → 住宅代理 → 端点生成器

Cursor / Windsurf / Cline 配置：

{
  "mcpServers": {
    "bestproxy4agents-mcp": {
      "command": "npx",
      "args": ["-y", "bestproxy4agents-mcp"],
      "env": {
        "NOVADA_PROXY_USER": "你的用户名",
        "NOVADA_PROXY_PASS": "你的密码"
      }
    }
  }
}

---

工具参数速查

agentproxy_fetch

agentproxy_batch_fetch

agentproxy_extract

agentproxy_map

agentproxy_session

agentproxy_search

agentproxy_render [BETA]

---

使用场景

AI 智能体需要：

• 抓取电商网站（Amazon、eBay、Walmart）不被封锁
• 跨国家监控价格变动
• 访问 195+ 国家的地区限制内容
• 对 Cloudflare/Akamai 保护站点进行竞争情报收集
• 执行多步登录流程并保持同一 IP
• 渲染无真实浏览器就返回空白的 JS 页面
• Google 搜索返回结构化 JSON 结果

开发者构建：

• AI 驱动的网页研究工具
• 价格比较智能体
• 全站内容爬取管道
• SEO 监控仪表盘
• 市场调研自动化

---

已验证可用

电商： Amazon、eBay、Walmart、Etsy、Shopify
职业网络： LinkedIn
反机器人保护： Cloudflare 站点、Akamai、DataDome
新闻内容： HackerNews、Reddit、BBC、CNN、NYTimes
科技： GitHub、Wikipedia、Stack Overflow、IMDB

---

反馈与支持

• 邮箱： tong.wu@novada.com
• GitHub Issues： github.com/NovadaLabs/proxy4agent/issues
• 官网： novada.com

---

许可证

MIT © Novada